Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท APM and Tracing

Instrumenting an Application

Add Datadog tracing to a Python, Node.js or Java service with the tracer library, unified service tags, auto-instrumentation, custom spans and log correlation.

To get traces you add a tracer library to your application. For most languages this takes a package install, three environment variables and one changed start command. Then the tracer wraps popular frameworks and database drivers automatically (auto-instrumentation), and you add custom spans only for your own important code.

The real tracer needs a running Datadog Agent, so the commands here are shown as read-only snippets. The two runnable examples are labelled stand-ins that model what the tracer does.

Unified service tagging

Datadog connects traces, metrics and logs with three reserved tags. Set them as environment variables on the process:

Variable Tag Example
DD_SERVICE service checkout-api
DD_ENV env prod
DD_VERSION version 2.14.0

With these set, a deploy shows up as a new version, and you can compare latency between versions right on the service page.

Python

Terminal
pip install ddtrace
export DD_SERVICE=checkout-api DD_ENV=prod DD_VERSION=2.14.0
export DD_AGENT_HOST=localhost       # where the Agent listens
ddtrace-run python app.py            # or: ddtrace-run gunicorn app:app

ddtrace-run patches supported libraries (Flask, Django, requests, SQLAlchemy, psycopg and many more) before your code starts. A custom span looks like this:

Python
from ddtrace import tracer

@tracer.wrap(name="pricing.calculate", resource="apply_discounts")
def apply_discounts(cart):
    ...

def checkout(cart):
    with tracer.trace("checkout.reserve_stock", service="checkout-api") as span:
        span.set_tag("cart.items", len(cart))
        reserve(cart)

Node.js

Terminal
npm install dd-trace
JavaScript
// tracer.js: must be loaded before any other import
const tracer = require("dd-trace").init({
  service: "checkout-api",
  env: "prod",
  version: "2.14.0",
  logInjection: true,
});
module.exports = tracer;

Start the app with node --require ./tracer.js server.js. Load order matters: the tracer must patch http or express before they are imported.

Java

Terminal
java -javaagent:/opt/datadog/dd-java-agent.jar \
     -Ddd.service=checkout-api -Ddd.env=prod -Ddd.version=2.14.0 \
     -jar app.jar

The Java agent instruments bytecode at startup, so no code change is needed. In containers you usually add the jar in the image build, or use Datadog's admission controller on Kubernetes to inject libraries for you.

Exact package versions, flags and supported-library lists change often. Check the Datadog documentation for your language before you copy a setup into production.

Where the spans go

The tracer sends spans to the Agent. Make sure the Agent has APM enabled (apm_config.enabled: true in datadog.yaml, or DD_APM_ENABLED=true). In Docker or Kubernetes, point the tracer to the Agent with DD_AGENT_HOST or use the Unix socket. If no traces appear, check that the Agent is reachable on port 8126 and that the service name is spelled the way you search for it.

Log correlation

Set DD_LOGS_INJECTION=true (Python, Java) or logInjection: true (Node.js). The tracer then adds dd.trace_id and dd.span_id to each log line. In the Logs explorer you can jump from a log to its trace and back. Logs must be JSON, or parsed by a pipeline, for the IDs to become attributes.

A stand-in: how auto-instrumentation wraps a function

Auto-instrumentation replaces a function with a wrapper that starts a span, calls the original, records errors and ends the span. This JavaScript stand-in shows the idea.

JS Stand-in: a tiny tracer with wrap()

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Spans finish in child-first order, which is why the checkout span appears last even though it started first. The tracer builds the tree from the parent links.

A stand-in: unified service tags checker

This checker validates the three reserved tags the way a deploy script could before shipping.

JS Stand-in: check unified service tags

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Custom spans: when and why

Auto-instrumentation covers the edges of your app (HTTP, database, queues). Add custom spans for business steps that matter: pricing, a cache decision, a long loop. Add tags with low-risk, useful values such as cart.items or customer.tier. Never put passwords, card numbers or other secrets in tags.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which three environment variables make up unified service tagging?

    Service, env and version are the reserved tags that tie traces, metrics and logs together.
  2. 2. What does ddtrace-run do for a Python program?

    ddtrace-run starts your program with auto-instrumentation enabled, with no code changes.
  3. 3. Why must the Node.js tracer be required before other modules?

    Patching happens when a library is loaded, so the tracer has to load first.
  4. 4. What does DD_LOGS_INJECTION add to log lines?

    Trace and span IDs in the log let Datadog link a log line to its trace.

Summary

  • Install the tracer, set DD_SERVICE, DD_ENV and DD_VERSION, and start the app through the tracer.
  • Auto-instrumentation wraps frameworks and drivers; add custom spans for your own business steps.
  • The tracer sends spans to the local Agent, which must have APM enabled.
  • DD_LOGS_INJECTION links logs to traces.
  • Keep secrets out of span tags.

Next: Traces, Spans and the Service Map