Datadog
Arcade.dev LLM tools for Datadog log and trace search
0.1.0Datadog toolkit for Arcade provides LLM tools to search, aggregate, and inspect Datadog logs, APM spans, and traces programmatically. It enables AI agents to perform observability triage — identifying error patterns, latency trends, and trace-level diagnostics — directly against a Datadog account.
Capabilities
- Log & span search: Query log events and APM spans over configurable time windows using Datadog search syntax.
- Aggregation & bucketing: Aggregate events or spans by count, percentile, or other measures, optionally grouped by facets and bucketed by time — suited for triage questions like rising error rates or latency trends without paginating raw results.
- Facet discovery: Probe which facets have live data in a given window and dataset before filtering or grouping, resolving environment-specific naming empirically (e.g.
@http.status_codevs@http.status). - Trace inspection: Retrieve a single assembled trace with span summary, handling internal pagination to avoid oversized responses on large traces.
Secrets
This toolkit requires three secrets configured in your Arcade environment.
-
DATADOG_API_KEY— A Datadog API key that authenticates requests to the Datadog API. Generate one in the Datadog dashboard under Organization Settings → API Keys. API keys are not scoped; any valid key for your org works. See Datadog API Keys docs. -
DATADOG_APPLICATION_KEY— A Datadog Application key, required alongside the API key to authorize read operations against logs, spans, and traces. Create one under Organization Settings → Application Keys. For least-privilege access, scope it to the specific permissions your agent needs (e.g.logs_read_data,apm_read). See Datadog Application Keys docs. -
DATADOG_SITE— The Datadog site URL for your account (e.g.datadoghq.com,datadoghq.eu,us3.datadoghq.com). This determines which regional API endpoint the toolkit calls. Find your site in the Datadog dashboard URL or under Organization Settings. See Datadog site list.
Configure secrets at https://api.arcade.dev/dashboard/auth/secrets. For details on how Arcade handles secrets in tools, see https://docs.arcade.dev/en/guides/create-tools/tool-basics/create-tool-secrets.
Available tools(5)
| Tool name | Description | Secrets | |
|---|---|---|---|
Aggregate log events or spans over a window, optionally grouped and bucketed by time.
Use this single call for triage questions like which service errors most, whether an
error rate is rising, or whether a span's latency percentile is climbing (set
aggregation to a percentile with measure '@duration' and an interval), instead of
paginating raw events. For spans, group_by facets, query filters, and the returned
bucket labels all use the same field names span results expose ('resource',
'operation'); the Datadog resource_name/operation_name facets are handled internally. | 2 | ||
Probe which standard facets are groupable and filterable for a dataset in a window.
Call this before grouping or filtering when the right facet name is uncertain,
instead of guessing a name and reading an empty bucket set back: it returns the
facets that actually have data to break down by right now, each with sample
values. This resolves environment-specific naming (e.g. whether HTTP status is
exposed as @http.status_code or @http.status) empirically rather than by guess. | 2 | ||
Retrieve a single trace assembled with a summary, bounding the span list.
Pages through the trace's spans internally; an unknown trace id returns an
empty trace. Use this single call to inspect a trace end to end without
risking an oversized response on large traces. | 2 | ||
Search Datadog log events matching a query over a time window. | 2 | ||
Search Datadog APM spans matching a query over a time window. | 2 |
Selected tools
No tools selected.
Click "Show all tools" to add tools.
Requirements
Select tools to see requirements
Datadog.AggregateEvents
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Aggregate log events or spans over a window, optionally grouped and bucketed by time. Use this single call for triage questions like which service errors most, whether an error rate is rising, or whether a span's latency percentile is climbing (set aggregation to a percentile with measure '@duration' and an interval), instead of paginating raw events. For spans, group_by facets, query filters, and the returned bucket labels all use the same field names span results expose ('resource', 'operation'); the Datadog resource_name/operation_name facets are handled internally.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
dataset | string | Required | Whether to count log events or APM spans.logsspans |
query | string | Optional | Datadog search query using facet syntax, e.g. 'status:error'. Empty counts everything in the window. Only indexed facets are filterable; a filter on a non-indexed field silently matches nothing rather than erroring. |
start_time | string | Optional | Start of the time window as Datadog date math (now-1h), ISO-8601 (YYYY-MM-DDTHH:MM:SSZ), or Unix epoch milliseconds. Defaults to now-1h. |
end_time | string | Optional | End of the time window, in the same formats as start_time. Defaults to now. |
group_by | array<string> | Optional | Facets to break the count down by, e.g. 'service' or 'status'. Multiple facets nest the grouping. Empty returns a single total for the window. Only configured facets are groupable; grouping by a non-facet field yields an empty bucket set (surfaced in warnings), not an error. |
interval | string | Optional | Bucket the counts into a time series with this rollup, e.g. '5m' or '1h'. Leave empty for a single total per group with no time buckets. |
group_limit | integer | Optional | Maximum number of groups to return per facet (1-1000). Defaults to 20. |
aggregation | string | Optional | How to aggregate matching events. COUNT tallies events; the other values compute a statistic of the measure facet. Defaults to COUNT.countavgminmaxsump50p75p90p95p99 |
measure | string | Optional | Numeric facet the statistic is computed over when aggregation is not COUNT, e.g. '@duration' for span latency (the value is then in nanoseconds). Defaults to '@duration'. Ignored when aggregation is COUNT. |
Requirements
Output
json— No description provided.Datadog.DiscoverFacets
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Probe which standard facets are groupable and filterable for a dataset in a window. Call this before grouping or filtering when the right facet name is uncertain, instead of guessing a name and reading an empty bucket set back: it returns the facets that actually have data to break down by right now, each with sample values. This resolves environment-specific naming (e.g. whether HTTP status is exposed as @http.status_code or @http.status) empirically rather than by guess.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
dataset | string | Required | Whether to probe log facets or APM span facets.logsspans |
query | string | Optional | Datadog search query scoping the probe, e.g. 'status:error'. Empty probes against everything in the window (the widest, most reliable signal). For spans, filter on 'resource'/'operation' with the same names span results expose; they are mapped to Datadog's facets automatically. |
start_time | string | Optional | Start of the time window as Datadog date math (now-1h), ISO-8601 (YYYY-MM-DDTHH:MM:SSZ), or Unix epoch milliseconds. Defaults to now-1h. |
end_time | string | Optional | End of the time window, in the same formats as start_time. Defaults to now. |
Requirements
Output
json— No description provided.Datadog.GetTrace
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Retrieve a single trace assembled with a summary, bounding the span list. Pages through the trace's spans internally; an unknown trace id returns an empty trace. Use this single call to inspect a trace end to end without risking an oversized response on large traces.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
trace_id | string | Required | The Datadog trace id to inspect. |
start_time | string | Optional | Start of the window to search for the trace's spans, as Datadog date math (now-1h), ISO-8601 (YYYY-MM-DDTHH:MM:SSZ), or Unix epoch milliseconds. Defaults to now-1h. |
end_time | string | Optional | End of the window, in the same formats as start_time. Defaults to now. |
max_spans | integer | Optional | Upper bound on spans to include in the response (1-500). Defaults to 100. The returned set is further auto-fit to a token-safe size, so the default call is always safe; the summary covers every span the call assembled (summary_complete is false on the rare trace too large to assemble in full), and the kept spans are every error span plus the slowest, with the result marked truncated when any are dropped. |
Requirements
Output
json— No description provided.Datadog.SearchLogs
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Search Datadog log events matching a query over a time window.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
query | string | Required | Datadog logs search query using facet syntax, e.g. 'service:checkout status:error'. Empty matches all logs in the window. Only indexed facets are filterable: an attribute that merely appears in a result (e.g. an http status under a log's attributes) is not necessarily a queryable facet, and a filter on a non-indexed field silently matches nothing rather than erroring. |
start_time | string | Optional | Start of the time window as Datadog date math (now-1h), ISO-8601 (YYYY-MM-DDTHH:MM:SSZ), or Unix epoch milliseconds. Defaults to now-15m. |
end_time | string | Optional | End of the time window, in the same formats as start_time. Defaults to now. |
max_results | integer | Optional | Maximum number of log events to return (1-1000). Defaults to 50. |
sort_order | string | Optional | Order results by event timestamp. Defaults to NEWEST.newestoldest |
cursor | string | Optional | Pagination cursor from a previous result's next_cursor. Leave empty to fetch the first page. |
Requirements
Output
json— No description provided.Datadog.SearchSpans
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Search Datadog APM spans matching a query over a time window.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
query | string | Required | Datadog spans search query using facet syntax, e.g. 'service:api-gateway status:error'. Filter on an endpoint or operation with the same field names that span results expose ('resource', 'operation'); they are mapped to Datadog's facets automatically. Quote values containing spaces or dots, e.g. resource:"GET /v1/auth". Bound span latency with @duration in nanoseconds (e.g. @duration:>500000000 for >500ms, or @duration:<60000000000 to exclude long-lived streaming spans when sorting by LONGEST). Empty matches all spans in the window. Only indexed facets are filterable: an attribute that merely appears in a span's meta is not necessarily a queryable facet, and a filter on a non-indexed field silently matches nothing rather than erroring. |
start_time | string | Optional | Start of the time window as Datadog date math (now-1h), ISO-8601 (YYYY-MM-DDTHH:MM:SSZ), or Unix epoch milliseconds. Defaults to now-15m. |
end_time | string | Optional | End of the time window, in the same formats as start_time. Defaults to now. |
max_results | integer | Optional | Maximum number of spans to return (1-1000). Defaults to 50. |
sort_order | string | Optional | Order results by start time or duration. Use LONGEST to surface the slowest spans first. Defaults to NEWEST.newestoldestlongest |
cursor | string | Optional | Pagination cursor from a previous result's next_cursor. Leave empty to fetch the first page. |
Requirements
Output
json— No description provided.