Agent

Active contributors: Derek Brown, Jaime Fullaondo, Olivier G, Massimiliano Pippi, Olivier Vielpeau

Purpose

The core Agent is the binary most users mean when they say "the Datadog Agent." It runs as a long-lived process on a host or in a container, runs Python and Go integration checks, hosts the in-process DogStatsD server (when colocated), exposes the Agent's IPC API, manages workload metadata and tags, and forwards everything the host produces — metrics, events, logs, service checks — to the Datadog intake.

The binary is built from cmd/agent/. Its main loop is composed via Fx in cmd/agent/subcommands/run/command.go, pulling in dozens of components from comp/.

Directory layout

cmd/agent/
├── main.go                # Linux/macOS entrypoint
├── main_windows.go        # Windows entrypoint
├── main_common.go         # Shared platform-agnostic entrypoint code
├── command/command.go     # Root cobra command builder
├── subcommands/           # All `agent <subcommand>` implementations
├── common/                # Shared helpers (signals, mis-config detection, …)
├── dist/                  # Default config files shipped with the binary
├── installer.go           # Hooks into the Datadog Installer
├── launcher/              # Embedded launcher used on macOS
├── macos/                 # macOS system extension scaffolding
├── windows/               # Windows service implementation
└── windows_resources/     # Windows resource files

The agent binary multiplexes more than one process. main.go inspects the executable name (and the DD_BUNDLED_AGENT env var) to pick a Cobra root command. By default it's the core Agent; it can also masquerade as the trace agent, security agent, system probe, or process agent when the same binary is hard-linked under a different name. This is the bundled agent mechanism.

Subcommands

cmd/agent/subcommands/ lists every supported subcommand. Highlights:

Subcommand	What it does
run	The main daemon. Wires the Fx graph, starts the HTTP API, runs forever.
start	Deprecated alias for run.
stop	Stops a running Agent service.
status	Renders a human-readable status snapshot.
health	Queries the health probe.
flare	Builds a support flare archive.
check <name>	Runs a single check once and prints its output.
configcheck	Lists effective check configurations from autodiscovery.
config	Reads, writes, or queries runtime configuration.
diagnose	Runs the diagnose suites (pkg/diagnose/).
secret	Inspects the configured secret backend.
secrethelper	Helper used inside containers to fetch secrets.
dogstatsd-stats, dogstatsd-capture, dogstatsd-replay	DogStatsD instrumentation.
streamlogs, analyzelogs	Log pipeline introspection.
streamep	Event Platform stream debug.
taggerlist	Dump the tagger's known entities.
workloadlist, workloadfilterlist	Dump workloadmeta state.
validatepodannotation	Validate AD-style Kubernetes annotations.
import	Imports a v5 config to v6/v7 layout.
integrations	Manage the bundled Python integrations.
jmx	JMX-Fetch helper subcommands.
controlsvc	Windows service-control wrapper.
coverage	Coverage reporter for tests.
createschema	Dump the configuration schema.
experimental	Holding pen for in-progress subcommands.
launchgui	Open the local GUI in a browser.
processchecks	Process check helpers.
remoteconfig	Inspect and manipulate Remote Config.
snmp	SNMP walker.
version	Print version info.

The list of subcommands is built in cmd/agent/subcommands/subcommands.go.

How run is wired

cmd/agent/subcommands/run/command.go is one of the largest files in cmd/. It imports dozens of *_fx packages from comp/, builds an fx.New(...) graph, and runs it under the cobra.Command's lifetime.

The graph includes:

• The core bundle (comp/core): config, logger, secrets, tagger, workloadmeta, autodiscovery, status, flare, healthprobe, gohai, IPC.
• The aggregator bundle (comp/aggregator): the demultiplexer.
• The collector bundle (comp/collector): scheduler, runner, Python loader.
• The forwarder bundle (comp/forwarder): HTTP forwarder with disk-backed retry queues.
• The serializer bundle (comp/serializer): payload serialization.
• The dogstatsd bundle (comp/dogstatsd): UDP/UDS/named-pipe listeners and the packet pipeline.
• The logs bundle (comp/logs): log collection, processing, batching, transport.
• The trace bundle (comp/trace): the in-process Trace Agent (when running embedded).
• The metadata bundle (comp/metadata): host metadata, inventory of agent/checks/integrations.
• The otelcol bundle (comp/otelcol): when the Agent acts as an OTLP receiver.
• And many more.

The same subcommands/run/ directory has internal helpers:

• clcrunnerapi/ — exposes the Cluster Checks Runner gRPC API on the embedded Cluster Checks Runner flavor.
• internal/settings/ — runtime-changeable settings registration.

Embedded checks

The Agent compiles in two flavors of checks:

• Core checks (pkg/collector/corechecks/) — written in Go and compiled into the binary. CPU, memory, network, file, container runtimes, eBPF-driven OS metrics, and many more.
• Python checks loaded from cmd/agent/dist/checks/ and from system-installed packages. Loaded through the rtloader-managed CPython 3 interpreter.

Autodiscovery dynamically configures checks based on the workloads the Agent observes. See Systems: Autodiscovery.

Key abstractions

Type / package	File	What it does
cmd/agent/main.go	cmd/agent/main.go	Multiplexes the binary based on its executable name
command.MakeCommand	cmd/agent/command/command.go	Builds the root cobra.Command
cmd/agent/subcommands/run/command.go	…	The Fx graph for the long-running daemon
comp/core/agent	comp/agent/	Core Agent component bundle
comp/aggregator/demultiplexer	comp/aggregator/demultiplexer/	Routes metric samples through the aggregator
comp/forwarder/defaultforwarder	comp/forwarder/defaultforwarder/	HTTP forwarder with retry/backoff and disk queue
comp/dogstatsd/server	comp/dogstatsd/server/	DogStatsD listener, packet parsing, metric extraction

Integration points

• DogStatsD is colocated with the core Agent by default. It consumes UDP/UDS/named-pipe traffic and sends MetricSamples into the aggregator. See DogStatsD.
• Trace Agent is colocated as a sub-process by default (via cmd/agent/trace_agent.go), forwarding APM data through the same forwarder. See Trace Agent.
• System Probe runs as a separate root process and exposes data over a Unix socket; the core Agent reads from it. See System Probe.
• Cluster Agent (when running in Kubernetes) dispatches cluster checks to standalone Cluster Checks Runner Agents. See Cluster Agent.
• Process Agent runs alongside and shares workloadmeta/tagger via gRPC.

Entry points for modification

• Adding a subcommand: copy a small one from cmd/agent/subcommands/ (e.g., version), wire it from subcommands.go, and follow the .claude/skills/create-subcommand/ skill.
• Wiring a new component into the long-running daemon: add the comp/<x>/<y>/fx import to cmd/agent/subcommands/run/command.go and include it in the fx.New(…) arguments. The .claude/skills/create-component/ skill walks through the full procedure.
• Touching main.go's flavor multiplexing: change carefully — every multi-process binary depends on it.

Related pages

• Architecture — how the Agent fits into the broader fleet.
• Systems: Components framework — Fx-based wiring.
• Systems: Aggregator pipeline — what happens to a metric after DogStatsD or a check emits it.
• Features: Metrics pipeline, Logs pipeline, APM tracing.