config

package
v2.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 19, 2026 License: Apache-2.0, BSD-3-Clause, Apache-2.0 Imports: 18 Imported by: 0

README

internal/config

This package is the single source of truth for initializing, reading, and updating tracer configuration.

Migration guidelines

When migrating a configuration value from another package (e.g. ddtrace/tracer):

  • Define the field on Config: add a private field on internal/config.Config.
  • Initialize it in loadConfig(): read from the config provider, which iterates over the following sources, in order, returning the default if no valid value found: local declarative config file, OTEL env vars, env vars, managed declarative config file
  • Expose an accessor: add a getter (and a setter if the value is updated at runtime).
  • Report telemetry in setters: setters should call configtelemetry.Report(...) with the correct origin.
  • Add the cross-product gate: every setter must call c.checkProductConflict(...) as its first action after acquiring the lock (see below).
  • Update callers: replace reads/writes on local "config" structs with calls to the singleton (internal/config.Get()).
  • Delete old state: remove the migrated field from any legacy config structs once no longer referenced.
  • Update tests: tests should call the singleton setter/getter (or set env vars) rather than mutating legacy fields.

Sample migration PR: https://github.com/DataDog/dd-trace-go/pull/4214

Cross-product gate

Every Set* method accepts an optional trailing ...Product parameter. When a product (tracer, profiler, etc.) sets a field via its programmatic API, it passes its Product identity:

c.internalConfig.SetServiceName(name, internalconfig.OriginCode, internalconfig.ProductTracer)

The gate enforces first-in-wins: if a different product already claimed the field via programmatic API, the call is silently rejected and a warning is logged. This prevents conflicting overrides like tracer.WithService("A") + profiler.WithService("B").

Key rules:

  • Env vars, defaults, and RC always pass through — the gate only activates for OriginCode.
  • Tests and integrations omit the product — they call SetServiceName(name, origin) without a product, bypassing the gate entirely.
  • Same product can call a setter multiple times — repeated calls from the same product just update the value.

Hot paths & performance guidelines

Some configuration accessors may be called in hot paths (e.g., span start/finish, partial flush logic). If benchmarks regress, ensure getters are efficient and do not:

  • Copy whole maps/slices on every call: prefer single-key lookup helpers like ServiceMapping/HasFeature over returning a map copy.
  • Take multiple lock/unlock pairs to read related fields: prefer a combined getter under one RLock, like PartialFlushEnabled().
  • Rethink defer in per-span/tight-loop getters: avoid defer in getters that are executed extremely frequently.
Cache config reads before loops (especially retry loops)

If you’re reading a config value inside any loop, prefer caching it once into a local variable before the loop:

  • Why: avoids repeated RLock/RUnlock overhead per iteration and keeps loop bounds/logging consistent if the value ever becomes dynamically updatable.
  • Example: cache SendRetries() and RetryInterval() once per flush send, and use the cached values inside the loop.
sendRetries := cfg.SendRetries()
retryInterval := cfg.RetryInterval()
for attempt := 0; attempt <= sendRetries; attempt++ {
	// ...
	time.Sleep(retryInterval)
}
Snapshot many-field hot paths under one lock

When a hot path reads ~3+ Config fields, define a snapshot struct + method in snapshots.go and have the caller read from the local copy.

  • Why: at high concurrency the bottleneck isn't blocking — readers don't block each other — but cache-line contention on sync.RWMutex's reader counter. Folding N RLock pairs into 1 collapses N atomic ops on a shared cache line into 1.
  • Convention: one bespoke struct per caller (e.g, a calling function StartSpan gets a snapshot API called SpanStartSnapshot).
  • Prior art: SpanStartSnapshot for tracer.StartSpan (13 → 1 RLock acquisitions, ~60% speedup on BenchmarkStartSpanConcurrent-8).

Documentation

Index

Constants

View Source 
const (
	OriginCode       = telemetry.OriginCode
	OriginCalculated = telemetry.OriginCalculated
	OriginDefault    = telemetry.OriginDefault
)

Re-exported origin constants for common configuration sources

View Source 
const (
	// DefaultRateLimit specifies the default rate limit per second for traces.
	// TODO: Maybe delete this. We will have defaults in supported_configuration.json anyway.
	DefaultRateLimit = 100.0

	// DefaultMaxTagsHeaderLen is the default value for DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH.
	DefaultMaxTagsHeaderLen = 512
	// MaxPropagatedTagsLength is the upper bound on DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH.
	MaxPropagatedTagsLength = 512
	// TraceMaxSize is the maximum number of spans we keep in memory for a
	// single trace. This is to avoid memory leaks. If more spans than this
	// are added to a trace, then the trace is dropped and the spans are
	// discarded. Adding additional spans after a trace is dropped does
	// nothing.
	TraceMaxSize = int(1e5)

	// Datadog trace protocol versions (agent wire format).
	TraceProtocolV04              = 0.4 // default
	TraceProtocolV1               = 1.0
	TraceProtocolVersionStringV04 = "0.4"
	TraceProtocolVersionStringV1  = "1.0"

	// Agent URL schemes supported by DD_TRACE_AGENT_URL.
	URLSchemeUnix  = "unix"
	URLSchemeHTTP  = "http"
	URLSchemeHTTPS = "https"

	// Trace API paths appended to the agent URL for each protocol.
	TracesPathV04 = "/v0.4/traces"
	TracesPathV1  = "/v1.0/traces"

	// OTLPContentTypeHeader is the Content-Type header value required for HTTP protobuf payloads.
	OTLPContentTypeHeader = "application/x-protobuf"
)

Variables

This section is empty.

Functions

func SetUseFreshConfig 

func SetUseFreshConfig(use bool)

Types

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config represents global configuration properties. Config instances should be obtained via Get() which always returns a non-nil value. Methods on Config assume a non-nil receiver and will panic if called on nil. Hot paths that read many fields within a single function should use a snapshot (see snapshots.go) to avoid per-field RLock contention on the reader counter.

func CreateNew added in v2.6.0 

func CreateNew() *Config

CreateNew returns a new global configuration instance. This function should be used when we need to create a new configuration instance. It build a new configuration instance and override the existing one loosing any programmatic configuration that would have been applied to the existing instance.

It shouldn't be used to get the global configuration instance to manipulate it but should be used when there is a need to reset the global configuration instance.

This is useful when we need to create a new configuration instance when a new product is initialized. Each product should have its own configuration instance and apply its own programmatic configuration to it.

If a customer starts multiple tracer with different programmatic configuration only the latest one will be used and available globally.

func Get 

func Get() *Config

Get returns the global configuration singleton. This function is thread-safe and can be called from multiple goroutines concurrently. The configuration is lazily initialized on first access using sync.Once, ensuring loadConfig() is called exactly once even under concurrent access.

func (*Config) APIKey added in v2.9.0 

func (c *Config) APIKey() string

APIKey returns the configured Datadog API key (DD_API_KEY).

func (*Config) AgentURL added in v2.8.0 

func (c *Config) AgentURL() *url.URL

AgentURL returns the URL to use for HTTP requests to the agent. For unix-scheme URLs this rewrites to the http://UDS_... form; otherwise it returns a copy of the configured URL.

func (*Config) CIVisibilityEnabled added in v2.6.0 

func (c *Config) CIVisibilityEnabled() bool

func (*Config) DataStreamsMonitoringEnabled added in v2.6.0 

func (c *Config) DataStreamsMonitoringEnabled() bool

func (*Config) Debug 

func (c *Config) Debug() bool

func (*Config) DebugAbandonedSpans added in v2.6.0 

func (c *Config) DebugAbandonedSpans() bool

func (*Config) DebugStack added in v2.6.0 

func (c *Config) DebugStack() bool

func (*Config) Env added in v2.6.0 

func (c *Config) Env() string

func (*Config) FeatureFlags added in v2.6.0 

func (c *Config) FeatureFlags() map[string]struct{}

func (*Config) GlobalSampleRate added in v2.6.0 

func (c *Config) GlobalSampleRate() float64

func (*Config) GlobalSampleRateConfig added in v2.8.0 

func (c *Config) GlobalSampleRateConfig() *DynamicConfig[float64]

GlobalSampleRateConfig returns the DynamicConfig for the global sample rate. Products use this to apply RC updates and read telemetry snapshots.

func (*Config) HasFeature added in v2.6.0 

func (c *Config) HasFeature(feat string) bool

HasFeature performs a single feature flag lookup without copying the underlying map. This is better than FeatureFlags() for hot paths (e.g., span creation) to avoid per-call allocations.

func (*Config) Hostname added in v2.6.0 

func (c *Config) Hostname() string

func (*Config) HostnameLookupError added in v2.6.0 

func (c *Config) HostnameLookupError() error

func (*Config) IsLambdaFunction added in v2.6.0 

func (c *Config) IsLambdaFunction() bool

func (*Config) LogDirectory added in v2.6.0 

func (c *Config) LogDirectory() string

func (*Config) LogStartup added in v2.6.0 

func (c *Config) LogStartup() bool

func (*Config) LogToStdout added in v2.6.0 

func (c *Config) LogToStdout() bool

func (*Config) LogsOTelEnabled added in v2.7.0 

func (c *Config) LogsOTelEnabled() bool

func (*Config) MaxTagsHeaderLen added in v2.9.0 

func (c *Config) MaxTagsHeaderLen() int

MaxTagsHeaderLen returns the configured cap on the x-datadog-tags header value (DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH). A non-positive value disables tags propagation.

func (*Config) OTLPExportMode added in v2.8.0 

func (c *Config) OTLPExportMode() bool

func (*Config) OTLPHeaders added in v2.8.0 

func (c *Config) OTLPHeaders() map[string]string

OTLPHeaders returns a copy of the OTLP headers map. If no headers are set, returns nil. Safe to return the full map because it is not called in hot paths.

func (*Config) OTLPTraceURL added in v2.8.0 

func (c *Config) OTLPTraceURL() string

func (*Config) PartialFlushEnabled added in v2.6.0 

func (c *Config) PartialFlushEnabled() (enabled bool, minSpans int)

PartialFlushEnabled returns the partial flushing configuration under a single read lock.

func (*Config) PeerServiceDefaultsEnabled added in v2.8.0 

func (c *Config) PeerServiceDefaultsEnabled() bool

func (*Config) PeerServiceMapping added in v2.8.0 

func (c *Config) PeerServiceMapping(from string) (to string, ok bool)

PeerServiceMapping performs a single mapping lookup without copying the underlying map. This is better than PeerServiceMappings() for hot paths to avoid per-call allocations.

func (*Config) PeerServiceMappings added in v2.8.0 

func (c *Config) PeerServiceMappings() map[string]string

PeerServiceMappings returns a copy of the peer service mappings map. If no mappings are set, returns nil. Not intended for hot paths — use PeerServiceMapping for single-key lookups to avoid per-call allocations.

func (*Config) ProfilerEndpoints added in v2.6.0 

func (c *Config) ProfilerEndpoints() bool

func (*Config) ProfilerHotspotsEnabled added in v2.6.0 

func (c *Config) ProfilerHotspotsEnabled() bool

func (*Config) RawAgentURL added in v2.8.0 

func (c *Config) RawAgentURL() *url.URL

RawAgentURL returns a copy of the configured trace agent URL before any transport-level rewriting (e.g. unix → http://UDS_...). Use AgentURL() for the URL suitable for HTTP requests.

func (*Config) ReportHostname added in v2.6.0 

func (c *Config) ReportHostname() bool

func (*Config) RetryInterval added in v2.6.0 

func (c *Config) RetryInterval() time.Duration

func (*Config) RuntimeMetricsEnabled added in v2.6.0 

func (c *Config) RuntimeMetricsEnabled() bool

func (*Config) RuntimeMetricsV2Enabled added in v2.6.0 

func (c *Config) RuntimeMetricsV2Enabled() bool

func (*Config) ServiceMapping added in v2.6.0 

func (c *Config) ServiceMapping(from string) (to string, ok bool)

ServiceMapping performs a single mapping lookup without copying the underlying map. This is better than ServiceMappings() for hot paths (e.g., span creation) to avoid per-call allocations.

func (*Config) ServiceMappings added in v2.6.0 

func (c *Config) ServiceMappings() map[string]string

ServiceMappings returns a copy of the service mappings map. If no service mappings are set, returns nil.

func (*Config) ServiceName added in v2.6.0 

func (c *Config) ServiceName() string

func (*Config) SetAgentURL added in v2.8.0 

func (c *Config) SetAgentURL(u *url.URL, origin telemetry.Origin, product ...Product)

func (*Config) SetCIVisibilityEnabled added in v2.6.0 

func (c *Config) SetCIVisibilityEnabled(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetDataStreamsMonitoringEnabled added in v2.6.0 

func (c *Config) SetDataStreamsMonitoringEnabled(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetDebug 

func (c *Config) SetDebug(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetDebugAbandonedSpans added in v2.6.0 

func (c *Config) SetDebugAbandonedSpans(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetDebugStack added in v2.6.0 

func (c *Config) SetDebugStack(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetEnv added in v2.6.0 

func (c *Config) SetEnv(env string, origin telemetry.Origin, product ...Product)

func (*Config) SetFeatureFlags added in v2.6.0 

func (c *Config) SetFeatureFlags(features []string, origin telemetry.Origin, product ...Product)

SetFeatureFlags adds to the feature flag set. No cross-product gate because this is additive, not a replacement.

func (*Config) SetGlobalSampleRate added in v2.6.0 

func (c *Config) SetGlobalSampleRate(rate float64, origin telemetry.Origin, product ...Product)

func (*Config) SetHostname added in v2.6.0 

func (c *Config) SetHostname(hostname string, origin telemetry.Origin, product ...Product)

func (*Config) SetIsLambdaFunction added in v2.6.0 

func (c *Config) SetIsLambdaFunction(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetLogDirectory added in v2.6.0 

func (c *Config) SetLogDirectory(directory string, origin telemetry.Origin, product ...Product)

func (*Config) SetLogStartup added in v2.6.0 

func (c *Config) SetLogStartup(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetLogToStdout added in v2.6.0 

func (c *Config) SetLogToStdout(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetLogsOTelEnabled added in v2.7.0 

func (c *Config) SetLogsOTelEnabled(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetOTLPExportMode added in v2.8.0 

func (c *Config) SetOTLPExportMode(v bool, origin telemetry.Origin, product ...Product)

func (*Config) SetPartialFlushEnabled added in v2.6.0 

func (c *Config) SetPartialFlushEnabled(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetPartialFlushMinSpans added in v2.6.0 

func (c *Config) SetPartialFlushMinSpans(minSpans int, origin telemetry.Origin, product ...Product)

func (*Config) SetPeerServiceDefaultsEnabled added in v2.8.0 

func (c *Config) SetPeerServiceDefaultsEnabled(enabled bool, origin telemetry.Origin)

func (*Config) SetPeerServiceMapping added in v2.8.0 

func (c *Config) SetPeerServiceMapping(from, to string, origin telemetry.Origin)

func (*Config) SetPeerServiceMappings added in v2.8.0 

func (c *Config) SetPeerServiceMappings(mappings map[string]string, origin telemetry.Origin)

func (*Config) SetProfilerEndpoints added in v2.6.0 

func (c *Config) SetProfilerEndpoints(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetProfilerHotspotsEnabled added in v2.6.0 

func (c *Config) SetProfilerHotspotsEnabled(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetRetryInterval added in v2.6.0 

func (c *Config) SetRetryInterval(interval time.Duration, origin telemetry.Origin, product ...Product)

func (*Config) SetRuntimeMetricsEnabled added in v2.6.0 

func (c *Config) SetRuntimeMetricsEnabled(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetRuntimeMetricsV2Enabled added in v2.6.0 

func (c *Config) SetRuntimeMetricsV2Enabled(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetServiceMapping added in v2.6.0 

func (c *Config) SetServiceMapping(from, to string, origin telemetry.Origin, product ...Product)

SetServiceMapping adds a single service mapping entry. No cross-product gate because this is additive, not a replacement.

func (*Config) SetServiceName added in v2.6.0 

func (c *Config) SetServiceName(name string, origin telemetry.Origin, product ...Product)

func (*Config) SetSpanTimeout added in v2.6.0 

func (c *Config) SetSpanTimeout(timeout time.Duration, origin telemetry.Origin, product ...Product)

func (*Config) SetStatsComputationEnabled added in v2.6.0 

func (c *Config) SetStatsComputationEnabled(enabled bool, origin telemetry.Origin, product ...Product)

func (*Config) SetTraceProtocol added in v2.8.0 

func (c *Config) SetTraceProtocol(v float64, origin telemetry.Origin, product ...Product)

func (*Config) SetTraceRateLimitPerSecond added in v2.6.0 

func (c *Config) SetTraceRateLimitPerSecond(rate float64, origin telemetry.Origin, product ...Product)

func (*Config) SetVersion added in v2.6.0 

func (c *Config) SetVersion(version string, origin telemetry.Origin, product ...Product)

func (*Config) SpanAttributeSchemaVersion added in v2.9.0 

func (c *Config) SpanAttributeSchemaVersion() int

SpanAttributeSchemaVersion returns the configured DD_TRACE_SPAN_ATTRIBUTE_SCHEMA version. Read on the span-creation hot path; avoids defer to minimise lock cost.

func (*Config) SpanStartSnapshot added in v2.9.0 

func (c *Config) SpanStartSnapshot() SpanStartSnapshot

SpanStartSnapshot returns a snapshot of the config fields read by tracer.StartSpan. Service mappings are not included because the lookup key (the resolved span service) isn't known until after this snapshot is read.

func (*Config) SpanTimeout added in v2.6.0 

func (c *Config) SpanTimeout() time.Duration

func (*Config) StatsComputationEnabled added in v2.6.0 

func (c *Config) StatsComputationEnabled() bool

func (*Config) TraceID128BitEnabled added in v2.8.0 

func (c *Config) TraceID128BitEnabled() bool

func (*Config) TraceProtocol added in v2.8.0 

func (c *Config) TraceProtocol() float64

func (*Config) TraceRateLimitPerSecond added in v2.6.0 

func (c *Config) TraceRateLimitPerSecond() float64

func (*Config) Version added in v2.6.0 

func (c *Config) Version() string

type DynamicConfig added in v2.8.0 

type DynamicConfig[T any] struct {
	// contains filtered or unexported fields
}

DynamicConfig is a thread-safe, RC-aware value store for a single configuration field. It tracks both the current value and the startup baseline (for RC reset). Consumers read via Get().

func (*DynamicConfig[T]) Get added in v2.8.0 

func (dc *DynamicConfig[T]) Get() T

Get returns the current value.

func (*DynamicConfig[T]) HandleRC added in v2.8.0 

func (dc *DynamicConfig[T]) HandleRC(val *T) bool

HandleRC processes a remote config update. If val is non-nil, the value is updated; if nil, the field is reset to its startup value. Reports the new value to telemetry when changed. Returns true if the value was changed.

type Origin added in v2.6.0 

type Origin = telemetry.Origin

Origin represents where a configuration value came from. Re-exported so callers don't need to import internal/telemetry.

type Product added in v2.8.0 

type Product string

Product identifies which product is setting a config value via programmatic API. 

const (
	ProductTracer   Product = "tracer"
	ProductProfiler Product = "profiler"
)

type SpanStartSnapshot added in v2.9.0 

type SpanStartSnapshot struct {
	ServiceName             string
	Env                     string
	Version                 string
	Hostname                string
	ReportHostname          bool
	DebugStack              bool
	DebugAbandonedSpans     bool
	ProfilerHotspotsEnabled bool
	ProfilerEndpoints       bool
}

Source Files

View all Source files

Directories

Path Synopsis
Package configtelemetry provides the telemetry reporting functions for configuration values.
 Package configtelemetry provides the telemetry reporting functions for configuration values.
Package provider resolves configuration values from multiple sources in priority order and reports telemetry for each value found.
 Package provider resolves configuration values from multiple sources in priority order and reports telemetry for each value found.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.