Awesome
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
-
Install Orchestrion:
$ go install github.com/DataDog/orchestrion@latest
-
<details><summary>Optional: project <tt>go.mod</tt> registration</summary>
You can automatically add
orchestrion
to your project's dependencies by running:$ orchestrion pin
This will:
- 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"
- Run
go get github.com/DataDog/orchstrion@<current-release>
to make sure the project version corresponds to the one currently being used - Run
go mod tidy
to make sure yourgo.mod
andgo.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 thego.mod
file, as you would control any other dependency. - Create a new
-
Prefix your
go
commands withorchestrion
:$ orchestrion go build . $ orchestrion go test -race ./...
If you have not run
orchestrion pin
, you may see a message similar to the following appear, asorchestrion pin
is automatically executed:
<details><summary>Alternative</summary>╭──────────────────────────────────────────────────────────────────────────────╮ │ │ │ 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. │ │ │ ╰──────────────────────────────────────────────────────────────────────────────╯
Orchestrion at the core is a standard Go toolchain
-toolexec
proxy. Instead of usingorchestrion go
, you can also manually provide the-toolexec
argument togo
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 thego.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
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.