Packages

The Datadog Agent uses two coexisting forms of "package":

• Go packages — the source-level units of code organization in pkg/ and comp/. There are over a thousand of these.
• Distribution packages — the deb / rpm / MSI / Docker artifacts shipped to customers, defined in packages/ (Bazel-driven, the new home) and omnibus/ (Ruby-driven, legacy).

Both meanings appear in this section.

Subsections

• Components overview (comp/) — the Fx-based component bundles. New code lives here.
• Legacy packages (pkg/) — the older Go-package home. Most data-plane code still lives here.

Distribution packaging

Distribution packaging — the artifacts you actually apt install or docker pull — is documented in Deployment and the underlying logic lives in:

• packages/ — Bazel-driven, the new home. One subdirectory per artifact.
• omnibus/ — Ruby-driven legacy. Still in use for some packaging, gradually being retired.
• Dockerfiles/ — Docker image definitions for the Agent, DogStatsD, and Cluster Agent.
• chocolatey/ — Windows Chocolatey package.

comp/ vs pkg/

A short cheat sheet:

Question	comp/	pkg/
Where new code goes?	Yes	Only when migrating from pkg/
Has Fx wiring?	Yes	No, uses globals
Has interface separation (def/impl)?	Yes	Sometimes
Mockable in tests?	Yes (mock subpackage)	Usually requires test helpers
Lifecycle hooks?	OnStart / OnStop	Ad hoc

The migration is incremental. Most of the heavy data-plane code (aggregator, trace agent, network tracer, security probe) still lives in pkg/, and it might be a long time before any of those move. Lighter, glue-style code is the easiest to migrate and the focus of most ongoing work.

A few packages worth singling out

• pkg/util/ — the Agent's grab-bag utility module. Contains the log interface, scrubber, containers, kubernetes, cloudproviders, and dozens of others. New utilities go here when they don't have a natural home.
• pkg/config/ — the canonical configuration source. Contains the schema, defaults, and parsing for datadog.yaml. The comp/core/config/ component wraps this.
• pkg/api/ — the Agent's HTTP IPC API layer (legacy). Now mostly delegated to comp/api/.
• pkg/serializer/ — payload serialization for metrics, sketches, events, service checks, host metadata.
• pkg/util/fxutil/ — Datadog's Fx helpers used by every component test.
• pkg/proto/ — protobuf type definitions shared between binaries.

Go modules

The repo is a multi-module Go workspace. The root go.mod is one of the largest in the open-source ecosystem; there are also nested modules:

• pkg/metrics/go.mod
• pkg/trace/go.mod
• pkg/network/go.mod
• pkg/security/secl/go.mod
• (and many more)

Nested modules are extracted so they can be consumed externally (the trace agent's protos, the SECL parser, etc.). Coordination is via the root go.work file.

modules.yml lists the canonical set of Go modules in the repository. dda inv tidy keeps everything consistent.

Related pages

• Systems: Components framework — how comp/ is wired.
• Reference: Dependencies — third-party Go and other dependencies.