dd-trace-java and the price of automatic instrumentation

Two things in one repository: the API and the agent

The repository contains dd-trace-java, described as Datadog's APM client Java library, and the documentation says it provides APIs to automatically or manually trace and profile Java applications.

That phrasing hides the most useful structural fact. The repository is not one artifact. It is a set of modules, and the directory names make the split legible: dd-trace-api is the public surface a developer codes against, dd-trace-core holds the implementation, and dd-java-agent is the part that instruments applications at startup. There is also dd-trace-ot, which by its name is the OpenTelemetry side of the house, and dd-openfeature at the top level for feature flag evaluation.

The split matters for how you consume it. If you want spans you emit yourself, dd-trace-api is the dependency. If you want Datadog to attach spans to the framework calls you already make, the agent is what does that, and the agent is a JVM agent rather than a library you call.

The repository also has a Gradle build at the root with build.gradle.kts, a settings file, a gradle directory and a wrapper, alongside a Maven wrapper, mvnw, so both build ecosystems are supported at the tooling level.

Automatic instrumentation is the product, manual API is the escape hatch

The listed features show what the automatic instrumentation buys you. Distributed Tracing with Automatic Instrumentation is named first, and the integrations are indexed under a compatibility page. Continuous Profiling, Error Tracking, Continuous Integration Visibility, Deployment Tracking and Code Hotspots are all named as powered by the same library.

That last one is worth pausing on. Code Hotspots connects traces and profiles, so a slow endpoint in a trace can be tied to the profiling data for the same window. This is the kind of correlation that a plain APM agent does not give you, and it explains why the profiler lives in the same codebase rather than being a separate agent you have to run alongside.

Manual instrumentation exists for the cases automatic coverage misses: a custom library, an internal RPC call, a queue publish, or a piece of business logic you want to time yourself. The API docs are linked from the README as the custom instrumentation API, sitting alongside a configuration reference for advanced usage.

The repository also contains docs/add_new_instrumentation.md and docs/how_instrumentations_work.md, which tells you two things. First, writing your own instrumentation is a supported activity rather than a hack. Second, the way instrumentations work is explained in a separate document, so the internals are documented but not in the README.

What the README deliberately leaves to the docs site

There is a notable absence in this README: no installation command, no configuration snippet, no code example.

The Getting Started section is three sentences. To use and configure, check out the setup documentation. For advanced usage, check out the configuration reference and the custom instrumentation API. And then, for the terminology, there is a pointer to an APM glossary, with the note Confused about the terminology of APM?

Those links point at docs.datadoghq.com, and the setup documentation for this library is at the Java tracing page. The configuration reference is the library configuration page, which is where the actual keys live, and the custom instrumentation API documentation is a third page for writing spans by hand.

This is a reasonable choice for a vendor-owned project whose documentation lives on a product site with versioned, per-language pages, and the repository does link every one of them. The cost is that a reader of the repository alone cannot answer the first question anyone has, which is how do I turn this on. If you are evaluating the library from GitHub, you have to read the docs site, and the docs site is versioned separately from the tags, so what you read there may not correspond exactly to the release you pin.

A Gradle multi-module build with a published-dependency test suite

The repository layout is larger than a typical library and shows a lot of internal tooling. There is a build-logic directory and a buildSrc directory, which is the Gradle convention for shared build configuration, plus a gradle.lockfile and a settings-gradle.lockfile, meaning dependency versions are locked and verified rather than resolved fresh.

The tooling directory and a static-analysis.datadog.yml file suggest the build runs its own linters. A .githooks directory, a .gitlab directory alongside .github, and a .gitlab-ci.yml indicate the project is built on more than one CI system.

Two directories stand out for what they tell you about the release process. test-published-dependencies is a suite that checks the artifacts you publish actually work when consumed as dependencies, which catches packaging mistakes that unit tests inside the build cannot. And there are tag-conventions files, tag-conventions.yaml and tag-conventions-java.yaml, which suggests the tagging scheme is enforced rather than ad hoc.

Other directories map to features rather than infrastructure: remote-config, telemetry, internal-api, metadata, communication, and a products directory. The internal-api name is a good signal about the design: there is a distinction between what application code sees and what the agent uses internally.

Release cadence: a new minor version in the first full week each month

The Releases section is short and specific. Datadog will generally release a new minor version during the first full week of every month, with more detail in docs/releases.md.

The published versions match that claim. v1.67.1 landed on 2026-10-08, which is the first full week of October, v1.67.0 on 2026-10-07, and v1.66.0 on 2026-09-08, the first full week of September. The pattern is consistent, and it means you can plan an upgrade rather than discovering one.

The version number also tells you the stability posture. A 1.x line with monthly minor releases means patch versions carry fixes and minor versions carry behaviour, and the minor release could change what your application observes, not just what the agent does internally. With a monthly cadence and no long-term support branch mentioned in the README, the upgrade question is a recurring one rather than an annual one.

The repository is not archived and the last push was on 2026-10-20, days after the 1.67.1 release, so the work is current and the release line is moving.

The licence is Apache-2.0, which is permissive and carries no copyleft obligation into your application. The repository also ships a LICENSE-3rdparty.csv and a NOTICE file, which is the expected form for a project that embeds third-party code.

What this repository is and is not for your team

It is worth being clear about where dd-trace-java sits, because the name understates it. It is not a general purpose Java tracing library. It is a client for one specific vendor's platform, and the features it enables, Continuous Integration Visibility, Deployment Tracking, Code Hotspots, are all Datadog product surfaces.

The alternative approach for a Java team that wants tracing without a vendor is the OpenTelemetry path, and the presence of dd-trace-ot as a separate module in this repository says something about how the vendor expects that conversation to go. The module is part of the same project, so choosing an OpenTelemetry-based setup does not mean leaving the Datadog codebase, but the code paths are separate and the configuration will differ.

Automatic instrumentation also has a known category of problem worth naming before you deploy it. A Java agent that rewrites bytecode at startup changes what your application is running, and it interacts with your framework versions, your JVM version and your other agents. The repository's own compatibility page for automatic instrumentation is the list of what is supported, and it is linked from the README, which means the coverage varies by integration.

The documentation for how instrumentations work exists as a separate guide, and for an agent that rewrites your code that guide is the right place to start evaluating, not the feature list.

Editorial conclusion

dd-trace-java is a good fit for a Java service that already sends telemetry to Datadog and wants distributed tracing, continuous profiling and error tracking from one dependency, because the automatic instrumentation covers the framework integrations you would otherwise wire by hand. It is a poor fit for a team that wants no vendor lock-in, for a build that cannot add a JVM agent, or for anyone who needs to understand exactly what is being instrumented before it runs in production, since the internals are documented in a separate guide. Before adopting, read the setup documentation for your framework and your Java version, check which integrations the compatibility list covers for your stack, and review the configuration reference, because the defaults in this repository are not the defaults you will run.

Frequently asked questions

Official sources

1. DataDog/dd-trace-java on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases