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] 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 (library-side)
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 (library-side) / 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
cloud.google.com/go/pubsub	v0.9.0	Aspect (library-side)
github.com/99designs/gqlgen	v0.9.1	Aspect
github.com/redis/go-redis	v0.9.1	Aspect
github.com/graph-gophers/graphql-go	v0.9.1	Aspect
github.com/graphql-go/graphql	v0.9.1	Aspect
testing	v0.9.3	Aspect with Test Optimization
github.com/jackc/pgx	v0.9.4	Aspect
github.com/elastic/go-elasticsearch	v0.9.4	Aspect
github.com/twitchtv/twirp	v0.9.4	Aspect
github.com/segmentio/kafka-go	v0.9.4	Aspect (library-side)
github.com/confluentinc/confluent-kafka-go/kafka	v0.9.4	Aspect (library-side)
github.com/confluentinc/confluent-kafka-go/kafka/v2	v0.9.4	Aspect (library-side)
github.com/julienschmidt/httprouter	v0.9.4	Aspect (library-side)
github.com/sirupsen/logrus	v0.9.4	Aspect

Library Side

Most integrations are added by orchestrion at the call site, making it possible to use the //orchestrion:ignore directive to locally opt out of instrumentation for a specific instance of a component.

Some integrations are however injected directly into the library (library-side instrumentation, also called callee-side instrumentation), and are hence always active and cannot be locally opted out. If you have a use-case where you need to locally opt out of a library-side instrumentation, please let us know about it by filing a GitHub issue.

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][dd-doc]. [dd-doc]: https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/go/?tab=compiletimeinstrumentation

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.