# @kody/datadog — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by
**name** only — never paste key values. Do not enable the `monitor-status` job
or mute/delete monitors without an explicit ask.

## Auth

| Secret | Header | Notes |
| --- | --- | --- |
| `datadogApiKey` | `DD-API-KEY` | Org API key |
| `datadogApplicationKey` | `DD-APPLICATION-KEY` | Application key |

Every request sends both headers. `account: "work"` → `datadogApiKey-work` +
`datadogApplicationKey-work`, or pass `apiKeySecretName` /
`applicationKeySecretName`. Pass `site` for non-US1 (`us1` default).

Hosts: `api.datadoghq.com` (US1), plus `api.us3/us5.datadoghq.com`,
`api.datadoghq.eu`, `api.ap1/ap2.datadoghq.com`, `api.uk1.datadoghq.com`,
`api.ddog-gov.com`.

## Import paths

| Export | Import |
| --- | --- |
| root dispatcher (default `smoke-test`) | `kody:@kody/datadog` |
| validate | `kody:@kody/datadog/validate` |
| monitors | `kody:@kody/datadog/monitors` |
| incidents | `kody:@kody/datadog/incidents` |
| logs | `kody:@kody/datadog/logs` |
| dashboards | `kody:@kody/datadog/dashboards` |
| smoke-test | `kody:@kody/datadog/smoke-test` |
| scheduled-status | `kody:@kody/datadog/scheduled-status` |

Prefer static `kody:@kody/datadog/...` imports from `execute`. Do not lead with
`packages.invoke`.

## Smoke test (read-only)

```ts
import datadog from 'kody:@kody/datadog'

export default async function main() {
	return await datadog()
	// without secrets => { ok: true, live: false, setup: { ...URLs } }
	// with secrets => validates keys + sample monitors/dashboards (no writes)
}
```

```ts
import smokeTest from 'kody:@kody/datadog/smoke-test'

export default async function main() {
	return await smokeTest()
}
```

Read-only samples:

```ts
import { searchLogs } from 'kody:@kody/datadog/logs'
import { listMonitors } from 'kody:@kody/datadog/monitors'

export default async function main() {
	const logs = await searchLogs({
		query: 'status:error',
		from: 'now-15m',
		to: 'now',
	})
	const monitors = await listMonitors()
	return { logs, monitors }
}
```

Root dispatcher example:

```ts
import datadog from 'kody:@kody/datadog'

export default async function main() {
	return await datadog({
		action: 'search-logs',
		query: 'status:error',
		from: 'now-15m',
		to: 'now',
	})
}
```

## dryRun / confirm (writes)

Monitor / incident / dashboard create, update, delete, mute, and unmute:
`dryRun: true` returns `{ dryRun: true, method, path, host }` without contacting
Datadog. Live writes also throw unless `confirm: true`.

```ts
import { createMonitor, deleteMonitor } from 'kody:@kody/datadog/monitors'

export default async function main() {
	const preview = await createMonitor({
		type: 'query alert',
		query: 'avg(last_5m):avg:system.cpu.user{*} > 95',
		name: 'High CPU',
		dryRun: true,
	})

	// Only after explicit user confirmation of the target:
	const deleted = await deleteMonitor({
		monitorId: 12345,
		confirm: true,
	})
	return { preview, deleted }
}
```

## Edge cases / fork notes

- No OAuth lane — secret-backed API + application keys only.
- Do not create, mute, or delete anyone's monitors/incidents/dashboards from a
  smoke test or scheduled job.
- The `monitor-status` job is declared **disabled**; it wraps read-only
  `scheduled-status`. Enable only after confirming keys, hosts, and site.
- Fork/adapt: keep secret names `datadogApiKey` / `datadogApplicationKey` (or
  document a rename); do not hard-code org, monitor, or dashboard IDs.