APM SSI: agentic onboarding rewrite

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,149 +31,44 @@ 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{{< /nextlink >}}
 {{< /whatsnext >}}
 
-### Manual setup and custom spans
+## Need more control?
 
-As your observability needs grow, you can add more control and customization:
-
-**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 >}}
-
-{{< /whatsnext >}}
-
 ## Further reading
 
 {{< partial name="whats-next/whats-next.html" >}}
@@ -182,5 +77,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
@@ -29,21 +30,21 @@ further_reading:
 ---
 ## Overview
 
-Single Step Instrumentation (SSI) automatically installs the Datadog SDKs with no additional configuration required, reducing onboarding time from days to minutes.
+Single Step Instrumentation (SSI) automatically installs the Datadog SDKs into your applications with no code changes or additional configuration required.
 
-To learn more about how it works, see the [injector guide for Single Step Instrumentation][8].
+To learn more about how it works, see the [injector guide for Single Step Instrumentation][2].
 
 ## Prerequisites
 
-1. Remove any custom instrumentation code from your application and restart it. SSI is automatically disabled if custom instrumentation is detected.
-1. Confirm environment compatibility by reviewing the [SSI compatibility guide][18] for supported languages, operating systems, and architectures.
+1. Check whether the application already loads a tracing SDK. Remove or disable only conflicting tracer initialization before enabling SSI, then restart the application. You can keep custom spans and non-tracing OpenTelemetry dependencies.
+1. Confirm environment compatibility by reviewing the [SSI compatibility guide][5] for supported languages, operating systems, and architectures.
 
 ## Instrument SDKs across applications
 
 When you [install or update the Datadog Agent][1] with {{< ui >}}APM Instrumentation{{< /ui >}} enabled, the Agent instruments your applications by loading the Datadog SDK into supported processes. This enables distributed tracing by capturing and sending trace data from your services without requiring code changes.
 
 After instrumentation, you can optionally:
-- [configure Unified Service Tags (USTs)][14]
+- [configure Unified Service Tags (USTs)][3]
 - enable additional SDK-dependent products and features, such as Continuous Profiler or Application Security Monitoring
 
 Click on one of the following tiles to learn how to set up SSI for your deployment type:
@@ -59,27 +60,14 @@ Click on one of the following tiles to learn how to set up SSI for your deployme
 
 ## Troubleshooting
 
-If you encounter problems enabling APM with SSI, see the [SSI troubleshooting guide][15].
+If you encounter problems enabling APM with SSI, see the [SSI troubleshooting guide][4].
 
 ## Further reading
 
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: https://app.datadoghq.com/account/settings/agent/latest
-[2]: /tracing/metrics/runtime_metrics/
-[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
-[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
-[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
-[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/
+[2]: /tracing/guide/injectors
+[3]: /getting_started/tagging/unified_service_tagging
+[4]: /tracing/trace_collection/single-step-apm/troubleshooting
+[5]: /tracing/trace_collection/single-step-apm/compatibility/