Add a new configuration field to the Datadog Agent (datadog.yaml)
Add a new configuration field to a Datadog Agent. This involves registering the key with defaults/env bindings in Go, and optionally documenting it in the config template.
There are two separate config objects, each with their own Go init function. Within the core agent config, many subsystems have dedicated setup functions and template sections.
| Config object | Config file | Go init function |
|---|---|---|
| Core Agent | datadog.yaml | InitConfig() in pkg/config/setup/config.go |
| System Probe | system-probe.yaml | InitSystemProbeConfig() in pkg/config/setup/system_probe.go |
| Subsystem | Go setup function | Template conditional | Key prefix examples |
|---|---|---|---|
| Common / General |
agent() or inline in InitConfig() |
.Common, .Agent |
api_key, hostname, site |
| Logs Agent | logsagent() | .LogsAgent | logs_config.* |
| APM / Trace Agent | setupAPM() in apm.go | .TraceAgent | apm_config.* |
| Process Agent | setupProcesses() in process.go | .ProcessAgent | process_config.* |
| DogStatsD | dogstatsd() | .Dogstatsd | dogstatsd_* |
| Security Agent | via InitConfig() | .SecurityAgent | security_agent.* |
| Cluster Agent | via InitConfig() | .ClusterAgent | cluster_agent.* |
| OTLP | OTLP() in otlp.go | .OTLP | otlp_config.* |
| Subsystem | Go setup function | Template conditional | Key prefix examples |
|---|---|---|---|
| General | InitSystemProbeConfig() | .SystemProbe | system_probe_config.* |
| CWS | initCWSSystemProbeConfig() in system_probe_cws.go | .SecurityModule | runtime_security_config.* |
| USM | initUSMSystemProbeConfig() in system_probe_usm.go | .UniversalServiceMonitoringModule | service_monitoring_config.* |
| Network | via InitSystemProbeConfig() | .NetworkModule | network_config.* |
Use AskUserQuestion to collect the following. If $ARGUMENTS provides the config key name, skip that question.
datadog.yaml) or System Probe (system-probe.yaml)?my_feature.enabled): the YAML path.pkg/config/setup/<feature>.go) for a group of related fields?pkg/config/config_template.yaml?Find the right subsystem function from the tables above and add the binding. Use Grep if unsure where related keys live.
config.BindEnvAndSetDefault("my_feature.enabled", false)
For a group of related fields, create pkg/config/setup/<feature>.go with a dedicated setup function, then call it from the appropriate init function. Read an existing setup file (e.g. pkg/config/setup/apm.go) for the pattern.
For serverless-compatible core agent fields, register via the serverlessConfigComponents slice in config.go instead of directly in InitConfig.
If user-facing, add documentation to pkg/config/config_template.yaml inside the appropriate conditional block (see Template conditional column in tables above). Read existing entries nearby for the exact format (@param, @env annotations).
dda inv agent.build --build-exclude=systemd (or dda inv system-probe.build)dda inv linter.godda inv generate-configBindEnvAndSetDefault(key, default, envVars...) — Preferred. Registers key, sets default, binds DD_* env var.SetDefault(key, value) — Default without env binding.BindEnv(key, envVars...) — Env binding without default.BindEnvAndSetDefault("my_feature.timeout", 30) auto-creates DD_MY_FEATURE_TIMEOUT. Custom alias: BindEnvAndSetDefault("my_feature.timeout", 30, "DD_MY_TIMEOUT").
SetKnown for new fields — it's deprecated. Use BindEnvAndSetDefault.default < file < env-var < fleet-policies < agent-runtime < remote-config < cli./create-config-field — Interactive: prompts for all details/create-config-field my_feature.enabled — Pre-fills the key name