First, import and start the tracer in your code following the Library Configuration documentation. Refer to the API documentation for configuration instructions and details about using the API.

Next, activate Go integrations to generate spans. Datadog has a series of pluggable packages which provide out-of-the-box support for instrumenting a series of libraries and frameworks. A list of these packages can be found in the Compatibility Requirements page. Import these packages into your application and follow the configuration instructions listed alongside each Integration.

Overview

Orchestrion automatically adds instrumentation to Go applications during compilation, eliminating the need for code changes. It provides comprehensive tracing coverage and enables exclusive security features:

• Comprehensive tracing coverage:
  • Instruments your code and all dependencies, including the Go standard library
  • Instruments your code during compilation, preventing gaps in tracing coverage due to overlooked manual instrumentation
• Exclusive Application Security Management Exploit Prevention feature. Exploit Prevention is a Runtime Application Self-Protection (RASP) implementation and includes RASP methods such as Local File Inclusion (LFI).

Requirements

• Supports the two latest Go runtime releases (matching Go’s official release policy).
• Applications must be managed using go modules. Module vendoring is supported.

Supported packages

Orchestrion is under active development and supports a subset of integrations available in the tracing library. For the latest list of supported frameworks and their minimum Orchestrion versions, see the Supported frameworks.

Install Orchestrion

To install and set up Orchestrion:

1. Install Orchestrion:

   go install github.com/DataDog/orchestrion@latest
   

   Ensure $(go env GOBIN) (or $(go env GOPATH)/bin) is in your $PATH.

2. Register Orchestrion in your project’s go.mod:

   orchestrion pin
   

3. Commit changes to your version control system:

   git commit -m "chore: enable orchestrion" go.mod go.sum orchestrion.tool.go
   

Now you can manage your dependency on orchestrion like any other dependency using the go.mod file.

Usage

Use one of these methods to enable Orchestrion in your build process:

Prepend orchestrion to your usual go commands:

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

Add the -toolexec="orchestrion toolexec" argument to your go commands:

go build -toolexec="orchestrion toolexec" .
go run -toolexec="orchestrion toolexec" .
go test -toolexec="orchestrion toolexec" ./...

Modify the $GOFLAGS environment variable to inject Orchestrion, and use go commands normally:

# Make sure to include the quotes as shown below, as these are required for
# the Go toolchain to parse GOFLAGS properly!
export GOFLAGS="${GOFLAGS} '-toolexec=orchestrion toolexec'"
go build .
go run .
go test ./...

Create custom trace spans

To create custom trace spans for functions accepting context.Context or *http.Request arguments, add the //dd:span directive comment to the function declaration:

//dd:span custom_tag:tag_value
func CriticalPathFunction(ctx context.Context) {
  // ... implementation details ...
}

This also works with function literal expressions:

//dd:span custom_tag:tag_value
handler := func(w http.ResponseWriter, r *http.Request) {
  // ... implementation details ...
}

Use the tracing library

You can use the tracing library in your Orchestrion-built application. This is useful for instrumenting frameworks not yet supported by Orchestrion. However, be aware that this may result in duplicated trace spans in the future as Orchestrion support expands. Review the release notes when updating your orchestrion dependency to stay informed about new features and adjust your manual instrumentation as necessary.

Use the continuous profiler

Your Orchestrion-built application includes continuous profiler instrumentation. To enable the profiler, set the environment variable DD_PROFILING_ENABLED=true at run time.

Supported frameworks