Tracing Go Applications

このページは日本語には対応しておりません。随時翻訳に取り組んでいます。翻訳に関してご質問やご意見ございましたら、お気軽にご連絡ください。

Compatibilty 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

If you already have a Datadog account you can find step-by-step instructions in our in-app guides for either host-based or container-based set ups.

First install and configure the Datadog Agent. See the additional documentation for tracing Docker applications or Kubernetes applications.

Next, install the Go tracer from its canonical import path:

go get gopkg.in/DataDog/dd-trace-go.v1/ddtrace

You are now ready to import the tracer and start instrumenting 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. The list of supported integrations is in the compatibility section. Note that packages must be imported.

Configuration

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

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][73] documentation for recommendations on how to configure these environment variables.

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.WithVersion("abc123"),
    )
    defer tracer.Stop()
}

Change Agent Hostname

The Go Tracing Module automatically looks for and initializes with the environment variables DD_AGENT_HOST and DD_AGENT_APM_PORT.

But 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()
}

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][74] 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.