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 App and API Protection 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.

Install Orchestrion

To install and set up Orchestrion:

1. Install Orchestrion:

   go install github.com/DataDog/orchestrion@latest
   

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

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

   orchestrion pin
   

   Refer to the output of orchestrion pin -help for more information about available customization options.

3. Commit changes to your version control system (unless you are integrating orchestrion directly in your CI/CD pipeline):

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

   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 ./...

Trace Customization

Setting up Unified Service Tagging

Applications instrumented by orchestrion support Unified Service Tagging (UST). You can set UST tags for your traces by setting the corresponding environment variable in your application’s runtime environment:

For more information, refer to the Unified Service Tagging documentation.

Tracer configuration

Refer to Library Configuration for configuration instructions.

Create custom trace spans

Custom trace spans can be automatically created for any function annotated with the //dd:span directive comment:

//dd:span custom_tag:tag_value
func CriticalPathFunction() {
  // ... 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 ...
}

Operation Name

The name of the operation (span.name) is determined automatically using the following precedence:

1. An explicit span.name:customOperationName tag specified as a directive argument
2. The function’s declared name (this does not apply to function literal expressions, which are anonymous)
3. The value of the very first tag provided to the directive arguments list

//dd:span tag-name:spanName other-tag:bar span.name:operationName
func tracedFunction() {
  // This function will be represented as a span named "operationName"
}

//dd:span tag-name:spanName other-tag:bar
func otherTracedFunction() {
  // This function will be represented as a span named "otherTracedFunction"
}

//dd:span tag-name:spanName other-tag:bar
tracedFunction := func() {
  // This function will be represented as a span named "spanName"
}

Error Results

If the annotated function returns an error result, any error returned by the function will be automatically attached to the corresponding trace span:

//dd:span
func failableFunction() (any, error) {
  // This span will have error information attached automatically.
  return nil, errors.ErrUnsupported
}

Prevent instrumentation of some code

You can use the //orchestrion:ignore directive to prevent orchestrion from performing any modification on the annotated code.

This can be used to prevent caller-side instrumentation from being applied to specific locations:

import "database/sql"

// Caller-side instrumentation normally happens within this function...
func normal() {
  // The following assignment will NOT be modified to add any caller-side
  // instrumentation as it is opted out by the orchestrion:ignore directive:
  //orchestrion:ignore
  db, err := sql.Open("driver-name", "database=example")
  // ...
}

// Caller-side instrumentation will NOT happen in the following function
// as it is annotated with orchestrion:ignore.
//orchestrion:ignore
func excluded() {
  // The following assignment will NOT be modified to add any caller-side
  // instrumentation as the surrounding context is excluded by an
  // orchestrion:ignore directive:
  db, err := sql.Open("driver-name", "database=example")
  // ...
}

Some of the instrumentation performed by orchestrion is done callee-side (or library-side), meaning the integration is added directly within the dependency itself. In such cases, it is not possible to locally opt out of such integrations.

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 runtime.

Troubleshooting

To troubleshoot builds that orchestrion manages, see Troubleshooting Go Compile-Time Instrumentation.

Add the tracer library to your application

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

Activate Go integrations to create spans

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.