Auto-Instrumentation
Auto-instrumentation is the mechanism by which, the moment the Datadog SDK (tracing library) is loaded, calls to supported frameworks and libraries automatically become spans. It lets you capture traces without rewriting code, while the sections of your own custom processing are instrumented by you.
Overview
Auto-instrumentation is a mechanism that works by default the moment the Datadog APM SDK is loaded into an application, recording calls to supported frameworks and libraries as spans. Calls the SDK knows about are captured automatically, but for sections of your own business logic and business-level attributes you add spans yourself. Single Step Instrumentation is the approach in which even embedding the SDK is done automatically from the Agent side. You care about it when traces are showing up but your own processing is not visible, and when you want to extend instrumentation without touching code.
Instrumentation that starts the moment the SDK is loaded
Auto-instrumentation is the mechanism that works the moment the Datadog APM SDK (tracing library) is loaded, turning calls to supported frameworks and libraries into Spans. The official documentation explains that once the SDK is loaded, spans are generated automatically by default, and that this gives sufficient visibility for many users (as of September 2026, Source: Application Instrumentation). Instrumentation refers to the work of adding code to capture traces, and auto-instrumentation has the SDK take over most of that work. Supported languages and the adoption flow are left to the APM explainer.
How far is automatic, and where do you start writing it yourself
The boundary is "a call the SDK knows about, or processing you wrote yourself." Supported calls automatically become spans, but sections of your own business logic and application-specific attributes are unknown to the SDK. When you want to see those, there are 2 means. Dynamic Instrumentation lets you define instrumentation rules in the Datadog UI and add custom spans to running processes without code changes or redeployment. Code-based custom instrumentation is the method of writing spans directly in the code, and suits complex instrumentation logic and spans you want to keep permanently (as of September 2026, Source: Application Instrumentation). The 3 can be layered together. Since the SDK decides the names and attributes of auto-instrumented spans, the moment a requirement arises to name sections in business terms is when custom instrumentation takes the stage.
Single Step Instrumentation - automating even the embedding of the SDK
Auto-instrumentation presupposes that the SDK is loaded into the process. Single Step Instrumentation (SSI) is what automates that embedding itself (as of September 2026, Source: Single Step APM Instrumentation). When you install the Datadog Agent with APM Instrumentation enabled, the Agent has supported processes load the SDK. What works inside is a shared library called the injector, and the route by which it gets onto a process differs by environment.
| Environment | Route |
|---|---|
| Linux hosts | Loaded into every dynamically linked process via LD_PRELOAD (/etc/ld.so.preload) |
| Docker | A Datadog-provided runc shim replaces the default container runtime and sets LD_PRELOAD for processes inside the container |
| Kubernetes | The Datadog Admission Controller rewrites the Pod spec as a mutating webhook and distributes the injector and SDK with an init container |
| Windows | A Datadog kernel driver loads the injector DLL into new processes |
Since the Kubernetes route is handled by components on the Cluster Agent side, checking that the Cluster Agent is running before rolling SSI out more widely saves you second-guessing.
What the injector decides inside the process
Once the injector is in the process's memory, its behavior proceeds in the same order in every environment.
- Detect the application runtime (Python / Node.js / PHP / Java / .NET / Ruby / NGINX)
- Decide whether the process is an instrumentation target (some processes are excluded by default, and allow and deny rules can also be defined)
- Rewrite environment variables or command-line arguments to load the SDK matching the runtime (for Java,
-javaagentinJAVA_TOOL_OPTIONS; for Python,PYTHONPATH) - Send telemetry indicating its status
- If it fails or the runtime is unsupported, keep running the application without instrumentation
The last point matters in practice. Because the application does not stop even if instrumentation does not take effect, "no traces are showing up" surfaces quietly as a configuration problem rather than an outage. Disabling it also has a quirk: since the injector runs before the SDK evaluates environment variables, DD_TRACE_ENABLED=false cannot stop SSI. To stop it, disable SSI itself using the procedure for each platform (as of September 2026, Source: Understanding Injector Behavior).
SSI stops automatically if custom instrumentation remains
As a prerequisite for using SSI, the official documentation asks you to remove existing custom instrumentation code and restart. This is because SSI is automatically disabled when custom instrumentation is detected (as of September 2026, Source: Single Step APM Instrumentation). If you choose vendor neutrality, there is also the route of instrumenting with OpenTelemetry and sending to Datadog, and the receiving side is covered in the OpenTelemetry explainer. There are 2 situations in which you become conscious of the term auto-instrumentation. One is when spans line up on the Service screen but only the sections of your own processing are missing; that is outside the scope of auto-instrumentation, so the decision is to add custom spans. The second is when no Traces appear at all, in which case you check, in order, whether the runtime is supported, whether an exclusion rule is matching, and whether leftover custom instrumentation has stopped SSI.