Documentation
Getting Started

Getting Started

Requirements

Orchestrion supports the two latest Go releases, matching the Go release policy.

It also requires the use of Go modules.

Orchestrion can inject instrumentation which enables use of Datadog’s ASM features, but those are only effectively available on supported platforms (Linux or macOS, on AMD64 and ARM64 processor architectures).

Install Orchestrion

We recommend installing Orchestrion as a project tool dependency, as this ensures you are in control of the exact versions of Orchestion and the Datadog tracing library being used; and that your builds are reproducible.

This is achieved using the following steps:

Step 1

Install Orchestrion in your environment:

$ go install github.com/DataDog/orchestrion@latest

If necessary, also add the GOBIN directory to your PATH:

$ export PATH="$PATH:$(go env GOBIN)"

Step 2

Register orchestrion in your project’s go.mod to ensure reproducible builds:

$ orchestrion pin

Be sure to check the updated files into source control!

Step 3

  • Option 1 (Recommended):

    Use orchestrion go instead of just go:

    $ orchestrion go build .
$ orchestrion go run .
$ orchestrion go test ./...

  • Option 2:

    Manually specify the -toolexec argument to go commands:

    $ go build -toolexec 'orchestrion toolexec' .
$ go run -toolexec 'orchestrion toolexec' .
$ go test -toolexec 'orchestrion toolexec' ./...

  • Option 3:

    Add the -toolexec argument to the GOFLAGS environment variable (be sure to include the quoting as this is required by the go toolchain when a flag value includes white space):

    $ export GOFLAGS="${GOFLAGS} '-toolexec=orchestrion toolexec'"

    Then use go commands normally:

    $ go build .
$ go run .
$ go test ./...

Step 4 (Optional)

Print what packages are instrumented by Orchestrion in your build. Add the -work and the -a flag to your go build command. For example using option 2:

$ go build -work -a -toolexec 'orchestrion toolexec' .
WORK=/tmp/go-build123456789

The previous command can take more time because the -a flag forces a full rebuild of all packages.

Now use the WORK directory to find the instrumented packages:

$ orchestrion diff --package /tmp/go-build123456789
os
runtime
testing
net/http
log/slog
[...]
Last updated on
DocumentationDatadog Tracer