query-metrics
Retrieve time-series metric data from Datadog using metric query syntax. Provide a query, start, and end time to get data for analysis.
Instructions
Query time-series metric data from Datadog. Supports any Datadog metric query syntax (e.g., avg:system.cpu.user{host:myhost} by {env})
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Datadog metric query. Example: avg:system.cpu.user{host:myhost} by {env} | |
| from | Yes | Start time as Unix epoch seconds | |
| to | Yes | End time as Unix epoch seconds |
Implementation Reference
- src/tools/metrics.ts:10-38 (handler)Main handler function for the 'query-metrics' tool. Calls Datadog metricsApi.queryMetrics with the provided params (from, to, query), then maps the response series into a structured result with timestamps and values.
export async function queryMetrics(params: z.infer<typeof queryMetricsSchema>) { const response = await metricsApi.queryMetrics({ from: params.from, to: params.to, query: params.query, }); const series = response.series ?? []; const results = series.map((s) => ({ metric: s.metric, displayName: s.displayName, unit: s.unit, scope: s.scope, expression: s.expression, pointCount: s.pointlist?.length ?? 0, points: s.pointlist?.map(([ts, val]) => ({ timestamp: new Date((ts ?? 0) * 1000).toISOString(), value: val, })), })); return { query: response.query, from: response.fromDate ? new Date(response.fromDate).toISOString() : undefined, to: response.toDate ? new Date(response.toDate).toISOString() : undefined, seriesCount: series.length, series: results, }; } - src/tools/metrics.ts:4-8 (schema)Zod schema for query-metrics input validation. Defines three fields: query (string), from (numeric, start time as Unix epoch seconds), and to (numeric, end time as Unix epoch seconds).
export const queryMetricsSchema = z.object({ query: z.string().describe("Datadog metric query. Example: avg:system.cpu.user{host:myhost} by {env}"), from: z.coerce.number().describe("Start time as Unix epoch seconds"), to: z.coerce.number().describe("End time as Unix epoch seconds"), }); - src/index.ts:172-177 (registration)Registration of the 'query-metrics' tool via the local tool() helper. Associates the name, description, schema shape, and wraps the handler with wrapToolHandler.
tool( "query-metrics", "Query time-series metric data from Datadog. Supports any Datadog metric query syntax (e.g., avg:system.cpu.user{host:myhost} by {env})", queryMetricsSchema.shape, wrapToolHandler(queryMetrics), ); - src/index.ts:162-167 (helper)The tool() registration helper that registers the tool with a name, category, and conditionally registers it with the MCP server if the category is enabled.
function tool(name: string, description: string, schema: any, handler: any): void { registry.register(name, description, currentCategory); if (registry.isEnabled(currentCategory)) { server.tool(name, description, schema, handler); } }