From ff8c47ab98c27e661e0e5f4a3ba6c43f8293862e Mon Sep 17 00:00:00 2001 From: Dominique Alessi Date: Tue, 23 Dec 2025 16:59:13 -0500 Subject: [PATCH] instrumentation landing page rework --- content/en/tracing/trace_collection/_index.md | 174 +++++++++++++----- 1 file changed, 124 insertions(+), 50 deletions(-) diff --git a/content/en/tracing/trace_collection/_index.md b/content/en/tracing/trace_collection/_index.md index 24146a34f67..88fd72185fe 100644 --- a/content/en/tracing/trace_collection/_index.md +++ b/content/en/tracing/trace_collection/_index.md @@ -31,100 +31,174 @@ algolia: 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. -
Simplify your setup! Install the Agent and instrument your application in one step with Single Step Instrumentation.
+
+Simplify your setup! +Use Single Step Instrumentation to complete these steps in one command. +
-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 +
+If you prefer vendor-neutral instrumentation, see the OpenTelemetry documentation for using OpenTelemetry API support in Datadog libraries. +
-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. -
-If you prefer vendor-neutral instrumentation, see the OpenTelemetry documentation for using OpenTelemetry API support in Datadog libraries. -
+### 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. - - - - + + - + + - - - - - - - - + - - - - + + + + + + + + + + + + + + + + + + + + + + + + - + - + + + - + - + + + - + + + - - - - + + + + + + -
- Automatic Instrumentation +
+ + Single Step Instrumentation + - Custom Instrumentation + + + Manually managed SDKs + + + + Code-based Custom Instrumentation + + + + Dynamic Instrumentation +
Single Step InstrumentationManually managed SDKsCode-based Custom InstrumentationDynamic Instrumentation
(UI-based Custom Instrumentation)
DescriptionWith a single command, Datadog automatically loads language SDKs to your application processes. You can also control which processes to instrument.Add Datadog language SDKs to your applications. The SDK handles instrumentation automatically.Add explicit tracing API calls or span logic in your application code.Add instrumentation rules in the Datadog UI. Rules are applied dynamically at runtime and do not require code changes. + With a single command, Datadog automatically loads language SDKs to your application processes. You can also control which processes to instrument. + + Add Datadog language SDKs to your applications. The SDK handles instrumentation automatically. + + Add explicit tracing API calls or span logic in your application code. + + Add instrumentation rules in the Datadog UI. Rules are applied dynamically at runtime and do not require code changes. +
Installs Datadog language SDKs?Yes (automatic)Yes (manual)NoNo
Instrumentation behaviorAutomaticAutomaticCustom (code-based)Custom (runtime, UI-based)
Code changes?Code changes required NoNoYes Yes No
Environment config changes?Runtime or environment configuration required NoYesYes Yes No
Setup complexity LowMediumMedium High Low
Best forSRE, admins, or central teams who want tracing across services without developer involvement.App dev teams who want to instrument applications individually with granular control over configuration through environment variables.Teams needing custom logic, specialized spans, or visibility into custom code paths.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. + SRE, admins, or central teams who want tracing across services without developer involvement. + + App dev teams who want to instrument applications individually with granular control over configuration through environment variables. + + Teams needing custom logic, specialized spans, or visibility into custom code paths. + + 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. +
Use cases -
    -
  • Capturing essential observability data across common libraries and languages with minimal configuration.
    • -
  • Enabling real-time monitoring with pre-configured settings for immediate insights into application performance.
    • -
  • Simplifying the observability setup for projects where custom instrumentation is not required.
    • +
+
    +
  • Capturing essential observability data across common libraries and languages with minimal configuration.
    • +
  • Enabling real-time monitoring with pre-configured settings for immediate insights into application performance.
    • +
  • Simplifying the observability setup for projects where custom instrumentation is not required.
 -
    -
  • Collecting observability data from custom code with unique or complex business logic.
    • -
  • Providing deeper visibility and context into spans, including adding span tags.
    • -
  • Precisely monitoring specific sequences of operations or user interactions that require fine-grained control.
    • -
  • Removing unwanted spans from traces.
    • +
      +
    • Collecting observability data from custom code with unique or complex business logic.
      • +
    • Enriching traces with application-specific metadata.
      • +
    • Precisely monitoring sequences of operations or user interactions that require fine-grained control.
      • +
    • Removing unwanted spans from traces.