Architecture

The Datadog Agent is a multi-process system that runs on the customer side of the data pipeline. Each process has a focused responsibility, but they share a common Go codebase, a common configuration, and a common forwarding path to the Datadog backend.

This page covers the moving parts at the highest level. Drill into Apps, Systems, and Features for the per-area detail.

Process topology

graph TB
    subgraph host[Customer host or pod]
        DSD[DogStatsD<br/>UDP/UDS/pipe]
        AGENT[Core Agent<br/>checks + collector]
        TRACE[Trace Agent<br/>APM]
        SYSP[System Probe<br/>eBPF, privileged]
        SEC[Security Agent<br/>CWS + CSPM]
        PROC[Process Agent<br/>process + container]
    end

    APP[Instrumented app]
    OTEL[OTel SDK]
    K8S[Kubernetes API]

    APP -->|metrics| DSD
    APP -->|traces v0.4/v0.5| TRACE
    OTEL -->|OTLP| TRACE
    DSD -->|metric samples| AGENT
    AGENT <-->|gRPC tagger / workloadmeta| PROC
    AGENT <-->|gRPC tagger / metrics| TRACE
    AGENT <-->|sysprobe HTTP socket| SYSP
    SEC <-->|sysprobe HTTP socket| SYSP
    K8S -.->|cluster checks| AGENT

    AGENT -->|metrics, logs, events| INTAKE[Datadog intake]
    TRACE -->|traces, stats| INTAKE
    SEC -->|CWS events, compliance| INTAKE
    PROC -->|process, container| INTAKE

The core Agent is the first process most users think of, but every process produces its own payload type and forwards it directly. The cross-process arrows are mostly metadata: the core Agent runs the canonical tagger and workloadmeta stores; other processes connect to it over a gRPC socket to get the same view of containers, pods, and tags.

For the data flow inside the core Agent itself, see the metrics pipeline. For the trace agent's internal pipeline, see the APM tracing feature.

Code layout

The repository is organized around three top-level Go directories that mirror the architecture:

Directory	What lives here
cmd/	One subdirectory per binary. Each contains a main.go, a command/ package that wires Cobra subcommands, and subcommands/ for individual subcommands. The actual logic lives elsewhere — cmd/ is mostly composition.
pkg/	The legacy home for shared Go libraries. Most of the data-collection and processing logic still lives here: pkg/aggregator, pkg/collector, pkg/logs, pkg/trace, pkg/network, pkg/security, etc.
comp/	The newer component framework built on go.uber.org/fx. Each component exposes an interface and has one or more implementations wired through Fx. New code should be written as components; old code is being migrated incrementally. See Components framework.

A few other top-level directories matter:

Directory	Purpose
tasks/	Python Invoke tasks — the canonical entry point for all build, test, lint, and release operations. Run via the dda inv … wrapper.
bazel/ and BUILD.bazel files	The newer Bazel build system. eBPF compilation, code generation, and many packages now build via Bazel. The old Omnibus build system is being phased out.
omnibus/	The legacy Omnibus build system used to produce deb/rpm/MSI packages. Still in use for distribution, but new logic goes into packages/.
packages/	Bazel-managed packaging definitions for the Agent and friends.
rtloader/	C/C++ runtime loader that hosts CPython 2/3 inside the Agent so Python checks can run. Built with CMake.
rust/	Cargo workspace — small Rust crates used by some components.
test/new-e2e/, test/e2e-framework/, test/fakeintake/	The end-to-end test framework that provisions cloud infrastructure and a mock Datadog intake.
tools/	Helper binaries used during development, code generation, or CI.
docs/	The developer documentation site (Material for MkDocs).

For a stat-driven view of the layout (LOC by language, churn hotspots, etc.) see By the numbers.

Component framework in 30 seconds

graph LR
    BUNDLE[Component bundle<br/>e.g. comp/core] -->|Fx options| APP[Binary app<br/>fx.New]
    BUNDLE2[Component bundle<br/>e.g. comp/logs] --> APP
    BUNDLE3[Component bundle<br/>e.g. comp/trace] --> APP
    APP -->|injects deps| RUN[run command]
    APP -->|build tags filter| BUILDS[different binaries]

Each binary is assembled by composing Fx bundles of components. A bundle is a Go package under comp/<name> that provides an fx.Option and a list of components it owns. Different binaries (Agent, IoT Agent, Cluster Agent, Trace Agent…) include a different mix of bundles, which is how the same component code can produce ten different processes.

The fx-based wiring lives in cmd/<binary>/subcommands/run/. For example, cmd/agent/subcommands/run/command.go lists every bundle the core Agent uses.

Data plane: from sample to intake

For metrics, the path is roughly:

graph LR
    subgraph in[Inputs]
        DSDIN[DogStatsD]
        CHKIN[Python/Go check]
    end
    DSDIN -->|MetricSample| AGG[Aggregator<br/>pkg/aggregator]
    CHKIN -->|Sender API| AGG
    AGG -->|TimeSampler<br/>CheckSampler| CTX[Context Metrics]
    CTX -->|Series + Sketches| SER[Serializer<br/>pkg/serializer]
    SER -->|HTTP POST| FWD[Forwarder<br/>comp/forwarder]
    FWD -->|retry queue| INTAKE[Datadog intake]

The same shape applies to logs, traces, events, and CWS payloads, each with its own pipeline. See Aggregator pipeline, Forwarder and serializer, and the per-feature pages for details.

Multi-platform support

The Agent runs on Linux, Windows, macOS, and inside containers. Significant amounts of code are platform-specific:

• *_linux.go, *_windows.go, *_darwin.go build constraints split per-OS implementations.
• Build tags like linux_bpf, kubeapiserver, containerd, python enable or disable whole subsystems.
• Windows-specific packaging lives under packages/, omnibus/, and cmd/*/windows_resources/.
• macOS has a system-extension scaffold under cmd/agent/macos/.

Platform-specific divergence is a frequent source of bugs, called out explicitly in AGENTS.md. When reading code, pay attention to the build constraints at the top of each file.

Build and packaging

Two coexisting build systems:

• Bazel (newer, growing). bazel/ defines toolchains, repositories, and macros (notably the eBPF rules in bazel/rules/ebpf/). BUILD.bazel files live next to Go packages. Migration is in progress; recent commits like "migrate another batch of packages to bazel" are common.
• Omnibus + Invoke (legacy). dda inv agent.build and friends drive Go builds with the right tag combinations; omnibus/ produces deb/rpm/MSI packages.

The Python Invoke tasks under tasks/ are the human-facing entry point for both. See Tooling.

What this page does not cover

• Per-app responsibilities and command lines: see Apps.
• Cross-cutting features (metrics, logs, traces, network, security): see Features.
• The shared internal subsystems (collector runtime, aggregator, autodiscovery, remote-config, components framework): see Systems.
• API surfaces (Agent IPC, gRPC, expvar, status, flare): see API.
• Configuration and build tags: see Reference.