Create Core Check

Create a new Go-based core check for the Datadog Agent. Core checks collect metrics, service checks, or events and send them to Datadog at regular intervals.

Instructions

Step 1: Gather information from the user

Use AskUserQuestion to collect the following. If $ARGUMENTS provides the check name, skip that question.

1. Check name: The identifier for the check (e.g. uptime, memory, ntp). Used as the package name, registration key, and config directory name.

2. Check category: Where should the check live under pkg/collector/corechecks/?

   • system/ — System-level checks (CPU, memory, uptime, disk)
   • net/ — Network checks (NTP, DNS)
   • containers/ — Container-related checks
   • ebpf/ — eBPF-based checks (these are more complex, see pkg/collector/corechecks/ebpf/AGENTS.md)
   • embed/ — Embedded service checks
   • Top-level under corechecks/ — For standalone checks

3. What does it collect?: Describe the metrics, service checks, or events it produces.

4. Configuration: Does it need instance-level configuration?

   • No config — Single instance, no user parameters (like uptime)
   • Simple config — A few YAML parameters (like memory with collect_memory_pressure)
   • Multi-instance — Supports multiple configured instances (like ntp with different servers)

5. Component dependencies: Does the check need injected components?

   • None — Simple check, no external dependencies
   • Tagger — Needs to tag metrics with container/host tags
   • WorkloadMeta — Needs access to workload metadata store
   • Other — Specify which components

6. Long-running?: Does the check run continuously in the background?

   • No (default) — Run() is called at regular intervals (default 15s)
   • Yes — Run() never returns, processes events in a loop

7. Platform restrictions: Does the check only work on certain platforms?

   • All platforms (default)
   • Linux only
   • Windows only
   • Linux + macOS (not Windows)

Step 2: Read reference examples from the codebase

Before writing any code, read the appropriate reference files based on the check type determined in Step 1. Follow the patterns found in these files exactly.

Also read these files for registration and test patterns:

• pkg/commonchecks/corechecks.go — to see how checks are registered (import alias convention, RegisterCheck calls)
• The _test.go file alongside whichever reference check you read — to see mock sender patterns

Step 3: Create the check package

Directory: pkg/collector/corechecks/<category>/<checkname>/

Create the check implementation file following the patterns from the reference files read in Step 2. Key structural elements that every check needs:

1. CheckName constant — string identifier for the check
2. Check struct — embeds core.CheckBase, plus any config or component fields
3. Factory() function — returns option.Option[func() check.Check]. Components are injected as Factory parameters.
4. Configure() method — calls CommonConfigure, then FinalizeCheckServiceTag, then parses instance config if needed
5. Run() method — collects data, calls sender methods, ends with sender.Commit()

Key rules to follow:

• For multi-instance checks: call c.BuildID(integrationConfigDigest, rawInstance, rawInitConfig) before CommonConfigure()
• For long-running checks: wrap with core.NewLongRunningCheckWrapper() in Factory, return 0 from Interval(), implement Stop()
• For platform-specific checks: add //go:build <platform> tag and create a stub file for other platforms that returns option.None[func() check.Check]()

Step 4: Register the check

Edit pkg/commonchecks/corechecks.go:

1. Add an import for the check package using the standard alias convention visible in the file (typically the check name)
2. Add a corecheckLoader.RegisterCheck() call in RegisterChecks(), matching the Factory signature to available component parameters