Orchestrion is an open-source, Apache-2.0 licensed tool that automatically instruments Go source code at compile time, built for Go teams that want tracing and APM coverage without hand-editing their code.

What it is

Orchestrion is a Go developer tool maintained under the DataDog organisation. It processes Go source code during compilation and automatically inserts instrumentation into it. Which instrumentation gets inserted is driven by the imports present in an orchestrion.tool.go file at the project's root. The project positions itself as vendor-agnostic: by default orchestrion pin enables Datadog's tracer integrations by importing github.com/DataDog/dd-trace-go/v2 in orchestrion.tool.go, but other vendors such as OpenTelemetry may provide alternate integrations that can be used instead. It carries topics for apm, datadog, go, instrumentation, monitoring, and tracing, and sits in the Infrastructure & Operations / Monitoring & Observability category.

The concrete problem it solves is manual instrumentation of Go services. Instead of a developer writing instrumentation calls by hand into each service, package, and handler, Orchestrion rewrites the source at build time so the instrumentation is present in the compiled binary. It replaces the hand-written instrumentation code and per-integration wiring that a Go team would otherwise maintain across its codebase. Because the work happens at compile time rather than at runtime, the generated instrumentation is part of the build output rather than something attached dynamically.

Key capabilities

• Compile-time source processing that inserts instrumentation automatically during the Go build.
• Import-driven configuration: the set of active instrumentations comes from imports declared in orchestrion.tool.go at the project root.
• Full-tracer enrolment by importing github.com/DataDog/dd-trace-go/v2, which enables automatic instrumentation of all supported integrations.
• Selective enrolment by importing individual integration package paths instead of the tracer's root module, so a project can cherry-pick which integrations are enabled.
• orchestrion pin as the command that writes the Datadog tracer integration imports into orchestrion.tool.go by default.
• Vendor-agnostic integration model, with alternate integrations such as OpenTelemetry able to replace the default Datadog set.
• Build diagnostics through the -work argument to go build, which emits a WORK= line pointing at a retained directory containing the updated source Orchestrion produced plus metadata.
• orchestrion version reports the tool version, which together with go version is required in any bug report.

Who uses it and how

• Go teams whose services are already built with Go modules and who want tracing coverage without editing application code; Go modules are a hard requirement.
• Datadog customers following the compile-time instrumentation path of the Go tracing library, using the dd-trace-go/v2 import to enrol all supported integrations at once.
• Teams that want partial coverage, importing only the specific integration package paths they care about rather than the tracer's root module.
• Projects on the two latest Go releases, which is the support window Orchestrion matches to Go's official release policy; older releases may work but are not supported.
• Users debugging their build, running go build -work to inspect the rewritten source and metadata in the retained working directory, then filing reports in the GitHub issue tracker or asking questions in GitHub discussions.

Getting started

Add the desired imports to orchestrion.tool.go at the project root and run orchestrion pin to enable Datadog's tracer integrations, or import individual integration package paths instead. The step-by-step path is the user guide on the Datadog documentation site under the Go library's compile-time instrumentation tab, with project documentation at datadoghq.dev/orchestrion.

How it compares

Orchestrion is itself vendor-agnostic and treats the Datadog tracer as one option among several; the OpenTelemetry ecosystem is named in the README as a source of alternate integrations that can be substituted for the default Datadog set. The distinction that matters is therefore not which vendor wins but where the instrumentation is injected: Orchestrion does it by rewriting Go source at compile time, configurable through a single orchestrion.tool.go file at the project root. Projects already invested in one tracing vendor can keep that vendor's integration package and swap it by changing imports rather than restructuring the build.

When to use it — and when not to

Pick Orchestrion if the codebase is a Go modules project on one of the two latest Go releases and the team accepts a compile-time source-rewriting step in its build pipeline. Do not pick it for non-module Go projects, for older Go toolchains where support is explicitly not offered, or where the build must remain byte-for-byte untouched, since Orchestrion rewrites source during compilation. The main weakness visible in the project's own material is documentation placement: the README's getting-started path points offsite to Datadog's user guide, and the repository itself is light on setup detail, so teams relying on the repo alone will need to follow the external docs.