DataDog/dd-trace-go

Datadog Client Libraries for Go

This repository contains Go packages for the client-side components of the Datadog product suite for Application Performance Monitoring, Continuous Profiling and Application Security Monitoring of Go applications.

• Datadog Application Performance Monitoring (APM): Trace requests as they flow across web servers, databases, and microservices so that developers have great visibility into bottlenecks and troublesome requests. The package github.com/DataDog/dd-trace-go/v2/ddtrace/tracer allows you to trace any piece of your Go code, and commonly used Go libraries can be automatically traced thanks to our out-of-the-box integrations which can be found in the package github.com/DataDog/dd-trace-go/v2/contrib.

• Datadog Go Continuous Profiler: Continuously profile your Go apps to find CPU, memory, and synchronization bottlenecks, broken down by function name, and line number, to significantly reduce end-user latency and infrastructure costs. The package github.com/DataDog/dd-trace-go/v2/profiler allows you to periodically collect and send Go profiles to the Datadog API.

• Datadog Application Security Management (ASM) provides in-app monitoring and protection against application-level attacks that aim to exploit code-level vulnerabilities, such as a Server-Side-Request-Forgery (SSRF), a SQL injection (SQLi), or Reflected Cross-Site-Scripting (XSS). ASM identifies services exposed to application attacks and leverages in-app security rules to detect and protect against threats in your application environment. ASM is not a standalone Go package and is transparently integrated into the APM tracer. You can simply enable it with DD_APPSEC_ENABLED=true.

Installing

This module contains many packages, but most users should probably install the two packages below:

go get github.com/DataDog/dd-trace-go/v2/ddtrace/tracer
go get github.com/DataDog/dd-trace-go/v2/profiler

Additionally there are many contrib packages, published as nested modules, that can be installed to automatically instrument and trace commonly used Go libraries such as net/http, gorilla/mux or database/sql/v2

go get github.com/DataDog/dd-trace-go/contrib/gorilla/mux/v2

If you installed more packages than you intended, you can use go mod tidy to remove any unused packages.

Documentation

• APM Tracing API
• APM Tracing Go Applications
• Continuous Go Profiler
• Application Security Monitoring
• If you are migrating from an older version of the tracer (e.g., 1.60.x) you may also find the migration document we've put together helpful.

Go Support Policy

Datadog APM for Go is built upon dependencies defined in specific versions of the host operating system, Go releases, and the Datadog Agent/API. dd-trace-go supports the two latest releases of Go, matching the official Go policy. This library only officially supports first class ports of Go.

Contributing

Before considering contributions to the project, please take a moment to read our brief contribution guidelines.

Testing

Tests can be run locally using make targets or Go toolset directly.

Using Make (Recommended):

Usage: make [target]

Targets:
  help                 Show this help message
  all                  Run complete build pipeline (tools, generate, lint, test)
  tools-install        Install development tools
  tools-install/checkmake Install checkmake binary for Makefile linting
  clean                Clean build artifacts
  clean-all            Clean everything including tools and temporary files
  generate             Run code generation
  lint                 Run linting checks
  lint/go              Run Go linting checks
  lint/go/fix          Fix linting issues automatically
  lint/shell           Run shell script linting checks
  lint/misc            Run miscellaneous linting checks (copyright, Makefiles)
  lint/action          Lint GitHub Actions workflows
  format               Format code
  format/go            Format Go code
  format/shell         install shfmt
  test                 Run all tests (core, integration, contrib)
  test/unit            Run unit tests
  test/appsec          Run tests with AppSec enabled
  test/contrib         Run contrib package tests
  test/integration     Run integration tests
  test-deadlock        Run tests with deadlock detection
  test-debug-deadlock  Run tests with debug and deadlock detection
  fix-modules          Fix module dependencies and consistency
  fix/go               Apply go fix modernizations to Go code
  fix/go/diff          Preview go fix modernizations (dry-run)
  apidiff              Run semantic API diff for ddtrace/tracer against main
  apidiff/incompatible Show only breaking (incompatible) API changes for ddtrace/tracer
  docs                 Generate and Update embedded documentation in README files
  upgrade/orchestrion  Upgrade Orchestrion and fix modules
  config-audit         Report which DD_* configs are migrated to internal/config

Direct Script Usage: For more control, you can use the scripts/test.sh script directly. You'll need Docker and docker-compose installed for integration tests. Run ./scripts/test.sh --help for all available options.

To run integration tests locally, you should set the INTEGRATION environment variable. The dependencies of the integration tests are best run via Docker. To get an idea about the versions and the set-up take a look at our docker-compose config.

If you're only interested in the tests for a specific integration it can be useful to spin up just the required containers via docker-compose. For example if you're running tests that need the mysql database container to be up:

docker compose -f docker-compose.yaml -p dd-trace-go up -d mysql