Skip to content

Latest commit

 

History

History
236 lines (201 loc) · 15 KB

README.md

File metadata and controls

236 lines (201 loc) · 15 KB
Raw

Orchestrion

Documentation Latest Release GitHub go.mod Go version OpenSSF Scorecard

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/[email protected]           │
│      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

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.