Process Agent

Active contributors: Corrina Sivak, Ivan Ilichev, Moisés Botarro

Purpose

The Process Agent is a separate binary that collects process-level and container-level data from the host. It runs as its own process so that the heavier process scanning workload doesn't compete with the core Agent's metric pipelines.

It powers:

• Live Processes — periodic snapshots of all running processes (with command lines, resource usage, parents, container association).
• Live Containers — equivalent for containers.
• Process discovery for autodiscovery and language detection.
• Connections check — pulling network flow data from the System Probe and reporting it as connection metrics.

Directory layout

cmd/process-agent/
├── main.go
├── command/
├── subcommands/        # `run`, `status`, `version`, `events`, `tagger`, etc.
├── api/                # HTTP API
├── flags/              # Shared flag plumbing
└── windows_resources/

pkg/process/            # The actual collection logic
├── checks/             # Process / container / connections checks
├── config/
├── encoding/
├── monitor/            # Process monitoring helpers
├── runner/             # Check scheduling
├── statsd/, status/, util/
└── ...

Subcommands

Subcommand	Purpose
run (default)	Long-running daemon.
status	Status snapshot.
flare	Build a flare archive.
tagger	Inspect tagger state (Process Agent has its own tagger client).
events	Container event stream introspection.
version	Print version.

The full list lives in cmd/process-agent/subcommands/.

How it relates to other binaries

The Process Agent shares workloadmeta and tagger state with the core Agent over gRPC: pkg/clusteragent/api/ and comp/api/grpcserver/ provide the server side; the process agent runs the client. This avoids three independent processes (core, process, security) re-implementing container/pod resolution.

It also reads from the System Probe over its UDS socket to populate the connections check (which is what shipps NPM data to the cloud, in non-cluster deployments).

Configuration

Process Agent settings live under process_config: in datadog.yaml. Key options:

Setting	Effect
process_config.process_collection.enabled	Enable Live Processes
process_config.container_collection.enabled	Enable Live Containers
process_config.process_discovery.enabled	Enable process discovery (lightweight)
process_config.scrub_args	Mask sensitive command-line args
process_config.custom_sensitive_words	Additional sensitive words for scrubbing
process_config.strip_proc_arguments	Drop args entirely

Pipeline

graph LR
    PROC[/proc, ps] --> COLL[Collector<br/>pkg/process/checks/process.go]
    CGROUPS[cgroups, container runtimes] --> COLL
    SYSPROBE[System Probe<br/>UDS] --> CONN[Connections check<br/>pkg/process/checks/connections.go]
    COLL --> RUNNER[Runner<br/>pkg/process/runner]
    CONN --> RUNNER
    RUNNER --> ENC[Encoder<br/>pkg/process/encoding]
    ENC --> SENDER[Forwarder]
    SENDER --> INTAKE[Datadog intake]

The runner schedules each check on its own cadence. Process and container snapshots are big payloads and are encoded with custom MessagePack/protobuf to keep them compact.

Key abstractions

Type / package	Location	Purpose
Check	pkg/process/checks/check.go	Check abstraction
ProcessCheck	pkg/process/checks/process.go	Live Processes
ContainerCheck	pkg/process/checks/container.go	Live Containers
ConnectionsCheck	pkg/process/checks/connections.go	Network flows from system probe
Runner	pkg/process/runner/	Check scheduler
Encoder	pkg/process/encoding/	Wire-format encoder

Sensitive data scrubbing

Command-line arguments can contain secrets. pkg/process/util/scrubber/ (and its pkg/util/scrubber/ ancestor) implements a regex-based scrubber that replaces the values of password, token, key, etc. Patterns are configurable.

Entry points for modification

• Adding a new check: implement pkg/process/checks/check.go and register it in the runner.
• Adding new metadata to existing checks: extend the encoder, the protobuf, and the corresponding intake-side schema.
• Tweaking scrubbing: update the patterns in pkg/process/util/scrubber/ and write tests.

Related pages

• Apps: Agent — shares workloadmeta/tagger over gRPC.
• Apps: System Probe — origin of connections data.
• Features: Network monitoring — how connection data flows end-to-end.