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,key:value
or layer:api team:intake key:value
. 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:
true
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_PARTIAL_FLUSH_ENABLED
- Default:
false
Enables incrementally flushing large traces to the Datadog Agent, reducing the chance of rejection by the Agent. Use only when you have long-lived traces or traces with many spans. Valid values are true
or false
.
Added in version 1.54.0. Only compatible with the Datadog Agent 7.26.0+. DD_TRACE_PARTIAL_FLUSH_MIN_SPANS
- Default:
1000
Number of spans within a trace that can be partially flushed to the Datadog Agent. DD_TRACE_PARTIAL_FLUSH_ENABLED
must be true
for partial flushing to occur.
Added in version 1.54.0. Only compatible with the Datadog Agent 7.26.0+. 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
The APM environment name may be configured in the Agent or using the WithEnv start option of the tracer.
Further reading
Additional helpful documentation, links, and articles: