APM onboarding: Set Up APM + K8s SSI rewrite w/ Agent Execution Context

config/_default/menus/main.en.yaml

@@ -4284,7 +4284,7 @@ menu:
       parent: tracing
       identifier: tracing_glossary
       weight: 1
-    - name: Application Instrumentation
+    - name: Set Up APM
       url: tracing/trace_collection/
       parent: tracing
       identifier: tracing_trace_collection

content/en/tracing/trace_collection/_index.md

@@ -1,6 +1,6 @@
 ---
-title: Application Instrumentation
-description: "Get Started with Datadog APM"
+title: Set Up APM
+description: "Set up Datadog APM to collect traces from your applications. Choose Single Step Instrumentation for automatic setup on Kubernetes, Linux, Docker, or Windows, or use manually managed SDKs for full configuration control."
 aliases:
     - /tracing/setup
     - /tracing/send_traces/
@@ -31,148 +31,55 @@ algolia:
 ---
 
 ## Overview
-Application {{< tooltip glossary="instrumentation" >}} with Datadog APM involves:
 
-1. **SDK setup**: Adding a Datadog SDK to your application.
-2. **Span creation**: Capturing observability data as {{< tooltip glossary="span" >}}s.
+Set up Datadog APM to collect traces from your applications. [Single Step Instrumentation][1] (SSI) is the recommended approach for most users. It automatically installs and configures Datadog SDKs with no code changes required.
 
-   Spans are automatically generated by default as soon as the SDK is loaded. This is known as **auto-instrumentation** and provides sufficient visibility for most users. If you need more control, you can optionally add custom spans.
-
-**Note**: These steps assume you have a [Datadog Agent][5] installed and configured to receive traces.
-
-{{< img src="tracing/visualization/troubleshooting_pipeline.png" alt="The APM pipeline">}}
-
-## Getting started
+## Get APM running
 
 <div class="alert alert-info">
 <strong>Prefer vendor-neutral instrumentation?</strong> See the <a href="/opentelemetry/">OpenTelemetry documentation</a> for using OpenTelemetry with Datadog.
 </div>
 
-### Single step instrumentation (recommended)
-
-[Single Step Instrumentation][1] (SSI) automatically installs and configures Datadog SDKs with a single command. Auto-instrumentation then immediately begins capturing traces from your supported frameworks and libraries, with no code changes required.
+SSI automatically installs and loads Datadog SDKs into your application processes at runtime with a single command. Pick your platform to get started:
 
 {{< whatsnext desc=" " >}}
-    {{< nextlink href="/tracing/trace_collection/single-step-apm/" >}}Get started with Single Step Instrumentation{{< /nextlink >}}
+    {{< nextlink href="/tracing/trace_collection/single-step-apm/kubernetes" >}}Kubernetes{{< /nextlink >}}
+    {{< nextlink href="/tracing/trace_collection/single-step-apm/linux" >}}Linux{{< /nextlink >}}
+    {{< nextlink href="/tracing/trace_collection/single-step-apm/docker" >}}Docker{{< /nextlink >}}
+    {{< nextlink href="/tracing/trace_collection/single-step-apm/windows" >}}Windows IIS{{< /nextlink >}}
 {{< /whatsnext >}}
 
-### Manual setup and custom spans
-
-As your observability needs grow, you can add more control and customization:
+## Need more control?
 
-**For full SDK configuration control:** Use [manually managed Datadog SDKs][2] if you need granular control over SDK behavior and configuration.
+If you need full control over SDK configuration and installation, use [manually managed Datadog SDKs][2]. This approach requires adding the SDK to your application code or build process.
 
 {{< whatsnext desc=" " >}}
-    {{< nextlink href="/tracing/trace_collection/dd_libraries/" >}}Use manually managed Datadog SDKs{{< /nextlink >}}
+    {{< nextlink href="/tracing/trace_collection/dd_libraries/" >}}Set up manually managed SDKs{{< /nextlink >}}
 {{< /whatsnext >}}
 
-**For custom spans without code changes:** Use [Dynamic Instrumentation][4] to create custom spans from the Datadog UI without redeploying your application.
+## Add custom spans
 
-{{< whatsnext desc=" " >}}
-    {{< nextlink href="/tracing/trace_collection/dynamic_instrumentation/" >}}Add custom spans with Dynamic Instrumentation{{< /nextlink >}}
-{{< /whatsnext >}}
+After you have APM running, you can add custom spans for visibility into application-specific code paths:
 
-**For custom spans in code:** Add [code-based custom instrumentation][3] to instrument custom business logic or add application-specific metadata to spans.
+- **Without code changes**: Use [Dynamic Instrumentation][4] to create custom spans from the Datadog UI without redeploying your application.
+- **In code**: Add [code-based custom instrumentation][3] to instrument custom business logic or add application-specific metadata to spans.
 
 {{< whatsnext desc=" " >}}
+    {{< nextlink href="/tracing/trace_collection/dynamic_instrumentation/" >}}Add custom spans with Dynamic Instrumentation{{< /nextlink >}}
     {{< nextlink href="/tracing/trace_collection/custom_instrumentation/" >}}Add custom spans with code-based instrumentation{{< /nextlink >}}
 {{< /whatsnext >}}
 
-These options can be combined. For example, you can start with Single Step Instrumentation and add code-based custom instrumentation for specific spans, or use manually managed SDKs with Dynamic Instrumentation for no-deploy span additions.
-
-## Detailed comparison
-
-### SDK setup
-
-Single Step Instrumentation is the recommended starting point for most users. If you need more control over SDK configuration, you can use manually managed SDKs instead:
-
-<table style="width:100%; border-collapse:collapse; border:2px solid #999;">
-  <tr style="background-color:#f2f2f2;">
-    <th style="border:1px solid #ccc;"></th>
-    <th style="border:1px solid #ccc; font-weight:bold;"><a href="/tracing/trace_collection/single-step-apm/">Single Step Instrumentation</a> (recommended)</th>
-    <th style="border:1px solid #ccc; font-weight:bold;"><a href="/tracing/trace_collection/dd_libraries/">Manually managed SDKs</a></th>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">How it works</td>
-    <td style="border:1px solid #ccc;">Datadog automatically installs and loads SDKs into your application processes, at runtime, with a single command.</td>
-    <td style="border:1px solid #ccc;">You install and configure SDKs directly in your application code or build process.</td>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">Code changes?</td>
-    <td style="border:1px solid #ccc;">No</td>
-    <td style="border:1px solid #ccc;">Yes</td>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">Setup complexity</td>
-    <td style="border:1px solid #ccc;">Low - minimal configuration needed</td>
-    <td style="border:1px solid #ccc;">Medium - requires environment and build configuration</td>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">Configuration control</td>
-    <td style="border:1px solid #ccc;">Standard defaults with optional overrides</td>
-    <td style="border:1px solid #ccc;">Full control through environment variables and code</td>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">When to use</td>
-    <td style="border:1px solid #ccc;">Start here for fast, consistent instrumentation across services without code changes.</td>
-    <td style="border:1px solid #ccc;">Progress to this when you need granular control over SDK behavior and configuration.</td>
-  </tr>
-</table>
-
-### Span customization
-
-Auto-instrumentation automatically creates spans for supported frameworks and libraries, providing essential observability with no additional work. When you need visibility into custom code paths or want to enrich traces with application-specific data, you can add custom spans using either Dynamic Instrumentation or code-based custom instrumentation:
-
-<table style="width:100%; border-collapse:collapse; border:2px solid #999;">
-  <tr style="background-color:#f2f2f2;">
-    <th style="border:1px solid #ccc;"></th>
-    <th style="border:1px solid #ccc; font-weight:bold;"><a href="/tracing/trace_collection/dynamic_instrumentation/">Dynamic Instrumentation</a></th>
-    <th style="border:1px solid #ccc; font-weight:bold;"><a href="/tracing/trace_collection/custom_instrumentation/">Code-based custom instrumentation</a></th>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">How it works</td>
-    <td style="border:1px solid #ccc;">Configure instrumentation rules in the Datadog UI; rules are applied at runtime.</td>
-    <td style="border:1px solid #ccc;">Add explicit tracing API calls in your application code.</td>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">Code changes?</td>
-    <td style="border:1px solid #ccc;">No</td>
-    <td style="border:1px solid #ccc;">Yes</td>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">Deployment required</td>
-    <td style="border:1px solid #ccc;">No</td>
-    <td style="border:1px solid #ccc;">Yes (to add or modify spans)</td>
-  </tr>
-  <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">When to use</td>
-    <td style="border:1px solid #ccc;">Add custom spans without code changes or redeployments.</td>
-    <td style="border:1px solid #ccc;">Progress to this when you need complex instrumentation logic or want spans permanently defined in code.</td>
-  </tr>
-</table>
-
-## APM setup tutorials
-
-The following tutorials guide you through setting up distributed tracing for a sample application on various infrastructure scenarios, with both automatic and custom instrumentation:
-
-{{< whatsnext desc="Choose your language and environment:" >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-python-host" >}}<img src="/images/integrations_logos/python-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-host-icon.png" /> Enabling Tracing on a Python Application on the Same Host as Datadog Agent{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-python-containers" >}}<img src="/images/integrations_logos/python-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-container-icon.png" /> Enabling Tracing on a Python Application and Datadog Agent in Containers{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-python-container-agent-host" >}}<img src="/images/integrations_logos/python-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-container-icon.png" /> <img src="/images/tracing/guide/tutorials/tutorial-host-icon.png" /> Enabling Tracing for a Python Application in a Container and an Agent on a Host{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-java-host" >}}<img src="/images/integrations_logos/java-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-host-icon.png" /> Enabling Tracing on a Java Application on the Same Host as Datadog Agent{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-java-containers" >}}<img src="/images/integrations_logos/java-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-container-icon.png" /> Enabling Tracing on a Java Application and Datadog Agent in Containers{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-java-container-agent-host" >}}<img src="/images/integrations_logos/java-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-container-icon.png" /> <img src="/images/tracing/guide/tutorials/tutorial-host-icon.png" /> Enabling Tracing for a Java Application in a Container and an Agent on a Host{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-java-gke" >}}<img src="/images/integrations_logos/java-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-gke-icon.png" /> Enabling Tracing for a Java Application on GKE{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-java-aws-eks" >}}<img src="/images/integrations_logos/java-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-eks-icon.png" /> Enabling Tracing for a Java Application on Amazon EKS{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-java-aws-ecs-ec2" >}}<img src="/images/integrations_logos/java-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-ec2-icon.png" /> Enabling Tracing for a Java Application in Amazon ECS with EC2{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-java-aws-ecs-fargate" >}}<img src="/images/integrations_logos/java-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-fargate-icon.png" /> Enabling Tracing for a Java Application in Amazon ECS with Fargate{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-java-admission-controller" >}}<img src="/images/integrations_logos/java-avatar.png" /> Enabling Tracing for a Java Application with the Admission Controller{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-go-host" >}}<img src="/images/integrations_logos/golang-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-host-icon.png" /> Enabling Tracing on a Go Application on the Same Host as Datadog Agent{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-go-containers" >}}<img src="/images/integrations_logos/golang-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-container-icon.png" /> Enabling Tracing on a Go Application and Datadog Agent in Containers{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-go-aws-ecs-ec2" >}}<img src="/images/integrations_logos/golang-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-ec2-icon.png" /> Enabling Tracing for a Go Application in Amazon ECS with EC2{{< /nextlink >}}
-    {{< nextlink href="tracing/guide/tutorial-enable-go-aws-ecs-fargate" >}}<img src="/images/integrations_logos/golang-avatar.png" /> <img src="/images/tracing/guide/tutorials/tutorial-fargate-icon.png" /> Enabling Tracing for a Go Application in Amazon ECS with Fargate{{< /nextlink >}}
+{{< agent-only >}}
+If a user asks to set up APM, tracing, or distributed tracing, start with Single Step Instrumentation (SSI) unless they specifically request manual SDK control.
 
-{{< /whatsnext >}}
+First, ask what language they're using. If the language is Go, C++, or Rust, SSI is not available — direct them to manually managed SDKs at /tracing/trace_collection/dd_libraries/.
+
+Then ask what platform they're running on:
+- Kubernetes → /tracing/trace_collection/single-step-apm/kubernetes
+- Linux host or VM → /tracing/trace_collection/single-step-apm/linux
+- Docker → /tracing/trace_collection/single-step-apm/docker
+- Windows IIS → /tracing/trace_collection/single-step-apm/windows
+{{< /agent-only >}}
 
 ## Further reading
 
@@ -182,5 +89,3 @@ The following tutorials guide you through setting up distributed tracing for a s
 [2]: /tracing/trace_collection/dd_libraries/
 [3]: /tracing/trace_collection/custom_instrumentation/
 [4]: /tracing/trace_collection/dynamic_instrumentation/
-[5]: /agent/
-

content/en/tracing/trace_collection/single-step-apm/_index.md

@@ -1,5 +1,6 @@
 ---
 title: Single Step APM Instrumentation
+description: "Automatically instrument applications with Datadog APM using Single Step Instrumentation (SSI). Install the Datadog Agent and enable tracing with no code changes on Kubernetes, Linux, Docker, or Windows."
 aliases:
 - /tracing/trace_collection/admission_controller/
 - /tracing/trace_collection/library_injection_local/
@@ -11,7 +12,7 @@ further_reading:
   - link: /tracing/guide/injectors
     tag: Documentation
     text: Understanding injector behavior with Single Step Instrumentation
-  - link: /tracing/trace_collection/automatic_instrumentation/single-step-apm/troubleshooting/
+  - link: /tracing/trace_collection/single-step-apm/troubleshooting/
     tag: Documentation
     text: "Troubleshooting Single Step APM"
   - link: https://learn.datadoghq.com/courses/troubleshooting-apm-instrumentation-on-a-host
@@ -70,16 +71,16 @@ If you encounter problems enabling APM with SSI, see the [SSI troubleshooting gu
 [3]: /internal_developer_portal/catalog/
 [4]: /tracing/glossary/#instrumentation
 [5]: /containers/cluster_agent/admission_controller/
-[6]: /tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility
+[6]: /tracing/trace_collection/single-step-apm/compatibility
 [7]: /tracing/trace_collection/custom_instrumentation/
 [8]: /tracing/guide/injectors
-[9]: /tracing/trace_collection/automatic_instrumentation/single-step-apm/kubernetes/?tab=installingwithdatadogoperator#configure-instrumentation-for-namespaces-and-pods
+[9]: /tracing/trace_collection/single-step-apm/kubernetes/?tab=installingwithdatadogoperator#configure-instrumentation-for-namespaces-and-pods
 [10]: /tracing/trace_collection/library_config/
 [11]: /tracing/metrics/runtime_metrics/
 [12]: /internal_developer_portal/catalog/
 [13]: /tracing/glossary/#instrumentation
 [14]: /getting_started/tagging/unified_service_tagging
-[15]: /tracing/trace_collection/automatic_instrumentation/single-step-apm/troubleshooting
+[15]: /tracing/trace_collection/single-step-apm/troubleshooting
 [16]: /tracing/trace_collection/custom_instrumentation/
 [17]: /tracing/trace_collection/library_config/application_monitoring_yaml/
-[18]: /tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility/
+[18]: /tracing/trace_collection/single-step-apm/compatibility/