README
¶
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 visiblity into bottlenecks and troublesome requests.
The packagegithub.com/DataDog/dd-trace-go/v2/ddtrace/tracerallows 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 packagegithub.com/DataDog/dd-trace-go/v2/ddtrace/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 packagegithub.com/DataDog/dd-trace-go/v2/profilerallows 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:
go get github.com/DataDog/dd-trace-go/v2/contrib/gorilla/mux
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.
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. For Go the two latest releases are GA supported and the version before that is in Maintenance. We do make efforts to support older releases, but generally these releases are considered Legacy. This library only officially supports first class ports of Go.
| Level | Support provided |
|---|---|
| General Availability (GA) | Full implementation of all features. Full support for new features, bug & security fixes. |
| Maintenance | Full implementation of existing features. May receive new features. Support for bug & security fixes only. |
| Legacy | Legacy implementation. May have limited function, but no maintenance provided. Not guaranteed to compile the latest version of dd-trace-go. Contact our customer support team for special requests. |
Supported Versions
| Go Version | Support level |
|---|---|
| 1.22 | GA |
| 1.21 | GA |
| 1.20 | Maintenance |
| 1.19 | Legacy |
- Datadog's Trace Agent >= 5.21.1
Package Versioning
A Minor version change will be released whenever a new version of Go is released. At that time the newest version of Go is added to GA, the second oldest supported version moved to Maintenance and the oldest previously supported version dropped to Legacy. For example: For a dd-trace-go version 1.37.*
| Go Version | Support |
|---|---|
| 1.18 | GA |
| 1.17 | GA |
| 1.16 | Maintenance |
Then after Go 1.19 is released there will be a new dd-trace-go version 1.38.0 with support:
| Go Version | Support |
|---|---|
| 1.19 | GA |
| 1.18 | GA |
| 1.17 | Maintenance |
| 1.16 | Legacy |
Contributing
Before considering contributions to the project, please take a moment to read our brief contribution guidelines.
Testing
Tests can be run locally using the Go toolset. To run integration tests locally, you should set the INTEGRATION environment variable. The dependencies of the integration tests are best run via Docker. To find
out the versions and the set-up take a look at our docker-compose config.
The best way to run the entire test suite is using the test.sh script. You'll need Docker and docker-compose installed. If this is your first time running the tests, you should run ./test.sh -t to install any missing test tools/dependencies. Run ./test.sh --all to run all of the integration tests through the docker-compose environment. Run ./test.sh --help for more options.
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
Directories
¶
| Path | Synopsis |
|---|---|
|
Package appsec provides application security features in the form of SDK functions that can be manually called to monitor specific code paths and data.
|
Package appsec provides application security features in the form of SDK functions that can be manually called to monitor specific code paths and data. |
|
contrib
|
|
|
99designs/gqlgen
Module
|
|
|
IBM/sarama
Module
|
|
|
IBM/sarama.v1
Module
|
|
|
Shopify/sarama
Module
|
|
|
aws/aws-sdk-go
Module
|
|
|
aws/aws-sdk-go-v2
Module
|
|
|
bradfitz/gomemcache
Module
|
|
|
database/sql
Module
|
|
|
dimfeld/httptreemux.v5
Module
|
|
|
elastic/go-elasticsearch.v6
Module
|
|
|
emicklei/go-restful.v3
Module
|
|
|
gin-gonic/gin
Module
|
|
|
globalsign/mgo
Module
|
|
|
go-chi/chi
Module
|
|
|
go-chi/chi.v5
Module
|
|
|
go-pg/pg.v10
Module
|
|
|
go-redis/redis
Module
|
|
|
go-redis/redis.v7
Module
|
|
|
go-redis/redis.v8
Module
|
|
|
go.mongodb.org/mongo-driver
Module
|
|
|
gocql/gocql
Module
|
|
|
gofiber/fiber.v2
Module
|
|
|
gomodule/redigo
Module
|
|
|
google.golang.org/api
Module
|
|
|
google.golang.org/grpc
Module
|
|
|
gorilla/mux
Module
|
|
|
gorm.io/gorm.v1
Module
|
|
|
graph-gophers/graphql-go
Module
|
|
|
graphql-go/graphql
Module
|
|
|
hashicorp/consul
Module
|
|
|
hashicorp/vault
Module
|
|
|
jackc/pgx.v5
Module
|
|
|
jmoiron/sqlx
Module
|
|
|
julienschmidt/httprouter
Module
|
|
|
k8s.io/client-go
Module
|
|
|
labstack/echo.v4
Module
|
|
|
miekg/dns
Module
|
|
|
net/http
Module
|
|
|
olivere/elastic
Module
|
|
|
olivere/elastic.v5
Module
|
|
|
redis/go-redis.v9
Module
|
|
|
segmentio/kafka-go
Module
|
|
|
sirupsen/logrus
Module
|
|
|
syndtr/goleveldb
Module
|
|
|
tidwall/buntdb
Module
|
|
|
twitchtv/twirp
Module
|
|
|
urfave/negroni
Module
|
|
|
valyala/fasthttp
Module
|
|
|
valyala/fasthttp.v1
Module
|
|
|
Package ddtrace contains the interfaces that specify the implementations of Datadog's tracing library, as well as a set of sub-packages containing various implementations: our native implementation ("tracer") and a mock tracer to be used for testing ("mocktracer").
|
Package ddtrace contains the interfaces that specify the implementations of Datadog's tracing library, as well as a set of sub-packages containing various implementations: our native implementation ("tracer") and a mock tracer to be used for testing ("mocktracer"). |
|
ext
Package ext contains a set of Datadog-specific constants.
|
Package ext contains a set of Datadog-specific constants. |
|
mocktracer
Package mocktracer provides a mock implementation of the tracer used in testing.
|
Package mocktracer provides a mock implementation of the tracer used in testing. |
|
opentelemetry
Package opentelemetry provides a wrapper on top of the Datadog tracer that can be used with OpenTelemetry.
|
Package opentelemetry provides a wrapper on top of the Datadog tracer that can be used with OpenTelemetry. |
|
tracer
Package tracer contains Datadog's core tracing client.
|
Package tracer contains Datadog's core tracing client. |
|
appsec/dyngo
Package dyngo is the Go implementation of Datadog's Instrumentation Gateway which provides an event-based instrumentation API based on a stack representation of instrumented functions along with nested event listeners.
|
Package dyngo is the Go implementation of Datadog's Instrumentation Gateway which provides an event-based instrumentation API based on a stack representation of instrumented functions along with nested event listeners. |
|
appsec/emitter
Package emitter provides functions and types used to instrument go libraries to integrate them with Datadog AppSec features.
|
Package emitter provides functions and types used to instrument go libraries to integrate them with Datadog AppSec features. |
|
appsec/emitter/graphqlsec
Package graphql is the GraphQL instrumentation API and contract for AppSec defining an abstract run-time representation of AppSec middleware.
|
Package graphql is the GraphQL instrumentation API and contract for AppSec defining an abstract run-time representation of AppSec middleware. |
|
appsec/emitter/grpcsec
Package grpcsec is the gRPC instrumentation API and contract for AppSec defining an abstract run-time representation of gRPC handlers.
|
Package grpcsec is the gRPC instrumentation API and contract for AppSec defining an abstract run-time representation of gRPC handlers. |
|
appsec/emitter/httpsec
Package httpsec defines is the HTTP instrumentation API and contract for AppSec.
|
Package httpsec defines is the HTTP instrumentation API and contract for AppSec. |
|
appsec/listener
Package listener provides functions and types used to listen to AppSec instrumentation events produced by code usintrumented using the functions and types found in github.com/DataDog/dd-trace-go/v2/internal/appsec/emitter.
|
Package listener provides functions and types used to listen to AppSec instrumentation events produced by code usintrumented using the functions and types found in github.com/DataDog/dd-trace-go/v2/internal/appsec/emitter. |
|
appsec/trace
Package trace provides functions to annotate trace spans with AppSec related information.
|
Package trace provides functions to annotate trace spans with AppSec related information. |
|
contrib/httptrace
Package httptrace provides functionalities to trace HTTP requests that are commonly required and used across contrib/** integrations.
|
Package httptrace provides functionalities to trace HTTP requests that are commonly required and used across contrib/** integrations. |
|
contrib/namingschematest
Package namingschematest provides utilities to test naming schemas across different integrations.
|
Package namingschematest provides utilities to test naming schemas across different integrations. |
|
globalconfig
Package globalconfig stores configuration which applies globally to both the tracer and integrations.
|
Package globalconfig stores configuration which applies globally to both the tracer and integrations. |
|
hostname/cachedfetch
Package cachedfetch provides a read-through cache for fetched values.
|
Package cachedfetch provides a read-through cache for fetched values. |
|
hostname/validate
Package validate provides hostname validation helpers
|
Package validate provides hostname validation helpers |
|
httpmem
Package httpmem provides an in-memory HTTP server and client, for testing
|
Package httpmem provides an in-memory HTTP server and client, for testing |
|
log
Package log provides logging utilities for the tracer.
|
Package log provides logging utilities for the tracer. |
|
namingschema
Package namingschema allows to use the naming schema from the integrations to set different service and span/operation names based on the value of the DD_TRACE_SPAN_ATTRIBUTE_SCHEMA environment variable.
|
Package namingschema allows to use the naming schema from the integrations to set different service and span/operation names based on the value of the DD_TRACE_SPAN_ATTRIBUTE_SCHEMA environment variable. |
|
normalizer
Package normalizer provides tag normalization
|
Package normalizer provides tag normalization |
|
osinfo
Package osinfo provides information about the current operating system release
|
Package osinfo provides information about the current operating system release |
|
telemetry
Package telemetry implements a client for sending telemetry information to Datadog regarding usage of an APM library such as tracing or profiling.
|
Package telemetry implements a client for sending telemetry information to Datadog regarding usage of an APM library such as tracing or profiling. |
|
telemetry/telemetrytest
Package telemetrytest provides a mock implementation of the telemetry client for testing purposes
|
Package telemetrytest provides a mock implementation of the telemetry client for testing purposes |
|
traceprof
Package traceprof contains shared logic for cross-cutting tracer/profiler features.
|
Package traceprof contains shared logic for cross-cutting tracer/profiler features. |
|
traceprof/testapp
Package testapp has the protbuf/grpc definitions for the test application implemented in traceproftest.
|
Package testapp has the protbuf/grpc definitions for the test application implemented in traceproftest. |
|
Package profiler periodically collects and sends profiles to the Datadog API.
|
Package profiler periodically collects and sends profiles to the Datadog API. |
|
internal/fastdelta
Package fastdelta tries to match up samples between two pprof profiles and take their difference.
|
Package fastdelta tries to match up samples between two pprof profiles and take their difference. |
|
internal/immutable
Package immutable provides read-only types
|
Package immutable provides read-only types |
|
internal/pproflite
Package pproflite implements zero-allocation pprof encoding and decoding.
|
Package pproflite implements zero-allocation pprof encoding and decoding. |
|
internal/pprofutils
Package pprofutils is a fork of github.com/felixge/pprofutils, see README.
|
Package pprofutils is a fork of github.com/felixge/pprofutils, see README. |
|
Package v1internal provides support for v1 as frontend of v2 implementation.
|
Package v1internal provides support for v1 as frontend of v2 implementation. |
|
globalconfig
Package globalconfig stores configuration which applies globally to both the tracer and integrations.
|
Package globalconfig stores configuration which applies globally to both the tracer and integrations. |
|
namingschema
Package namingschema allows to use the naming schema from the integrations to set different service and span/operation names based on the value of the DD_TRACE_SPAN_ATTRIBUTE_SCHEMA environment variable.
|
Package namingschema allows to use the naming schema from the integrations to set different service and span/operation names based on the value of the DD_TRACE_SPAN_ATTRIBUTE_SCHEMA environment variable. |
|
namingschematest
Package namingschematest provides support for automated testing of Go packages using the v1 API.
|
Package namingschematest provides support for automated testing of Go packages using the v1 API. |
|
normalizer
Package normalizer provides tag normalization This package is not intended for use by external consumers, no API stability is guaranteed.
|
Package normalizer provides tag normalization This package is not intended for use by external consumers, no API stability is guaranteed. |
|
telemetry
Package telemetry implements a client for sending telemetry information to Datadog regarding usage of an APM library such as tracing or profiling.
|
Package telemetry implements a client for sending telemetry information to Datadog regarding usage of an APM library such as tracing or profiling. |