diff --git a/content/en/tracing/trace_collection/_index.md b/content/en/tracing/trace_collection/_index.md index 24146a34f67..071e4dcbdd7 100644 --- a/content/en/tracing/trace_collection/_index.md +++ b/content/en/tracing/trace_collection/_index.md @@ -28,112 +28,179 @@ algolia: --- ## Overview +Application {{< tooltip glossary="instrumentation" >}} with Datadog APM involves two steps: -To get started with Datadog APM, you need to follow these key steps: +1. **SDK setup**: Adding a Datadog SDK to your application. +2. **Span creation**: Capturing observability data as {{< tooltip glossary="span" >}}s. -1. Install and configure the Datadog Agent. -2. Instrument your application. +Spans are automatically generated by default as soon as the SDK is loaded. For most users, this automatic span creation provides sufficient visibility. If you need more control, you can optionally add custom spans. -
Simplify your setup! Install the Agent and instrument your application in one step with Single Step Instrumentation.
- -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. +**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">}} +## Choose your path + +
+Prefer vendor-neutral instrumentation? See the OpenTelemetry documentation for using OpenTelemetry with Datadog. +
+ +### No code changes -## Instrumentation types +**Best for**: Teams that want tracing without modifying application code. -There are two main approaches to {{< tooltip glossary="instrument" >}} your application: +Use [Single Step Instrumentation][1] to automatically set up Datadog SDKs. If you need custom spans, you can also use [Dynamic Instrumentation][4] to add them from the Datadog UI without changing code. -**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. +{{< whatsnext desc=" " >}} + {{< nextlink href="/tracing/trace_collection/single-step-apm/" >}}Get started with Single Step Instrumentation{{< /nextlink >}} + {{< nextlink href="/tracing/trace_collection/dynamic_instrumentation/" >}}Add custom spans with Dynamic Instrumentation{{< /nextlink >}} +{{< /whatsnext >}} -**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. +### Code-based setup and customization -The following table compares the different instrumentation methods available. +**Best for**: Teams that want full control over SDK configuration and span creation. -
-If you prefer vendor-neutral instrumentation, see the OpenTelemetry documentation for using OpenTelemetry API support in Datadog libraries. -
+Use [Datadog SDKs][2] to manually configure instrumentation. If you need custom spans, you can also add [code-based custom instrumentation][3]. + +{{< whatsnext desc=" " >}} + {{< nextlink href="/tracing/trace_collection/dd_libraries/" >}}Get started with Datadog SDKs{{< /nextlink >}} + {{< nextlink href="/tracing/trace_collection/custom_instrumentation/" >}}Add custom spans with code-based instrumentation{{< /nextlink >}} +{{< /whatsnext >}} + +## How instrumentation works + +### SDK setup + +The first step is adding a Datadog SDK to your application. You have two options: + +| Method | Description | Code changes? | Best for | +|--------|-------------|--------------|----------| +| [**Single Step Instrumentation (SSI)**][1] | Automatically installs and loads SDKs at runtime with a single command. | No | SREs and platform teams who want tracing across services without developer involvement. | +| [**Manual SDK setup**][2] | Manually install and configure SDKs in your application. | Yes | Development teams who need granular control over SDK configuration. | + +### Span creation + +After the SDK is loaded, spans are automatically created through auto-instrumentation for supported frameworks and libraries. This automatic span creation captures essential observability data with no additional work required. + +If you need visibility into custom code paths or want to enrich traces with application-specific data, you can add custom spans: + +| Method | Description | Code changes? | Best for | +|--------|-------------|--------------|----------| +| [**Code-based custom instrumentation**][3] | Add spans programmatically using Datadog tracing APIs. | Yes | Teams that need custom logic, specialized spans, or visibility into custom code paths. | +| [**Dynamic Instrumentation**][4] | Add spans at runtime from the Datadog UI without code changes. | No | Teams that want to add spans without redeploying or modifying source code. | + +## Decision guide + +Use this guide to determine which combination of methods fits your needs: + +| Goal | SDK setup | Span creation | +|------|-----------|---------------| +| Get started with minimal effort | [Single Step Instrumentation][1] | Auto-instrumentation | +| Manually control SDK setup but use auto-instrumentation to capture spans | [Datadog SDKs][2] | Auto-instrumentation | +| Automatically load SDKs and customize spans without code changes | [Single Step Instrumentation][1] | [Dynamic Instrumentation][4] | +| Automatically load SDKs and customize spans in code | [Single Step Instrumentation][1] | [Code-based custom instrumentation][3] | +| Manually configure SDKs and customize spans without code changes | [Datadog SDKs][2] | [Dynamic Instrumentation][4] | +| Have full control over both SDK setup and span creation | [Datadog SDKs][2] | [Code-based custom instrumentation][3] | + +## Detailed comparison + +### SDK setup options - - - - - - - - - - - + + + - - - - - - - + + + - - - - - - - + + + - - - + + + + + + - - - - + + + +
- Automatic Instrumentation - - Custom Instrumentation -
Single Step InstrumentationManually managed SDKsCode-based Custom InstrumentationDynamic Instrumentation
(UI-based Custom Instrumentation)		Single Step InstrumentationDatadog SDKs
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.How it worksDatadog automatically loads SDKs into your application processes with a single command.You install and configure SDKs directly in your application code or build process.
Code changes? NoNo YesNo
Environment config changes?NoYesYesNoEnvironment configurationMinimalRequired
Setup complexity LowMediumHighLowMedium
Configuration controlStandard defaults with optional overridesFull control through environment variables and code
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.SREs, platform teams, and organizations wanting fast, consistent instrumentation across services.Development teams needing granular control over SDK behavior and configuration.
+ +### Span customization options + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + +
Code-based custom instrumentationDynamic Instrumentation
How it worksAdd explicit tracing API calls in your application code.Configure instrumentation rules in the Datadog UI; rules are applied at runtime.
Code changes?YesNo
Deployment requiredYes (to add or modify spans)No
Setup complexityMedium to highLow
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.
    • +
+
    +
  • Instrumenting custom business logic
    • +
  • Adding application-specific metadata to spans
    • +
  • Removing unwanted spans from traces
    • +
  • Complex span manipulation
 -
    -
  • 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.
    • +
+
    +
  • Adding spans to production without redeploying
    • +
  • Debugging specific code paths
    • +
  • Adding logs or metrics at runtime
    • +
  • Fast instrumentation changes
Best forTeams with complex instrumentation needs who want spans defined in code.Teams wanting to add or modify spans without code changes or redeployments.
- ## 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, using the Datadog tracing libraries: +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" >}} Enabling Tracing on a Python Application on the Same Host as Datadog Agent{{< /nextlink >}} @@ -143,7 +210,7 @@ The following tutorials guide you through setting up distributed tracing for a s {{< nextlink href="tracing/guide/tutorial-enable-java-containers" >}} Enabling Tracing on a Java Application and Datadog Agent in Containers{{< /nextlink >}} {{< nextlink href="tracing/guide/tutorial-enable-java-container-agent-host" >}} Enabling Tracing for a Java Application in a Container and an Agent on a Host{{< /nextlink >}} {{< nextlink href="tracing/guide/tutorial-enable-java-gke" >}} Enabling Tracing for a Java Application on GKE{{< /nextlink >}} - {{< nextlink href="tracing/guide/tutorial-enable-java-aws-eks" >}} Enabling Tracing for a Java Application on AWS EKS{{< /nextlink >}} + {{< nextlink href="tracing/guide/tutorial-enable-java-aws-eks" >}} Enabling Tracing for a Java Application on Amazon EKS{{< /nextlink >}} {{< nextlink href="tracing/guide/tutorial-enable-java-aws-ecs-ec2" >}} Enabling Tracing for a Java Application in Amazon ECS with EC2{{< /nextlink >}} {{< nextlink href="tracing/guide/tutorial-enable-java-aws-ecs-fargate" >}} Enabling Tracing for a Java Application in Amazon ECS with Fargate{{< /nextlink >}} {{< nextlink href="tracing/guide/tutorial-enable-java-admission-controller" >}} Enabling Tracing for a Java Application with the Admission Controller{{< /nextlink >}} @@ -153,7 +220,14 @@ The following tutorials guide you through setting up distributed tracing for a s {{< nextlink href="tracing/guide/tutorial-enable-go-aws-ecs-fargate" >}} Enabling Tracing for a Go Application in Amazon ECS with Fargate{{< /nextlink >}} {{< /whatsnext >}} + ## Further reading {{< partial name="whats-next/whats-next.html" >}} +[1]: /tracing/trace_collection/single-step-apm/ +[2]: /tracing/trace_collection/dd_libraries/ +[3]: /tracing/trace_collection/custom_instrumentation/ +[4]: /tracing/trace_collection/dynamic_instrumentation/ +[5]: /agent/ +