Instrumentation landing page rework

content/en/tracing/trace_collection/_index.md

@@ -31,100 +31,174 @@
 
 To get started with Datadog APM, you need to follow these key steps:
 
-1. Install and configure the Datadog Agent.  
-2. Instrument your application.
+1. Install and configure the Datadog Agent.
+2. Add the Datadog tracing SDK to your application.
+3. Instrument your application to create spans.
 
-<div class="alert alert-info"><strong>Simplify your setup!</strong> Install the Agent and instrument your application in one step with <a href="https://docs.datadoghq.com/tracing/trace_collection/single-step-apm/">Single Step Instrumentation</a>.</div>
+<div class="alert alert-info">
+<strong>Simplify your setup!</strong> 
+Use <a href="https://docs.datadoghq.com/tracing/trace_collection/single-step-apm/">Single Step Instrumentation</a> to complete these steps in one command.
+</div>
 
-Instrumenting your application allows observability data to be sent to the Agent, which then passes data to the Datadog backend to display in the UI.
+Instrumenting your application creates spans that are sent to the Datadog Agent, which forwards trace data to the Datadog backend for visualization and analysis.
 
 {{< img src="tracing/visualization/troubleshooting_pipeline.png" alt="The APM pipeline">}}
 
+## Instrumentation model 
 
-## Instrumentation types
+<div class="alert alert-info">
+If you prefer vendor-neutral instrumentation, see the <a href="https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/otel_instrumentation/">OpenTelemetry documentation</a> for using OpenTelemetry API support in Datadog libraries.
+</div>
 
-There are two main approaches to {{< tooltip glossary="instrument" >}} your application:
+At a high level, {{< tooltip glossary="instrument" >}}ing an application with Datadog APM involves two actions:
 
-**Automatic instrumentation** creates {{< tooltip glossary="span" >}}s for your application with minimal manual steps, capturing essential observability data across common libraries and languages with minimal configuration.
+1. Adding the Datadog language SDKs to your application.
+2. Creating {{< tooltip glossary="span" >}}s to capture observability data.
 
-**Custom instrumentation** captures observability data from in-house code or complex functions that aren't captured by automatic instrumentation, providing deeper visibility and context into spans when you need fine-grained control.
+Datadog language SDKs automatically create spans for supported frameworks and libraries. In many cases, this automatic instrumentation is sufficient. When you need more control, you can add custom instrumentation.
 
-The following table compares the different instrumentation methods available.
 
-<div class="alert alert-info">
-If you prefer vendor-neutral instrumentation, see the <a href="https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/otel_instrumentation/">OpenTelemetry documentation</a> for using OpenTelemetry API support in Datadog libraries.
-</div>
+### Adding Datadog language SDKs
+
+Datadog language SDKs can be added to your application in the following ways:
+
+- **Single Step Instrumentation (SSI)**: Automatically installs and loads Datadog language SDKs at runtime.
+- **Manual installation**: Install and configure the Datadog language SDKs directly in your application.
+
+
+### Creating spans
+
+After Datadog language SDKs are available, spans can be created in the following ways:
+
+- **Automatic instrumentation**: Datadog language SDKs automatically create spans to capture essential observability data across common libraries and languages.
+- **Custom instrumentation**: Add spans for custom code paths or specialized logic. You can create custom spans in two ways:
+  - **Code-based custom instrumentation**: Use the Datadog tracing APIs in your application code.
+  - **Dynamic Instrumentation (UI-based custom instrumentation)**: Add spans at runtime using configuration in the Datadog UI, without modifying application code.
+
+## Summary
+
+The following table compares the available ways to install Datadog language SDKs and create spans. In most cases, you install the SDK and rely on automatic instrumentation, then optionally add custom instrumentation if you need more control.
 
 <table style="width:100%; border-collapse:collapse; border:2px solid #999;">
-  <!-- Header group -->
-  <tr style="background-color:#d4d4e8;">
-    <th style="border:1px solid #ccc; background-color:#d4d4e8;"></th>
-    <th colspan="2" style="border:1px solid #ccc; border-right:2px solid #999; text-align:center; background-color:#d4d4e8; font-weight:bold; text-transform:uppercase; font-size:1.15em; padding:12px 8px;">
-      Automatic Instrumentation
+  <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/automatic_instrumentation/single-step-apm/">
+        Single Step Instrumentation
+      </a>
     </th>
-    <th colspan="2" style="border:1px solid #ccc; text-align:center; background-color:#d4d4e8; font-weight:bold; text-transform:uppercase; font-size:1.15em; padding:12px 8px;">
-      Custom Instrumentation
+    <th style="border:1px solid #ccc; font-weight:bold;">
+      <a href="/tracing/trace_collection/automatic_instrumentation/dd_libraries/">
+        Manually managed SDKs
+      </a>
+    </th>
+    <th style="border:1px solid #ccc; font-weight:bold;">
+      <a href="/tracing/trace_collection/custom_instrumentation/">
+        Code-based Custom Instrumentation
+      </a>
+    </th>
+    <th style="border:1px solid #ccc; font-weight:bold;">
+      <a href="/tracing/dynamic_instrumentation/">
+        Dynamic Instrumentation
+      </a>
     </th>
-  </tr>
-  <tr style="background-color:#f2f2f2;">
-    <th style="border:1px solid #ccc; text-transform:uppercase; font-weight:bold;"></th>
-    <th style="border:1px solid #ccc; text-transform:uppercase; font-weight:bold;"><a href="/tracing/trace_collection/automatic_instrumentation/single-step-apm/">Single Step Instrumentation</a></th>
-    <th style="border:1px solid #ccc; border-right:2px solid #999; text-transform:uppercase; font-weight:bold;"><a href="/tracing/trace_collection/automatic_instrumentation/dd_libraries/">Manually managed SDKs</a></th>
-    <th style="border:1px solid #ccc; text-transform:uppercase; font-weight:bold;"><a href="/tracing/trace_collection/custom_instrumentation/">Code-based Custom Instrumentation</a></th>
-    <th style="border:1px solid #ccc; text-transform:uppercase; font-weight:bold;"><a href="/tracing/dynamic_instrumentation/">Dynamic Instrumentation</a><br>(UI-based Custom Instrumentation)</th>
   </tr>
 
-  <!-- Body rows -->
+  <!-- Description -->
   <tr>
     <td style="border:1px solid #ccc; font-weight:bold;">Description</td>
-    <td style="border:1px solid #ccc;">With a single command, Datadog automatically loads language SDKs to your application processes. You can also control which processes to instrument.</td>
-    <td style="border:1px solid #ccc; border-right:2px solid #999;">Add Datadog language SDKs to your applications. The SDK handles instrumentation automatically.</td>
-    <td style="border:1px solid #ccc;">Add explicit tracing API calls or span logic in your application code.</td>
-    <td style="border:1px solid #ccc;">Add instrumentation rules in the Datadog UI. Rules are applied dynamically at runtime and do not require code changes.</td>
+    <td style="border:1px solid #ccc;">
+      With a single command, Datadog automatically loads language SDKs to your application processes. You can also control which processes to instrument.
+    </td>
+    <td style="border:1px solid #ccc;">
+      Add Datadog language SDKs to your applications. The SDK handles instrumentation automatically.
+    </td>
+    <td style="border:1px solid #ccc;">
+      Add explicit tracing API calls or span logic in your application code.
+    </td>
+    <td style="border:1px solid #ccc;">
+      Add instrumentation rules in the Datadog UI. Rules are applied dynamically at runtime and do not require code changes.
+    </td>
   </tr>
+
+  <!-- Installs SDK -->
+  <tr>
+    <td style="border:1px solid #ccc; font-weight:bold;">Installs Datadog language SDKs?</td>
+    <td style="border:1px solid #ccc;">Yes (automatic)</td>
+    <td style="border:1px solid #ccc;">Yes (manual)</td>
+    <td style="border:1px solid #ccc;">No</td>
+    <td style="border:1px solid #ccc;">No</td>
+  </tr>
+
+  <!-- Instrumentation behavior -->
+  <tr>
+    <td style="border:1px solid #ccc; font-weight:bold;">Instrumentation behavior</td>
+    <td style="border:1px solid #ccc;">Automatic</td>
+    <td style="border:1px solid #ccc;">Automatic</td>
+    <td style="border:1px solid #ccc;">Custom (code-based)</td>
+    <td style="border:1px solid #ccc;">Custom (runtime, UI-based)</td>
+  </tr>
+
+  <!-- Code changes -->
   <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">Code changes?</td>
+    <td style="border:1px solid #ccc; font-weight:bold;">Code changes required</td>
     <td style="border:1px solid #ccc;">No</td>
-    <td style="border:1px solid #ccc; border-right:2px solid #999;">No</td>
+    <td style="border:1px solid #ccc;">Yes</td>
     <td style="border:1px solid #ccc;">Yes</td>
     <td style="border:1px solid #ccc;">No</td>
   </tr>
+
+  <!-- Environment config -->
   <tr>
-    <td style="border:1px solid #ccc; font-weight:bold;">Environment config changes?</td>
+    <td style="border:1px solid #ccc; font-weight:bold;">Runtime or environment configuration required</td>
     <td style="border:1px solid #ccc;">No</td>
-    <td style="border:1px solid #ccc; border-right:2px solid #999;">Yes</td>
+    <td style="border:1px solid #ccc;">Yes</td>
     <td style="border:1px solid #ccc;">Yes</td>
     <td style="border:1px solid #ccc;">No</td>
   </tr>
+
+  <!-- Setup complexity -->
   <tr>
     <td style="border:1px solid #ccc; font-weight:bold;">Setup complexity</td>
     <td style="border:1px solid #ccc;">Low</td>
-    <td style="border:1px solid #ccc; border-right:2px solid #999;">Medium</td>
+    <td style="border:1px solid #ccc;">Medium</td>
     <td style="border:1px solid #ccc;">High</td>
     <td style="border:1px solid #ccc;">Low</td>
   </tr>
+
+  <!-- Best for -->
   <tr>
     <td style="border:1px solid #ccc; font-weight:bold;">Best for</td>
-    <td style="border:1px solid #ccc;">SRE, admins, or central teams who want tracing across services without developer involvement.</td>
-    <td style="border:1px solid #ccc; border-right:2px solid #999;">App dev teams who want to instrument applications individually with granular control over configuration through environment variables.</td>
-    <td style="border:1px solid #ccc;">Teams needing custom logic, specialized spans, or visibility into custom code paths.</td>
-    <td style="border:1px solid #ccc;">Teams wanting to add spans, logs, or metrics to specific code locations at runtime without redeploying or modifying source code. Configuration is managed through the Datadog UI.</td>
+    <td style="border:1px solid #ccc;">
+      SRE, admins, or central teams who want tracing across services without developer involvement.
+    </td>
+    <td style="border:1px solid #ccc;">
+      App dev teams who want to instrument applications individually with granular control over configuration through environment variables.
+    </td>
+    <td style="border:1px solid #ccc;">
+      Teams needing custom logic, specialized spans, or visibility into custom code paths.
+    </td>
+    <td style="border:1px solid #ccc;">
+      Teams wanting to add spans, logs, or metrics to specific code locations at runtime without redeploying or modifying source code. Configuration is managed through the Datadog UI.
+    </td>
   </tr>
+
+  <!-- Use cases -->
   <tr>
     <td style="border:1px solid #ccc; font-weight:bold;">Use cases</td>
-    <td colspan="2" style="border:1px solid #ccc; border-right:2px solid #999;">
-      <ul style="margin:0; padding-left:20px; font-size:inherit;">
-        <li style="font-size:inherit;">Capturing essential observability data across common libraries and languages with minimal configuration.</li>
-        <li style="font-size:inherit;">Enabling real-time monitoring with pre-configured settings for immediate insights into application performance.</li>
-        <li style="font-size:inherit;">Simplifying the observability setup for projects where custom instrumentation is not required.</li>
+    <td colspan="2" style="border:1px solid #ccc;">
+      <ul style="margin:0; padding-left:20px;">
+        <li>Capturing essential observability data across common libraries and languages with minimal configuration.</li>
+        <li>Enabling real-time monitoring with pre-configured settings for immediate insights into application performance.</li>
+        <li>Simplifying the observability setup for projects where custom instrumentation is not required.</li>
       </ul>
     </td>
     <td colspan="2" style="border:1px solid #ccc;">
-      <ul style="margin:0; padding-left:20px; font-size:inherit;">
-        <li style="font-size:inherit;">Collecting observability data from custom code with unique or complex business logic.</li>
-        <li style="font-size:inherit;">Providing deeper visibility and context into spans, including adding span tags.</li>
-        <li style="font-size:inherit;">Precisely monitoring specific sequences of operations or user interactions that require fine-grained control.</li>
-        <li style="font-size:inherit;">Removing unwanted spans from traces.</li>
+      <ul style="margin:0; padding-left:20px;">
+        <li>Collecting observability data from custom code with unique or complex business logic.</li>
+        <li>Enriching traces with application-specific metadata.</li>
+        <li>Precisely monitoring sequences of operations or user interactions that require fine-grained control.</li>
+        <li>Removing unwanted spans from traces.</li>
       </ul>
     </td>
   </tr>