Datadog Agent

The datadog agent connects to the Datadog API using API key and Application key authentication. It queries time-series metrics, lists monitors, fetches events, and posts custom events (deploys, incidents, etc.). Source data is written as JSON to the workspace.

Use this agent to incorporate observability data into your pipelines — check system health before deploying, pull metrics for automated analysis, or post deploy markers back to Datadog for correlation.

---

Sample Phase

- name: check-metrics
  agent: datadog
  action: query_metrics
  sources:
      - name: cpu.json
        ref: "avg:system.cpu.user{service:api}"

---

Phase Configuration

The datadog agent uses phase:standard capability. Every phase declaration requires an action field.

Actions

Action	Direction	Description
query_metrics	Source	Query time-series metrics; ref is the metric query string
get_monitors	Source	List all monitors (no ref needed)
get_events	Source	Fetch events; optional window field sets the lookback period
post_event	Target	Post a custom event; file contains the JSON event payload

Phase YAML Fields

Field	Type	Required	Description
name	string	Yes	Unique phase name within the workflow
type	string	No	Defaults to "standard"
agent	string	Yes	Must be "datadog"
depends_on	string[]	No	Upstream phases that must complete before this phase runs
action	string	Yes	One of: query_metrics, get_monitors, get_events, post_event
sources	SourceEntry[]	For fetch actions	Entries to fetch from Datadog
target_entries	TargetEntry[]	For write actions	Entries to deliver to Datadog

Source Entry Fields

Field	Type	Required	Description
name	string	Yes	Output filename written to .cliq/files/{phase}/
ref	string	Required for query_metrics	Metric query string (e.g., avg:system.cpu.user{host:web-1})
window	string	No	Lookback window (e.g., 1h, 24h, 7d). Default: 1h for metrics, 24h for events

Target Entry Fields

Field	Type	Required	Description
name	string	Yes	Identifier for the operation
file	string	Yes	Workspace file containing JSON event payload

---

Settings

Key	Required	Default	Description
agents.datadog.api_key	Yes	—	Datadog API key
agents.datadog.app_key	Yes	—	Datadog Application key

The DATADOG_SITE environment variable controls the API base URL (defaults to datadoghq.com). Set to datadoghq.eu for EU sites, us3.datadoghq.com for US3, etc.

---

Output

Handoff Structure

Source operation — query_metrics:

{
    "data": {
        "action": "query_metrics",
        "sources": {
            "cpu-metrics.json": {
                "ref": "avg:system.cpu.user{host:web-1}",
                "query": "avg:system.cpu.user{host:web-1}",
                "metric_type": "timeseries",
                "data_points": 60
            }
        },
        "targets": {}
    },
    "text": "## Datadog Results\n\n✓ Fetched cpu-metrics.json — query_metrics (60 data points, 1h window)"
}

Source operation — get_monitors:

{
    "data": {
        "action": "get_monitors",
        "sources": {
            "monitors.json": {
                "ref": "",
                "count": 12
            }
        },
        "targets": {}
    },
    "text": "## Datadog Results\n\n✓ Fetched monitors.json — 12 monitors"
}

Target operation — post_event:

{
    "data": {
        "action": "post_event",
        "sources": {},
        "targets": {
            "deploy-event": {
                "ref": "deploy-event",
                "event_id": "5678901234",
                "status": "ok"
            }
        }
    },
    "text": "## Datadog Results\n\n✓ Posted deploy-event"
}

Field Reference

Field	Location	Description
ref	data.sources.*, data.targets.*	Metric query string or target name
query	data.sources.*	Full metric query (present on query_metrics)
metric_type	data.sources.*	Type of metric data (present on query_metrics)
data_points	data.sources.*	Number of data points returned (present on query_metrics)
count	data.sources.*	Number of items returned (present on get_monitors, get_events)
event_id	data.targets.*	ID of created event (present on post_event)
monitor_id	data.targets.*	Monitor ID if applicable
status	data.targets.*	Operation status

Files Written

Source responses are saved to .cliq/files/{phase}/{source.name} as JSON. Metric queries include the full time-series data with timestamps and values.

Downstream Access

Reference metric data in downstream phases:

commands:
    - name: alert
      run: 'echo "Data points: $(handoff.check-metrics.sources.cpu-metrics.json.data_points)"'

---

Examples

Example: Pre-deploy health check

Query CPU metrics and list monitors before deploying, ensuring the system is healthy.

phases:
    - name: check-health
      agent: datadog
      action: get_monitors
      sources:
          - name: monitors.json

    - name: check-cpu
      agent: datadog
      action: query_metrics
      sources:
          - name: cpu.json
            ref: "avg:system.cpu.user{env:production}"
            window: "1h"

    - name: deploy
      agent: exec
      depends_on: [check-health, check-cpu]
      commands:
          - name: deploy
            run: ./scripts/deploy.sh

Example: Post a deploy event marker

After a successful deploy, post an event to Datadog for correlation with metrics.

phases:
    - name: deploy
      agent: exec
      commands:
          - name: deploy
            run: ./scripts/deploy.sh

    - name: mark-deploy
      agent: datadog
      action: post_event
      depends_on: [deploy]
      target_entries:
          - name: deploy-event
            file: deploy-event.json

The deploy-event.json file should contain a Datadog event payload:

{
    "title": "Deployed v2.3.1 to production",
    "text": "Release v2.3.1 deployed by CI pipeline",
    "tags": ["env:production", "service:api"],
    "alert_type": "info"
}

Example: Fetch events for incident analysis

Pull recent events and feed them to an AI agent for incident analysis.

phases:
    - name: fetch-events
      agent: datadog
      action: get_events
      sources:
          - name: events.json
            window: "24h"

    - name: analyze
      agent: cursor
      role: sre-analyst
      depends_on: [fetch-events]

Example: Metric-driven alerting pipeline

Query error rate metrics, then analyze the trend with an AI agent.

phases:
    - name: check-errors
      agent: datadog
      action: query_metrics
      sources:
          - name: error-rate.json
            ref: "sum:http.requests.errors{service:api}/sum:http.requests.total{service:api}"
            window: "6h"

    - name: assess-risk
      agent: cursor
      role: sre-analyst
      depends_on: [check-errors]

---

Setup

1. In your Datadog organization, go to Organization Settings → API Keys and create an API key
2. Go to Organization Settings → Application Keys and create an Application key
3. Note your Datadog site if not using the default (datadoghq.com)

echo $DD_API_KEY | cliq settings agents.datadog.api_key --stdin --global
echo $DD_APP_KEY | cliq settings agents.datadog.app_key --stdin --global
cliq doctor agent datadog

If you use a non-default Datadog site, set the DATADOG_SITE environment variable:

export DATADOG_SITE=datadoghq.eu

---

See Also

• Agent Overview
• Agent SDK