Datadog Collector

Collect dashboard, monitor, SLO, and On-Call data from Datadog via the API, and discover Datadog-as-code JSON files committed in the component repository.

Overview

This plugin provides three sub-collectors. The service sub-collector queries the Datadog REST API for monitors, dashboard, and SLOs tagged with the component's service. The repo-files sub-collector walks the repo for Datadog-as-code JSON files (dashboards and monitor definitions) and captures their raw contents. The oncall sub-collector reads the Datadog On-Call schedule and escalation policy of the component's team. Data lands under the tool-agnostic .observability and .oncall categories, so the shared observability and oncall policies work whether the data came from Datadog or another provider.

Collected Data

This collector writes to the following Component JSON paths:

Collectors

This plugin provides the following sub-collectors:

Installation

Add to your lunar-config.yml:

collectors:
  - uses: github://earthly/lunar-lib/collectors/datadog@v1.0.0
    on: ["domain:your-domain"]
    with:
      datadog_site: "datadoghq.com"
      # service_name: "payment-api"   # Optional fallback if catalog meta isn't set
      # dashboard_id: "abc-123-def"   # Optional dashboard UUID
      # team: "payments"              # Optional On-Call team fallback if catalog meta isn't set
      # find_command: "find ./datadog -type f -name '*.json'"  # Optional, narrows repo scan

Required secrets:

• DATADOG_API_KEY — Datadog API key (Organization Settings → API Keys)
• DATADOG_APP_KEY — Datadog application key (Organization Settings → Application Keys). Required for monitor, dashboard, SLO, and On-Call reads — these endpoints require both the API key and the application key.

Application key scopes. Modern Datadog application keys are scoped — if you pick "Custom Scopes" at creation time, select at minimum the scopes listed below, otherwise the API returns 403 for the matching endpoints. If you pick "All Scopes" at creation time no further action is needed, but least-privilege is preferred:

The repo-files sub-collector does not call the Datadog API and is unaffected by application-key scoping.

Service discovery

The service sub-collector resolves the component's Datadog service tag in this order:

1. Catalog meta annotation — reads datadog/service-name from the component's lunar catalog meta. Set via lunar catalog component --meta datadog/service-name <name>, typically by a company-specific cataloger that knows which components map to which Datadog services. This is the recommended approach.
2. service_name input — explicit value passed via with: service_name: <name> in lunar-config.yml. Useful for static cases or for orgs that don't run a cataloger.
3. If neither is set, the sub-collector exits cleanly with no data written.

Monitors and SLOs are listed via the Datadog API and filtered on service:<name> tag. .observability.alerts.count and .observability.slo.count reflect the number of matching resources.

Dashboard discovery

Datadog dashboards are not universally tagged with service:, so the dashboard must be mapped explicitly:

1. Catalog meta annotation — datadog/dashboard-id set via lunar catalog component --meta datadog/dashboard-id <uuid>.
2. dashboard_id input — explicit value passed via with: dashboard_id: <uuid>.
3. If neither is set, dashboard data is not collected (monitors and SLOs still run).

When the UUID resolves but the dashboard does not exist in Datadog, .observability.dashboard.exists=false is written so policies can flag the stale link. The UID is always written to .observability.dashboard.id so the link is visible in the component JSON even when the dashboard is missing.

On-Call team mapping

Datadog On-Call is team-based, so the oncall sub-collector needs the component's Datadog team. It resolves it in this order:

1. Catalog meta annotation — datadog/team, set via lunar catalog component --meta datadog/team <team>, typically by a cataloger that knows which team owns each component. This is the recommended approach.
2. team input — with: team: <team> in lunar-config.yml, for static cases.
3. If neither is set, the sub-collector exits cleanly without calling the API.

Either takes a team handle (e.g. payments, looked up through the Teams API) or a team ID. From the team it follows the path a page takes: the escalation policy the team's fallback routing rule pages (the rule with no query and no time restriction, which Datadog requires last), that policy's steps (levels), and the first schedule a step targets. If the fallback pages no policy, the first rule before it that does is used. participants counts the distinct users in that schedule's layers that have not ended, leaving out users Datadog reports as deactivated; rotation comes from the first such layer's interval.

A team with no routing rules, or none that pages an escalation policy, is recorded as exists: false. Any other API error (401/403, a rate limit that outlasts the retries, 5xx) fails the run and writes nothing, so a missing scope or an outage never reads as "no on-call".

Datadog site support

The datadog_site input selects which Datadog region to call. Defaults to datadoghq.com (US1). Supported values include datadoghq.eu (EU1), us3.datadoghq.com (US3), us5.datadoghq.com (US5), and ap1.datadoghq.com (AP1). The collector builds API URLs as https://api.<site> and dashboard links as https://app.<site>/dashboard/<id>.

If you are running outside of lunar collect and want to override the site without rewriting lunar-config.yml, set the DATADOG_SITE environment variable. Resolution order is datadog_site input → DATADOG_SITE env var → datadoghq.com default. Wrong-region requests return 401 Unauthorized, which is the most common cause of 4xx errors when keys are otherwise valid.

Repo file discovery (the repo-files sub-collector)

The repo-files sub-collector walks the cloned component repo and identifies Datadog-as-code JSON files by content fingerprint:

• Dashboards — any .json file whose top-level object contains both a widgets array and a layout_type field (string, typically ordered or free). This is the shape produced by Datadog's UI JSON export and by the datadog_dashboard_json Terraform resource.
• Monitors — any .json file whose top-level object contains type (string, e.g. metric alert, query alert, service check, log alert), query (string), and name (string). This is the shape of Datadog's Monitor API payload and what the datadog-ci and Datadog Terraform provider produce.

By default the full repo is walked. Set the find_command input to narrow the search to a specific directory (for example find ./datadog -type f -name '*.json'). This mirrors the pattern used by the Grafana collector's repo-dashboards sub-collector. Files that do not match either fingerprint are silently skipped. If no dashboards or monitors are found, nothing is written.

This sub-collector does not write to normalized .observability.dashboard / .observability.alerts paths — the API sub-collector owns those. .observability.native.datadog.repo_* is intentionally raw — users write their own policies against the dashboard/monitor JSON if they care about widget types, query shapes, notification targets, etc.

Notes on behavior

• Both sub-collectors run on the code hook, so they fire on each push rather than a schedule. This matches the Grafana collector's pattern — the clone is cheap and keeps the data fresh on every change. The service sub-collector does not actually read from the repo, but the clone is cheap and keeps the hook model consistent across the plugin.
• When Datadog API credentials are missing or the service name is not resolved, the service sub-collector exits 0 with a stderr message — no error, no partial data. The repo-files sub-collector works independently of API credentials.
• Example Component JSON is defined in lunar-collector.yml under example_component_json.