orchestrion

README

Orchestrion

Automatic compile-time instrumentation of Go code.

Overview

Orchestrion processes Go source code at compilation time and automatically inserts instrumentation. This instrumentation produces Datadog APM traces from the instrumented code and supports Datadog Application Security Management.

[!IMPORTANT] Orchestrion is under active development. The supported features are rapidly growing, and the user experiece may evolve with future releases.

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

1. Install Orchestrion:

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

2. Optional: project go.mod registration

   You can automatically add orchestrion to your project's dependencies by running:

   $ orchestrion pin
   

   This will:

   1. Create a new orchestrion.tool.go file containing content similar to:

      // Code generated by `orchestrion pin`; DO NOT EDIT.
      
      // This file is generated by `orchestrion pin`, and is used to include a blank import of the
      // orchestrion package(s) so that `go mod tidy` does not remove the requirements from go.mod.
      // This file should be checked into source control.
      
      //go:build tools
      
      package tools
      
      import _ "github.com/datadog/orchestrion"
      

   2. Run go get github.com/datadog/orchstrion@<current-release> to make sure the project version corresponds to the one currently being used
   3. Run go mod tidy to make sure your go.mod and go.sum files are up-to-date

   If you do not run this command, it will be done automatically when required. Once done, the version of orchestrion used by this project can be controlled directly using the go.mod file, as you would control any other dependency.

3. Prefix your go commands with orchestrion:

   $ orchestrion go build .
   $ orchestrion go test -race ./...
   

   If you have not run orchestrion pin, you may see a message similar to the following appear, as orchestrion pin is automatically executed:

   ╭──────────────────────────────────────────────────────────────────────────────╮
   │                                                                              │
   │  Warning: github.com/datadog/orchestrion is not present in your go.mod       │
   │  file.                                                                       │
   │  In order to ensure build reliability and reproductibility, orchestrion      │
   │  will now add itself in your go.mod file by:                                 │
   │                                                                              │
   │      1. creating a new file named orchestrion.tool.go                        │
   │      2. running go get github.com/datadog/orchestrion@v0.7.0-dev.2           │
   │      3. running go mod tidy                                                  │
   │                                                                              │
   │  You should commit the resulting changes into your source control system.    │
   │                                                                              │
   ╰──────────────────────────────────────────────────────────────────────────────╯
   

   Alternative

   Orchestrion at the core is a standard Go toolchain -toolexec proxy. Instead of using orchestrion go, you can also manually provide the -toolexec argument to go commands that accept it:

   $ go build -toolexec 'orchestrion toolexec' .
   $ go test -toolexec 'orchestrion toolexec' -race .
   

The version of orchestrion used to compile your project is ultimately tracked in the go.mod file. You can manage it in the same way you manage any other dependency, and updating to the latest release is as simple as doing:

$ go get github.com/datadog/orchestrion@latest

Supported libraries

Orchestrion supports automatic tracing of the following libraries:

Library	Since	Notes
database/sql	v0.7.0	Aspect
github.com/gin-gonic/gin	v0.7.0	Aspect
github.com/go-chi/chi/v5	v0.7.0	Aspect
github.com/go-chi/chi	v0.7.0	Aspect
github.com/go-redis/redis/v7	v0.7.0	Aspect
github.com/go-redis/redis/v8	v0.7.0	Aspect
github.com/gofiber/fiber/v2	v0.7.0	Aspect
github.com/gomodule/redigo/redis	v0.7.0	Aspect
github.com/gorilla/mux	v0.7.0	Aspect. Cannot be opted out of via //dd:ignore
github.com/jinzhu/gorm	v0.7.0	Aspect
github.com/labstack/echo/v4	v0.7.0	Aspect
google.golang.org/grpc	v0.7.0	Aspect
gorm.io/gorm	v0.7.0	Aspect
net/http	v0.7.0	Client / Server
go.mongodb.org/mongo-driver/mongo	v0.7.3	Aspect
github.com/aws-sdk-go/aws	v0.7.4	Aspect
github.com/hashicorp/vault	v0.7.4	Aspect
github.com/IBM/sarama	v0.7.4	Aspect
github.com/Shopify/sarama	v0.7.4	Aspect
k8s.io/client-go	v0.7.4	Aspect
log/slog	v0.7.4	Aspect
os	v0.8.0	Aspect
github.com/aws/aws-sdk-go-v2	v0.8.0	Aspect
github.com/redis/go-redis/v9	v0.8.0	Aspect
github.com/gocql/gocql	v0.8.0	Aspect

Calls to these libraries are instrumented with library-specific code adding tracing to them, including support for distributed traces.

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

Orchestrion's 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.