> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Datadog

> A stateful replica of Datadog's API v1 and v2: metric queries, log search, monitors and mutes, downtimes, dashboards, events and incidents.

The Datadog replica implements 26 endpoints across metrics, logs, monitors, downtimes, dashboards, events and incidents. Its key is `datadog`. It was tested with `@datadog/datadog-api-client`.

## Connect

| Variable | Value |
| - | - |
| `DATADOG_API_URL` | Base URL of the API. |
| `DD_API_KEY` | Fake API key, sent as `DD-API-KEY`. |
| `DD_APP_KEY` | Fake application key, sent as `DD-APPLICATION-KEY`. |
| `DATADOG_WEBHOOK_TOKEN` | Bearer token on webhook deliveries to your agent. |

```js Node theme={null}
import { client, v1 } from '@datadog/datadog-api-client';
const configuration = client.createConfiguration({
  baseServer: new client.BaseServerConfiguration(process.env.DATADOG_API_URL!, {}),
  enableRetry: false,
});
// The SDK reads DD_API_KEY and DD_APP_KEY. v2 incident operations require explicit unstableOperations flags.
const dashboards = new v1.DashboardsApi(configuration);
await dashboards.listDashboards();
```

This is what `ancha connect datadog --lang ts` prints. Turn SDK retries off so a failing call does not hide behind retries. `ancha connect` has no Python snippet for Datadog.

## Endpoints

Any other route returns HTTP 501 with `{"errors": ["ancha: not implemented: ..."]}` and `x-ancha-gap: 1`. `ancha twins coverage datadog` prints each endpoint's full notes.

### Metrics and logs

| Method | Path | Support |
| - | - | - |
| `GET` | `/api/v1/query` | partial |
| `POST` | `/api/v2/logs/events/search` | partial |

Metric queries support `avg`, `sum`, `min` and `max`, literal tag filters joined with AND, and grouping. Functions, arithmetic and boolean filters are coverage gaps. Both metrics and logs answer windows of at most 24 hours. Log search matches literal service, status and tag filters and quoted message substrings.

### Monitors

| Method | Path | Support |
| - | - | - |
| `POST` | `/api/v1/monitor/:id/mute` | partial |
| `POST` | `/api/v1/monitor/:id/unmute` | partial |
| `GET` | `/api/v1/monitor` | partial |
| `GET` | `/api/v1/monitor/:id` | partial |

Monitor states are `OK` and `Alert`. Mutes are global: they suppress notifications, not evaluation. In a living world, monitors evaluate generated metrics every 15 seconds of simulated time.

### Downtimes

| Method | Path | Support |
| - | - | - |
| `POST` | `/api/v1/downtime` | partial |
| `GET` | `/api/v1/downtime` | partial |
| `GET` | `/api/v1/downtime/:id` | partial |
| `PUT` | `/api/v1/downtime/:id` | partial |
| `DELETE` | `/api/v1/downtime/:id` | partial |
| `POST` | `/api/v2/downtime` | partial |
| `GET` | `/api/v2/downtime` | partial |
| `GET` | `/api/v2/downtime/:id` | partial |
| `PATCH` | `/api/v2/downtime/:id` | partial |
| `DELETE` | `/api/v2/downtime/:id` | partial |
| `GET` | `/api/v1/monitor/:monitor_id/downtimes` | partial |
| `GET` | `/api/v2/monitor/:monitor_id/downtime_matches` | partial |

Downtimes are one-time windows for one monitor or all monitors. Recurrence and scoped or tag-targeted downtimes are coverage gaps. v1 and v2 downtimes use their own ID formats, which are not interchangeable.

### Dashboards

| Method | Path | Support |
| - | - | - |
| `GET` | `/api/v1/dashboard` | partial |
| `GET` | `/api/v1/dashboard/:id` | supported |

Dashboards are read-only. Their widgets are stored, never executed.

### Events

| Method | Path | Support |
| - | - | - |
| `GET` | `/api/v1/events` | partial |
| `POST` | `/api/v1/events` | partial |

### Incidents

| Method | Path | Support |
| - | - | - |
| `GET` | `/api/v2/incidents` | partial |
| `POST` | `/api/v2/incidents` | partial |
| `GET` | `/api/v2/incidents/:id` | partial |
| `PATCH` | `/api/v2/incidents/:id` | partial |

Incidents are JSON:API resources with `state` (`active`, `stable`, `resolved`) and `severity` (`SEV-1` to `SEV-5` or `UNKNOWN`). They do not affect faults or PagerDuty.

## Starter data

The `datadog-starter` dataset describes Acme's production services two hours after an Orders API deploy was rolled back, with a warehouse sync that is falling behind.

| Ref | Record |
| - | - |
| `$datadog_orders` | Monitor "Orders request failures": `avg(last_5m):avg:orders.errors{service:orders} > 1`, state `OK`. Its message notifies `@pagerduty-orders`. |
| `$datadog_checkout` | Monitor "Checkout p95 latency", `OK`. |
| `$datadog_payments` | Monitor "Payment webhook failures", `OK`. |
| `$datadog_sync_lag` | Monitor "Warehouse sync lag": `avg(last_15m):avg:warehouse.sync.lag_seconds{service:warehouse-sync} > 900`, state `Alert`. |
| `$datadog_web_5xx` | Monitor "Web 5xx responses", `OK`. |
| `$datadog_db_disk` | Monitor "db-primary disk usage", `OK`. |
| `$datadog_queue` | Monitor "Fulfillment queue depth", `OK`. |
| `$datadog_dashboard` | Dashboard "Orders API health". |
| `$datadog_checkout_board`, `$datadog_sync_board` | Dashboards "Checkout" and "Warehouse sync". |
| `$datadog_recovery` | Event "Orders recovery verified", 10 minutes before start. |

Four more events tell the deploy story: orders 4.12.1 deployed 3 hours 10 minutes before start, rolled back to 4.12.0 twenty minutes later, web 2026.10.29 deployed 47 minutes before start, and a Snowflake maintenance window 42 minutes before start.

Eight metric series carry the last hour: `orders.errors` and `orders.latency` (a spike 15 minutes before start, 12 errors and 780 ms, then normal), `checkout.latency.p95`, `payments.webhook.errors`, `warehouse.sync.lag_seconds` (climbing from 420 to 1,230 seconds), `web.requests.5xx`, `system.disk.used_pct` for `db-primary` (around 72%) and `fulfillment.queue.depth`. Seventeen log lines from the services `orders`, `warehouse-sync`, `checkout`, `payments`, `web` and `fulfillment` match them, for example the Snowflake 503 retries and "Sync for ridgeway-robotics is 17 minutes behind". All are tagged `env:production`.

## Checks

| Check | Example |
| - | - |
| `datadog.monitor` | `{ datadog.monitor: $datadog_orders, is: OK }` |
| `datadog.downtime` | `{ datadog.downtime: { monitor: $datadog_orders, remaining_gte: 1m, duration_lte: 10m } }` |

`datadog.downtime` passes when an active, uncanceled downtime targets that exact monitor, has at least `remaining_gte` left and lasts no longer than `duration_lte` in total. Add `reject_active_unsafe: true` to also fail when any active all-monitor or overlong downtime exists. See [Checks reference](https://docs.ancha.io/reference/checks.md#datadog).

## Limits

* A bounded metric query grammar and log search syntax.
* One-time global downtimes only; no recurrence or scopes.
* No SLOs, notebooks, synthetics or APM.


## Related topics

- [Checks reference](https://docs.ancha.io/reference/checks.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [ancha init](https://docs.ancha.io/cli/init.md)
- [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md)
- [ancha scene](https://docs.ancha.io/cli/scene.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.