Configuration

The Datadog Agent is configured through several mechanisms that compose:

• Configuration files — datadog.yaml, system-probe.yaml, security-agent.yaml, plus per-check conf.d/<name>.d/conf.yaml.
• Environment variables — every config key is also reachable via a DD_* prefixed environment variable.
• Remote Config — runtime-pushed overrides for select features (samplers, CWS rules, AD templates, …).
• Command-line flags — for one-off invocations.

The schema is enormous. This page hits the highlights and points at canonical sources.

File locations

Default paths (Linux):

File	Path	Purpose
Main config	/etc/datadog-agent/datadog.yaml	Primary Agent config
System Probe	/etc/datadog-agent/system-probe.yaml	NPM/USM/CWS module config
Security Agent	/etc/datadog-agent/security-agent.yaml	CWS user-space config
Per-check configs	/etc/datadog-agent/conf.d/<check>.d/conf.yaml	Check instances and templates
CWS policies	/etc/datadog-agent/runtime-security.d/*.policy	SECL policies
Compliance	/etc/datadog-agent/compliance.d/*.yaml	CSPM benchmarks
Auth token	/etc/datadog-agent/auth_token	Inter-process IPC token

Windows and macOS use platform-appropriate paths (%ProgramData%\Datadog, /opt/datadog-agent/etc).

Environment variables

Every YAML key has an env var counterpart. Conventions:

• The key is uppercased.
• Dots become underscores.
• A DD_ prefix is added.

So apm_config.enabled: true becomes DD_APM_CONFIG_ENABLED=true. Nested map keys use double underscores in some places (DD_LOGS_CONFIG_PROCESSING_RULES).

Some env vars don't have a YAML equivalent (DD_BUNDLED_AGENT, which selects the Cobra root command in multi-process binaries).

The full conversion logic lives in pkg/config/setup/config.go and pkg/config/env/.

Top-level keys you'll meet often

Key	Purpose
api_key	Datadog API key
app_key	Datadog application key (cluster-agent only)
dd_url, dd_site	Backend URL / site (datadoghq.com, datadoghq.eu, …)
additional_endpoints	Fan-out to multiple Datadog accounts
mrf_dd_url	Multi-Region Failover URL
hostname	Override the auto-detected hostname
tags	Global tags applied to every metric/log/event
log_level	Global log level
log_file, log_file_max_size	Log file path and rotation
cmd_port	Agent IPC API port
agent_ipc.port	Internal IPC port
process_config.*	Process Agent settings
apm_config.*	Trace Agent settings
logs_enabled, logs_config.*	Logs pipeline settings
dogstatsd_*	DogStatsD listener and pipeline settings
network_config.*	NPM settings
service_monitoring_config.*	USM settings
runtime_security_config.*	CWS settings
compliance_config.*	CSPM settings
kubelet_*, kube_*	Kubernetes integration
forwarder_*	Forwarder behavior
aggregator_*, flush_interval	Aggregator behavior
histogram_aggregates, histogram_percentiles	Histogram aggregation
secret_backend_command	Path to the secret backend executable
remote_configuration.enabled	Master switch for Remote Config

Runtime-changeable settings

Some settings can be changed at runtime without restarting the Agent. They are registered through comp/core/settings/. View and modify them with:

agent config list-runtime
agent config set <name> <value>
agent config get <name>

Adding a new runtime-changeable setting follows the .claude/skills/create-runtime-setting/ skill.

Schema dump

The Agent can dump its full configuration schema, including descriptions, defaults, and types:

./bin/agent/agent createschema

The output is a JSON document — useful for tooling that wants a machine-readable description of the available knobs.

Per-check configuration

Each check has its own configuration directory: conf.d/<name>.d/conf.yaml. The format:

init_config:
  # check-wide settings

instances:
  - host: localhost
    port: 6379
  - host: other-host
    port: 6379

Templates for autodiscovery use init_config plus ad_identifiers and pin to the discovered service via template variables (%%host%%, %%port%%).

Multiple configurations and additional_endpoints

For customers shipping to multiple Datadog organizations, the Agent supports declaring extra endpoints:

additional_endpoints:
  https://app.datadoghq.com:
    - '<KEY1>'
  https://app.datadoghq.eu:
    - '<KEY2>'

Every payload is duplicated to each endpoint. The forwarder owns this fan-out logic; see Forwarder and serializer.

Tag configuration

Tags can come from many places (in priority order):

1. tags: in datadog.yaml.
2. extra_tags (computed at runtime from cloud metadata).
3. Environment variables (DD_TAGS, DD_EXTRA_TAGS).
4. Container/pod labels and annotations.
5. Tagger sources (kubelet, ECS, …).

The merged set is what gets attached to every metric/log/trace/event leaving the host.

Configuration file format

datadog.yaml is YAML; the loader uses Viper under the hood. Invalid keys produce warnings (not errors) by default. The agent configcheck and agent diagnose subcommands surface the more common misconfigurations.

Adding a new config key

The .claude/skills/create-config-field/ skill walks through the full procedure. Highlights:

• Add the default in pkg/config/setup/config.go.
• Update the example datadog.yaml in cmd/agent/dist/.
• Document it in docs/public/.
• If runtime-changeable, register through comp/core/settings/.
• If user-facing, add a release note via dda inv release.add-release-note.

Related pages

• How to contribute: Patterns and conventions — config code conventions.
• Systems: Remote Config — runtime overrides.
• Apps: Agent — agent config subcommand details.