config

package
v2.9.0-dev Latest Latest
Warning

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

 Go to latest Published: Mar 24, 2026 License: Apache-2.0, BSD-3-Clause, Apache-2.0 Imports: 17 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 reportTelemetry(...) with the correct origin.
  • 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

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

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
	// 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)

	// 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"
)

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.

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) AgentURL 

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) 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) 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) 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 

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 

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

func (*Config) SetCIVisibilityEnabled added in v2.6.0 

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

func (*Config) SetDataStreamsMonitoringEnabled added in v2.6.0 

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

func (*Config) SetDebug 

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

func (*Config) SetDebugAbandonedSpans added in v2.6.0 

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

func (*Config) SetDebugStack added in v2.6.0 

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

func (*Config) SetEnv added in v2.6.0 

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

func (*Config) SetFeatureFlags added in v2.6.0 

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

func (*Config) SetGlobalSampleRate added in v2.6.0 

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

func (*Config) SetHostname added in v2.6.0 

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

func (*Config) SetIsLambdaFunction added in v2.6.0 

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

func (*Config) SetLogDirectory added in v2.6.0 

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

func (*Config) SetLogStartup added in v2.6.0 

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

func (*Config) SetLogToStdout added in v2.6.0 

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

func (*Config) SetLogsOTelEnabled added in v2.7.0 

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

func (*Config) SetPartialFlushEnabled added in v2.6.0 

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

func (*Config) SetPartialFlushMinSpans added in v2.6.0 

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

func (*Config) SetProfilerEndpoints added in v2.6.0 

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

func (*Config) SetProfilerHotspotsEnabled added in v2.6.0 

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

func (*Config) SetRetryInterval added in v2.6.0 

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

func (*Config) SetRuntimeMetricsEnabled added in v2.6.0 

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

func (*Config) SetRuntimeMetricsV2Enabled added in v2.6.0 

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

func (*Config) SetServiceMapping added in v2.6.0 

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

func (*Config) SetServiceName added in v2.6.0 

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

func (*Config) SetSpanTimeout added in v2.6.0 

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

func (*Config) SetStatsComputationEnabled added in v2.6.0 

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

func (*Config) SetTraceProtocol 

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

func (*Config) SetTraceRateLimitPerSecond added in v2.6.0 

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

func (*Config) SetVersion added in v2.6.0 

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

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) TraceProtocol 

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 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.

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.