[DOCS] Improve onboarding flow for APM / distributed systems users

[kylehounslow]

Problem

The current docs site (observability.opensearch.org) does a good job covering the platform's capabilities, but the onboarding flow is optimized primarily for the AI agent observability persona. Users coming from a traditional APM background — monitoring distributed systems with traces, logs, metrics, and service maps — hit friction points that make it harder to reach their "aha moment."

This issue proposes targeted improvements to the getting-started flow for APM users, based on a page-by-page walkthrough of the current site.

Persona: APM / Distributed Systems User

Who: Backend or platform engineer with a microservices architecture. Looking for distributed tracing, log correlation, service maps, RED metrics, and dashboards. Agent tracing may exist in their stack but isn't their primary concern.

Goal: Install the stack → instrument their app → see traces and service maps in dashboards.

Audit Findings

1. "First Traces" quickstart is too thin

The Ingest Your First Traces page is the critical onboarding moment, but currently:

• Python-only, no language tabs (Java, Node.js, Go)
• Uses manual instrumentation only — no mention of auto-instrumentation, which is the 80% path for APM users
• No screenshots showing what the user should see in Dashboards
• No verification step ("how do I know it worked?")
• No connection to APM features — next steps jump to dashboards and agent tracing, skipping service maps entirely

2. No guided path from first traces → service map → log correlation

After seeing their first trace, an APM user's natural next question is "where's my service map?" and "can I correlate this with my logs?" There's no quickstart or tutorial that connects these steps. The APM section and Investigate section have good reference docs, but no guided walkthrough tying them together.

3. OTel Demo is underutilized as an onboarding asset

The OpenTelemetry Demo integration is a powerful APM onboarding tool — it's a full microservices e-commerce app generating realistic HTTP/gRPC/Kafka traces. Currently it's mentioned as a sub-section under "Example services" on the Installation page. For APM users, this could be a first-class quickstart: "uncomment one line, restart, explore a real distributed system."

4. Landing page quickstarts are agent-focused

The three quickstart cards on the landing page are:

1. Install & Explore
2. Send Your First Traces
3. Trace an AI Agent

There's no APM-specific quickstart (e.g., "Explore the Service Map" or "Monitor a Distributed App"). An APM user scanning the landing page may not see a clear path for their use case.

5. APM section lacks a getting-started entry point

The Application Monitoring page is solid reference documentation, but doesn't acknowledge that users who installed with default settings already have trace data flowing. A short "Getting started" section at the top ("If you installed with example services or the OTel Demo, open Dashboards and navigate to...") would reduce time-to-value significantly.

6. Auto-instrumentation is not linked from the quickstart flow

The Auto-Instrumentation page is comprehensive (Python, Java, Node.js, Go, .NET, Ruby) but is 3 clicks deep from the getting-started path. The first-traces quickstart doesn't reference it at all.

Proposed Changes

Roughly ordered by impact:

P0 — First traces quickstart rewrite

• Add language tabs (Python, Java, Node.js at minimum)
• Lead with auto-instrumentation as the primary path, manual as secondary
• Add screenshots of the trace view in OpenSearch Dashboards
• Add a verification step
• Update "Next steps" to include Application Monitoring / service map

P0 — New quickstart: "Explore Application Monitoring"

• Short page: open Dashboards → navigate to Application Monitoring → see the service map and RED metrics
• Works with either the built-in example services or OTel Demo
• Screenshots of service map, services catalog, and service detail

P1 — Elevate OTel Demo as an APM quickstart

• Either a dedicated quickstart page or a more prominent callout on the installation page
• Frame it as "explore a realistic distributed system" rather than just an optional add-on

P1 — Landing page: add APM quickstart path

• Replace or supplement the third quickstart card with an APM-focused option
• Alternatively, use a 2×2 grid: Install, First Traces, Application Monitoring, Agent Tracing

P2 — APM index page: add getting-started section

• Short section at the top for users who already have the stack running
• "You already have trace data — here's where to find it"

P2 — Link auto-instrumentation from quickstart

• Add a callout or link in the first-traces quickstart pointing to auto-instrumentation
• Consider making auto-instrumentation the default code example

Context

This is part of a broader effort to define clear onboarding paths for different user personas. A follow-up issue will cover the Agent Developer persona (agent tracing in OSD + evaluation with AgentHealth).