Datadog Audit Trail
Investigate user activity, configuration changes, access patterns, and compliance evidence using pup audit-logs.
Sub-Skills
| Sub-skill |
Use when |
| security-investigation |
"Who changed X?", "What did this user do?", "Show me deletions in the last 24h" |
| key-compromise |
"Was this API key compromised?", "What did key XYZ do?", "Investigate suspicious key activity" |
| cost-spike-investigation |
"Why did my bill go up?", "What caused this usage spike?", "Investigate LLM cost increase" |
| compliance-report |
"Generate SOC 2 evidence", "PCI audit log", "User provisioning report for auditor" |
| ai-activity-audit |
"What did the AI assistant do?", "Audit MCP tool calls", "AI governance report" |
Prerequisites
pup auth login # OAuth2 (recommended)
# or set DD_API_KEY + DD_APP_KEY with audit_logs_read scope
Commands
# List recent events
pup audit-logs list --from 1h --limit 100
# Search with a query
pup audit-logs search --query "@action:deleted" --from 24h
# JSON output for piping to jq
pup audit-logs search --query "@usr.email:alice@example.com" --from 7d -o json | jq '.data[].attributes'
Event Schema Quick Reference
| Field |
Description |
Example values |
@usr.email |
Actor email |
alice@example.com |
@evt.actor.type |
How action was taken |
USER, API_KEY, SUPPORT_USER |
@action |
Verb |
created, modified, deleted, accessed, login |
@evt.name |
Event category |
Dashboard, Monitor, Authentication, Access Management |
@asset.type |
Resource type |
dashboard, monitor, api_key, role, user |
@asset.id |
Resource identifier |
abc-123 |
@metadata.api_key.id |
API key used (if applicable) |
key_abc123 |
@metadata.app_key.id |
App key used (if applicable) |
app_abc123 |
@network.client.ip |
Client IP address |
1.2.3.4 |
@network.client.geoip.country.name |
Country |
United States |
@network.client.geoip.as.name |
ASN name |
Amazon.com |
@http.url_details.path |
API endpoint path |
/api/v1/dashboard/xyz |
Search Syntax
Same Lucene-style syntax as Log Explorer:
| Query |
Meaning |
@evt.name:Dashboard |
Exact field match |
@action:deleted |
Action filter |
@usr.email:alice@example.com |
Specific user |
@evt.name:Monitor AND @action:modified |
Compound |
-@action:deleted |
Negation |
@usr.email:* |
Field exists |
@network.client.ip:1.2.3.4 |
IP filter |
Retention
Default retention is 90 days. If querying beyond 90 days, archive to S3/GCS/Azure Blob must be configured. Always check whether the requested time window falls within retention before running a query.
Troubleshooting
| Problem |
Cause |
Fix |
| 403 Forbidden |
Missing audit_logs_read scope |
Add scope to app key in Datadog UI |
| Empty results |
Time window outside retention |
Check archive config; default max is 90 days |
| Timeout |
Query too broad |
Narrow time window or add more filters |
| No IP data |
Internal action or pre-enrichment event |
Not all events have geo data |
References
1---
2name: dd-audit
3description: Audit Trail investigations - who changed what, key compromise, cost spike root cause, compliance evidence (SOC 2/PCI), and AI activity auditing.
4metadata:
5 source: https://skillmd.com/skills/datadog-labs/dd-audit
6 version: "0.1.0"
7 author: datadog-labs
8 repository: https://github.com/datadog-labs/agent-skills
9 tags: datadog,audit,audit-trail,security,compliance,dd-audit
10 alwaysApply: "false"
11---
12
13# Datadog Audit Trail
14
15Investigate user activity, configuration changes, access patterns, and compliance evidence using `pup audit-logs`.
16
17## Sub-Skills
18
19| Sub-skill | Use when |
20|-----------|----------|
21| **security-investigation** | "Who changed X?", "What did this user do?", "Show me deletions in the last 24h" |
22| **key-compromise** | "Was this API key compromised?", "What did key XYZ do?", "Investigate suspicious key activity" |
23| **cost-spike-investigation** | "Why did my bill go up?", "What caused this usage spike?", "Investigate LLM cost increase" |
24| **compliance-report** | "Generate SOC 2 evidence", "PCI audit log", "User provisioning report for auditor" |
25| **ai-activity-audit** | "What did the AI assistant do?", "Audit MCP tool calls", "AI governance report" |
26
27## Prerequisites
28
29```bash
30pup auth login # OAuth2 (recommended)
31# or set DD_API_KEY + DD_APP_KEY with audit_logs_read scope
32```
33
34## Commands
35
36```bash
37# List recent events
38pup audit-logs list --from 1h --limit 100
39
40# Search with a query
41pup audit-logs search --query "@action:deleted" --from 24h
42
43# JSON output for piping to jq
44pup audit-logs search --query "@usr.email:alice@example.com" --from 7d -o json | jq '.data[].attributes'
45```
46
47## Event Schema Quick Reference
48
49| Field | Description | Example values |
50|-------|-------------|----------------|
51| `@usr.email` | Actor email | `alice@example.com` |
52| `@evt.actor.type` | How action was taken | `USER`, `API_KEY`, `SUPPORT_USER` |
53| `@action` | Verb | `created`, `modified`, `deleted`, `accessed`, `login` |
54| `@evt.name` | Event category | `Dashboard`, `Monitor`, `Authentication`, `Access Management` |
55| `@asset.type` | Resource type | `dashboard`, `monitor`, `api_key`, `role`, `user` |
56| `@asset.id` | Resource identifier | `abc-123` |
57| `@metadata.api_key.id` | API key used (if applicable) | `key_abc123` |
58| `@metadata.app_key.id` | App key used (if applicable) | `app_abc123` |
59| `@network.client.ip` | Client IP address | `1.2.3.4` |
60| `@network.client.geoip.country.name` | Country | `United States` |
61| `@network.client.geoip.as.name` | ASN name | `Amazon.com` |
62| `@http.url_details.path` | API endpoint path | `/api/v1/dashboard/xyz` |
63
64## Search Syntax
65
66Same Lucene-style syntax as Log Explorer:
67
68| Query | Meaning |
69|-------|---------|
70| `@evt.name:Dashboard` | Exact field match |
71| `@action:deleted` | Action filter |
72| `@usr.email:alice@example.com` | Specific user |
73| `@evt.name:Monitor AND @action:modified` | Compound |
74| `-@action:deleted` | Negation |
75| `@usr.email:*` | Field exists |
76| `@network.client.ip:1.2.3.4` | IP filter |
77
78## Retention
79
80Default retention is **90 days**. If querying beyond 90 days, archive to S3/GCS/Azure Blob must be configured. Always check whether the requested time window falls within retention before running a query.
81
82## Troubleshooting
83
84| Problem | Cause | Fix |
85|---------|-------|-----|
86| 403 Forbidden | Missing `audit_logs_read` scope | Add scope to app key in Datadog UI |
87| Empty results | Time window outside retention | Check archive config; default max is 90 days |
88| Timeout | Query too broad | Narrow time window or add more filters |
89| No IP data | Internal action or pre-enrichment event | Not all events have geo data |
90
91## References
92
93- [Audit Trail API](https://docs.datadoghq.com/api/latest/audit/)
94- [Audit Trail documentation](https://docs.datadoghq.com/account_management/audit_trail/)
95- [Search syntax](https://docs.datadoghq.com/logs/explorer/search_syntax/)