Configuring the C++ Tracing Library
After you set up the tracing library with your code and configure the Agent to collect APM data, optionally configure the tracing library as desired, including setting up Unified Service Tagging.
It is recommended to use DD_SERVICE, DD_ENV, and DD_VERSION to set env, service and version for your services. Refer to the Unified Service Tagging docummentation recommendations on which value to set for environment variables.
Environment variables
To configure the tracer using environment variables, set the variables before launching the instrumented application.
Unified service tagging
DD_SERVICE- Since: v0.1.0
Sets the service name. DD_ENV- Since: v0.1.0
Example: prod, pre-prod, or staging
Adds the env tag with the specified value to all generated spans. DD_VERSION- Since: v0.1.0
Example: 1.2.3, 6c44da20, 2020.02.13
Sets the version of the service.
Traces
DD_TRACE_ENABLED- Since: 0.1.0
Default: true
Submit or not traces to the Datadog Agent.
When false, the library stop sending traces to the Datadog Agent. However, the library continues to generate traces, report telemetry and poll for remote configuration updates. DD_TRACE_AGENT_PORT- Since: v0.1.0
Default: 8126
Sets the port where traces are sent (the port where the Agent is listening for connections). Ignored if DD_TRACE_AGENT_URL is set. If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then DD_TRACE_AGENT_PORT or DD_TRACE_AGENT_URL must match it. DD_TRACE_AGENT_URL- Since: v0.1.0
Default: http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT> if they are set, or http://localhost:8126.
Examples:
HTTP URL: http://localhost:8126
Unix Domain Socket: unix:///var/run/datadog/apm.socket
Sets the URL endpoint where traces are sent. Overrides DD_AGENT_HOST and DD_TRACE_AGENT_PORT if set. This URL supports HTTP, HTTPS, and Unix address schemes.
If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then DD_TRACE_AGENT_PORT or DD_TRACE_AGENT_URL must match it. DD_TRACE_RATE_LIMIT- Since: 0.1.0
Default: 200
Maximum number of traces allowed to be submitted per second. DD_TRACE_SAMPLE_RATE- Since: 0.1.0
Default: The Datadog Agent default rate or 1.0.
Sets the sampling rate for all generated traces. The value must be between 0.0 and 1.0 (inclusive). By default, the sampling rate is delegated to the Datadog Agent. If no sampling rate is set by the Datadog Agent, then the default is 1.0.
Note: DD_TRACE_SAMPLE_RATE is deprecated in favor of DD_TRACE_SAMPLING_RULES. DD_TRACE_SAMPLING_RULES- Since: v0.1.0
Default: null
Examples:
Set the sample rate to 20%: [{"sample_rate": 0.2}]
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}]'
A JSON array of objects. Each object must have a sample_rate, and 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.
DD_SPAN_SAMPLING_RULES- Version: v0.1.0
Default: null
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). DD_SPAN_SAMPLING_RULES_FILE- Since: 0.1.0
Points to a JSON file that contains the span sampling rules. See DD_SPAN_SAMPLING_RULES for the rule format. DD_TRACE_REPORT_HOSTNAME- Since: 0.1.0
Default: false
Adds the hostname tag with the result of gethostname. DD_TRACE_STARTUP_LOGS- Since: 0.1.0
Default: true
Log the tracer configuration once the tracer is fully initialized.
DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED- Since: 0.1.6
Default: true
If true, the tracer will generate 128-bit trace IDs.
If false, the tracer will generate legacy 64-bit trace IDs. DD_REMOTE_CONFIGURATION_ENABLED- Since: 0.2.0
Default: true
Enable the capability that allows to remotely configure and change the behavior of the tracer.
When false this feature is disabled.
For more information, see Remote Configuration. DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS- Since: 0.2.0
Default: 5.0
Sets how often, in seconds, the Datadog Agent is queried for Remote Configuration updates. DD_TRACE_DELEGATE_SAMPLING- Version: 0.2.0
Default: false
If true, delegate trace sampling decision to a child service and prefer the resulting decision over its own, if appropriate.
Agent
DD_TAGS- Since: v0.1.0
Example: team:intake,layer:api,foo:bar
A comma separated list of key:value pairs to be added to all generated spans. DD_AGENT_HOST- Since: v0.1.0
Default: localhost
Sets the host where traces are sent (the host running the Agent). Can be a hostname or an IP address. Ignored if DD_TRACE_AGENT_URL is set. DD_INSTRUMENTATION_TELEMETRY_ENABLED- Since: 0.1.12
Default: true
Datadog may collect environmental and diagnostic information about your system to improve the product. When false, telemetry data are not collected.
Trace context propagation
DD_PROPAGATION_STYLE- Since: 0.1.0
Comma separated list of propagation styles to use when extracting and injecting tracing context.
When multiple values are given, the order of matching is based on the order of values. DD_TRACE_PROPAGATION_STYLE_INJECT- Since: v0.1.6
Default: datadog,tracecontext
Accepted values: datadog, tracecontext, b3
Comma separated list of propagation styles to use when injecting tracing context.
When multiple values are given, the order of matching is based on the order of values. DD_TRACE_PROPAGATION_STYLE_EXTRACT- Since: v0.1.6
Default: datadog,tracecontext
Accepted values: datadog, tracecontext, b3
Comma separated list of propagation styles to use when extracting tracing context.
When multiple values are given, the order of matching is based on the order of values.
Further Reading
Additional helpful documentation, links, and articles:
