Orchestrion

Automatic compile-time instrumentation of Go code.

Overview

Orchestrion processes Go source code at compilation time and automatically inserts instrumentation. This instrumentation is driven by the imports present in the orchestrion.tool.go file at the project's root.

[!IMPORTANT] Should you encounter issues or a bug when using orchestrion, please report it in the bug tracker.

For support & general questions, you are welcome to use GitHub discussions. You may also contact us privately via Datadog support.

Requirements

Orchestrion supports the two latest releases of Go, matching Go's official release policy. It may function correctly with older Go releases; but we will not be able to offer support for these if they don't.

In addition to this, Orchestrion only supports projects using Go modules.

Getting started

Information on how to get started quickly with orchestrion can be found on the user guide.

Datadog Tracer Integrations

Importing github.com/DataDog/dd-trace-go/v2 in the project root's orchestrion.tool.go file enables automatic instrumentation of all supported integrations, which are listed on the documentation site. You can cherry-pick which integrations are enabled by orchestrion by importing the desired integrations' package paths instead of importing the tracer's root module.

[!TIP] Orchestrion is a vendor-agnostic tool. 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.

Troubleshooting

If you run into issues when using orchestrion please make sure to collect all relevant details about your setup in order to help us identify (and ideally reproduce) the issue. The version of orchestrion (which can be obtained from orchestrion version) as well as of the go toolchain (from go version) are essential and must be provided with any bug report.

You can inspect everything Orchestrion is doing by adding the -work argument to your go build command; when doing so the build will emit a WORK= line pointing to a working directory that is retained after the build is finished. The contents of this directory contains all updated source code Orchestrion produced and additional metadata that can help diagnosing issues.

More information

Datadog's user guide for Orchestrion can be found on docs.datadoghq.com.

Orchestrion's project documentation can be found at datadoghq.dev/orchestrion; in particular:

• the user guide provides information about available configuration, and how to customize the traces produced by your application;
• the contributor guide provides more detailed information about how orchestrion works and how to contribute new instrumentation to it.