Skip to content

Instrumentation landing page rework #33569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
domalessi wants to merge 1 commit into
base: master
Choose a base branch
from
+124 −50
Open

Instrumentation landing page rework #33569

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 124 additions & 50 deletions content/en/tracing/trace_collection/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Check warning on line 61 in content/en/tracing/trace_collection/_index.md

View workflow job for this annotation

GitHub Actions / vale

Datadog.headings 

'Adding Datadog language SDKs' should use sentence-style capitalization.

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>
Expand Down
Loading