Tracing Go Applications

Compatibility Requirements

The Go Tracer requires Go 1.12+ and Datadog Agent >= 5.21.1. For a full list of supported libraries, visit the Compatibility Requirements page.

Installation and Getting Started

For configuration instructions and details about using the API, see the Datadog API documentation. For manual instrumentation, use the integrations section below for Go libraries and frameworks supporting automatic instrumentation.

For a description of the terminology used in APM, see the Getting started with APM section. For details about contributing, check the official repository README.md.

Consult the migration document if you need to migrate from an older version of the tracer (e.g. v<0.6.x) to the newest version.

Installation

Follow the in-app documentation (Recommended)

Follow the Quickstart instructions within the Datadog app for the best experience, including:

Step-by-step instructions scoped to your deployment configuration (hosts, Docker, Kubernetes, or Amazon ECS).
Dynamically set service, env, and version tags.
Enable the Continuous Profiler, ingesting 100% of traces , and Trace ID injection into logs during setup.

Otherwise, follow the instructions below to add the Datadog Tracing Library to your code.

Automatic Instrumentation

Datadog has a series of pluggable packages which provide out-of-the-box support for instrumenting a series of libraries and frameworks. A list of these packages can be found in the Compatibility Requirements page. To trace these integrations, import these packages into your application and follow the configuration instructions listed alongside each Integration.

Configuration

The Go tracer supports additional environment variables and functions for configuration. See all available options in the configuration documentation.

We highly recommend using DD_ENV, DD_SERVICE, and DD_VERSION to set env, service, and version for your services. Check out the Unified Service Tagging documentation for recommendations on how to configure these environment variables. These variables are available for versions 1.24.0+ of the Go tracer.

You may also elect to provide env, service, and version through the tracer’s API:

package main

import (
    "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func main() {
    tracer.Start(
        tracer.WithEnv("prod"),
        tracer.WithService("test-go"),
        tracer.WithServiceVersion("abc123"),
    )

    // When the tracer is stopped, it will flush everything it has to the Datadog Agent before quitting.
    // Make sure this line stays in your main function.
    defer tracer.Stop()
}

Configure the Datadog Agent for APM

Install and configure the Datadog Agent to receive traces from your now instrumented application. By default the Datadog Agent is enabled in your datadog.yaml file under apm_enabled: true and listens for trace traffic at localhost:8126. For containerized environments, follow the links below to enable trace collection within the Datadog Agent.

Dropdown

Set apm_non_local_traffic: true in your main datadog.yaml configuration file
See the specific setup instructions to ensure that the Agent is configured to receive traces in a containerized environment:

After having instrumented your application, the tracing client sends traces to localhost:8126 by default. If this is not the correct host and port change it by setting the below env variables:

DD_AGENT_HOST and DD_TRACE_AGENT_PORT.

You can also set a custom hostname and port in code:

package main

import (
    "net"

    "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func main() {
    addr := net.JoinHostPort(
        "custom-hostname",
        "1234",
    )
    tracer.Start(tracer.WithAgentAddr(addr))
    defer tracer.Stop()
}

To set up Datadog APM in AWS Lambda, see the Tracing Serverless Functions documentation.

Tracing is available for a number of other environments, such as Heroku, Cloud Foundry, AWS Elastic Beanstalk, and Azure App Services Extension.

For other environments, please refer to the Integrations documentation for that environment and contact support if you are encountering any setup issues.

Configure APM Environment Name

The APM environment name may be configured in the agent or using the WithEnv start option of the tracer.

B3 Headers Extraction and Injection

The Datadog APM tracer supports B3 headers extraction and injection for distributed tracing.

Distributed headers injection and extraction is controlled by configuring injection/extraction styles. Two styles are supported: Datadog and B3.

Configure injection styles using the environment variable DD_PROPAGATION_STYLE_INJECT=Datadog,B3

Configure extraction styles using the environment variable DD_PROPAGATION_STYLE_EXTRACT=Datadog,B3

The values of these environment variables are comma separated lists of header styles that are enabled for injection or extraction. By default only the Datadog extraction style is enabled.

If multiple extraction styles are enabled, extraction attempts are made in the order that those styles are specified. The first successfully extracted value is used.