Configuring the Go Tracing Library

After you set up the tracing library with your code, configure the Agent to collect APM data, and activate the Go integration, optionally configure the tracing library as desired.

Datadog recommends using DD_ENV, DD_SERVICE, and DD_VERSION to set env, service, and version for your services.

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

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

DD_VERSION
Set the application’s version, for example: 1.2.3, 6c44da20, 2020.02.13
DD_SERVICE
The service name to be used for this application.
DD_ENV
Set the application’s environment, for example: prod, pre-prod, staging.
DD_AGENT_HOST
Default: localhost
Override the default trace Agent host address for trace submission.
DD_TRACE_AGENT_PORT
Default: 8126
Overrides the default trace Agent port for Datadog trace submission. If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then the library configuration DD_DOGSTATSD_PORT must match it.
DD_DOGSTATSD_PORT
Default: 8125
Overrides the default trace Agent port for DogStatsD metric submission. If the Agent configuration sets dogstatsd_port or DD_DOGSTATSD_PORT to something other than the default 8125, then the library configuration DD_DOGSTATSD_PORT must match it.
DD_TRACE_SAMPLING_RULES
Default: nil
A JSON array of objects. Each object must have a "sample_rate". The "name" and "service" fields are optional. The "sample_rate" value must be between 0.0 and 1.0 (inclusive). Rules are applied in configured order to determine the trace’s sample rate. For more information, see Ingestion Mechanisms.
Examples:
  • Set the sample rate to 20%: '[{"sample_rate": 0.2}]'
  • Set the sample rate to 10% for services starting with ‘a’ and span name ‘b’ and set the sample rate to 20% for all other services: '[{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}]'.
DD_TRACE_SAMPLE_RATE
Enable ingestion rate control.
DD_SPAN_SAMPLING_RULES
Default: nil
A JSON array of objects. Rules are applied in configured order to determine the span’s sample rate. The sample_rate value must be between 0.0 and 1.0 (inclusive). For more information, see Ingestion Mechanisms.
Example:
  • Set the span sample rate to 50% for the service my-service and operation name http.request, up to 50 traces per second: '[{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]'
DD_TRACE_RATE_LIMIT
Maximum number of spans to sample per-second, per-Go process. Defaults to 100 when DD_TRACE_SAMPLE_RATE is set. Otherwise, delegates rate limiting to the Datadog Agent.
DD_TAGS
Default: []
A list of default tags to be added to every span and profile. Tags can be separated by commas or spaces, for example: layer:api,team:intake or layer:api team:intake.
DD_TRACE_STARTUP_LOGS
Default: true
Enable startup configuration and the diagnostic log.
DD_TRACE_DEBUG
Default: false
Enable debug logging in the tracer.
DD_TRACE_ENABLED
Default: true
Enable web framework and library instrumentation. When false, the application code doesn’t generate any traces.
DD_SERVICE_MAPPING
Default: null
Dynamically rename services through configuration. Services can be separated by commas or spaces, for example: mysql:mysql-service-name,postgres:postgres-service-name, mysql:mysql-service-name postgres:postgres-service-name.
DD_INSTRUMENTATION_TELEMETRY_ENABLED
Default: false
Datadog may collect environmental and diagnostic information about your system to improve the product. When false, this telemetry data will not be collected.
DD_TRACE_CLIENT_IP_ENABLED
Default: false
Enable client IP collection from relevant IP headers in HTTP request spans. Added in version 1.47.0
DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED
Default: false
Enable generation of 128-bit trace IDs. By default, only 64-bit IDs are generated.
DD_TRACE_128_BIT_TRACEID_LOGGING_ENABLED
Default: false
Enable printing of the full 128-bit ID when formatting a span with ‘%v’. When false (default), only the low 64-bits of the trace ID are printed, formatted as an integer. This means if the trace ID is only 64 bits, the full ID is printed. When true, the trace ID is printed as a full 128-bit ID in hexadecimal format. This is the case even if the ID itself is only 64 bits.

Configure APM environment name

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

Trace context propagation for distributed tracing

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

Distributed headers injection and extraction is controlled by configuring injection/extraction styles. Supported styles are: tracecontext, Datadog, B3, and B3 single header.

  • Configure injection styles using the DD_PROPAGATION_STYLE_INJECT=tracecontext,B3 environment variable.
  • Configure extraction styles using the DD_PROPAGATION_STYLE_EXTRACT=tracecontext,B3 environment variable.
  • Configure both injection and extraction styles using the DD_TRACE_PROPAGATION_STYLE=tracecontext,B3 environment variable.

The values of these environment variables are comma-separated lists of header styles enabled for injection or extraction. By default, the tracecontext,Datadog styles are enabled.

To disable trace context propagation, set the value of the environment variables to none.

  • Disable injection styles using the DD_PROPAGATION_STYLE_INJECT=none environment variable.
  • Disable extraction styles using the DD_PROPAGATION_STYLE_EXTRACT=none environment variable.
  • Disable all trace context propagation (both inject and extract) using the DD_PROPAGATION_STYLE=none environment variable.

If multiple environment variables are set, DD_PROPAGATION_STYLE_INJECT and DD_PROPAGATION_STYLE_EXTRACT override any value provided in DD_PROPAGATION_STYLE.

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.

Further reading

Additional helpful documentation, links, and articles:

Source codeGITHUB more more Package pageGODOC more more Explore your services, resources and tracesDOCUMENTATION more more