aggregate_spans
Analyze Datadog trace spans by aggregating data based on specified attributes, time intervals, and functions like count, avg, or sum. Use filters for precise querying and group results for detailed monitoring insights.
Instructions
Datadogのトレースspanを集計するツール
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| aggregation | No | 集計関数（オプション、デフォルトは「count」） | count |
| filterFrom | No | 検索開始時間（UNIXタイムスタンプ、秒単位、オプション、デフォルトは15分前） | |
| filterQuery | No | 検索するためのクエリ文字列（オプション、デフォルトは「*」） | * |
| filterTo | No | 検索終了時間（UNIXタイムスタンプ、秒単位、オプション、デフォルトは現在時刻） | |
| groupBy | No | グループ化するための属性（例: ['service', 'resource_name']） | |
| interval | No | 結果をグループ化する時間間隔（オプション、デフォルト '5m'） | 5m |
| type | No | 結果タイプ - timeseries または total（オプション、デフォルトは「timeseries」） | timeseries |
Implementation Reference
- src/tools/spans/aggregate.ts:125-158 (handler)MCP tool handler for 'aggregate_spans': validates parameters using Zod schema, calls the aggregateSpans helper with converted dates, generates a markdown summary and Datadog URL, returns success or error response.export const aggregateSpansHandler = async ( parameters: z.infer<typeof aggregateSpansZodSchema> ): Promise<ToolResponse> => { const validation = aggregateSpansZodSchema.safeParse(parameters); if (!validation.success) { return createErrorResponse( `Parameter validation error: ${validation.error.message}` ); } try { // Convert to Date objects after validation const validatedParams = { ...validation.data, filterFrom: new Date(validation.data.filterFrom * 1000), filterTo: new Date(validation.data.filterTo * 1000), }; const result = await aggregateSpans(validatedParams); const formattedResult = generateSummaryText(validation.data, result); const urlText = `[View in Datadog](https://app.datadoghq.com/apm/traces?query=${encodeURIComponent( validation.data.filterQuery )}&start=${validation.data.filterFrom}&end=${ validation.data.filterTo }&viz=${ validation.data.type === "total" ? "toplist" : validation.data.type }&agg_q=${validation.data.groupBy?.join(",") || ""})`; return createSuccessResponse([formattedResult, urlText]); } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); return createErrorResponse(`Span aggregation error: ${errorMessage}`); } };
- src/tools/spans/aggregate.ts:6-60 (schema)Zod input schema for the aggregate_spans tool, defining optional parameters like filterQuery, time ranges, groupBy attributes, interval, and type (timeseries or total).export const aggregateSpansZodSchema = z.object({ filterQuery: z .string() .optional() .default("*") .describe("Query string to search for (optional, default is '*')"), filterFrom: z .number() .optional() .default(Date.now() / 1000 - 15 * 60) .describe( "Search start time (UNIX timestamp in seconds, optional, default is 15 minutes ago)" ), filterTo: z .number() .optional() .default(Date.now() / 1000) .describe( "Search end time (UNIX timestamp in seconds, optional, default is current time)" ), groupBy: z .array( z.enum([ "service", "resource_name", "env", "status", "operation_name", "type", "@version", "@http.status_code", "@http.client_ip", "@http.url", "@http.method", "@http.host", "@http.user_agent", "@http.path_group", "@http.route", ]) ) .optional() .describe("Attributes to group by (example: ['service', 'resource_name'])"), interval: z .string() .optional() .describe( "Time interval to group results by (optional, only used when type is timeseries)" ), type: z .enum(["timeseries", "total"]) .default("timeseries") .describe( "Result type - timeseries or total (optional, default is 'timeseries')" ), });
- src/index.ts:32-37 (registration)Registration of the 'aggregate_spans' MCP tool on the server, providing the tool name, description, input schema shape, and handler function.server.tool( "aggregate_spans", "Tool for aggregating Datadog trace spans", aggregateSpansZodSchema.shape, aggregateSpansHandler );
- src/datadog/spans/aggregate.ts:9-75 (helper)Core helper function that performs the Datadog API call to aggregate spans: constructs the request body with filters, groupBy, compute (count), calls spansApi.aggregateSpans, processes response into buckets and metadata.export const aggregateSpans = async ( params: SpanAggregationParams ): Promise<SpanAggregationResult> => { try { const configuration = createConfiguration(); const spansApi = new v2.SpansApi(configuration); const { filterFrom, filterTo, filterQuery, interval, type } = params; const requestBody: v2.SpansApiAggregateSpansRequest = { body: { data: { attributes: { compute: [ { aggregation: "count", interval: interval, type: type, }, ], filter: { from: filterFrom.toISOString(), to: filterTo.toISOString(), query: filterQuery, }, groupBy: params.groupBy?.length ? params.groupBy.map((field) => ({ facet: field, limit: 10, })) : undefined, }, type: "aggregate_request", }, }, }; const response = await spansApi.aggregateSpans(requestBody); if (!response.data || response.data.length === 0) { return { buckets: [] }; } const buckets: SpanBucket[] = response.data.map((bucket) => ({ id: bucket.id || "", by: bucket.attributes?.by || {}, compute: bucket.attributes?.compute || {}, computes: bucket.attributes?.computes || {}, })); return { buckets, elapsed: response.meta?.elapsed, requestId: response.meta?.requestId, status: response.meta?.status?.toString(), warnings: response.meta?.warnings?.map((warning) => ({ code: warning.code, detail: warning.detail, title: warning.title, })), }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); console.error(`Error aggregating spans: ${errorMessage}`); throw new Error(`Datadog API error: ${errorMessage}`); } };