search_spans
Search Datadog trace spans using a customizable query, time range, and pagination to analyze and retrieve monitoring data efficiently.
Instructions
Datadogのトレースspanを検索するツール
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filterFrom | No | 検索開始時間（UNIXタイムスタンプ、秒単位、オプション、デフォルトは15分前） | |
| filterQuery | No | 検索するためのクエリ文字列（オプション、デフォルトは「*」） | * |
| filterTo | No | 検索終了時間（UNIXタイムスタンプ、秒単位、オプション、デフォルトは現在時刻） | |
| pageCursor | No | 次のページを取得するためのカーソル（オプション） | |
| pageLimit | No | 取得するスパンの最大数（オプション、デフォルトは25） |
Implementation Reference
- src/tools/spans/search.ts:113-141 (handler)The MCP tool handler for 'search_spans'. Validates parameters using Zod schema, calls the core searchSpans function, generates a markdown summary of results, provides a Datadog UI link, and handles errors.export const searchSpansHandler = async ( parameters: z.infer<typeof searchSpansZodSchema> ): Promise<ToolResponse> => { const validation = searchSpansZodSchema.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 searchSpans(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})`; return createSuccessResponse([formattedResult, urlText]); } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); return createErrorResponse(`Span search error: ${errorMessage}`); } };
- src/tools/spans/search.ts:6-37 (schema)Zod schema defining the input parameters for the search_spans tool, including query, time range, pagination.export const searchSpansZodSchema = 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)" ), pageLimit: z .number() .min(1) .max(1000) .optional() .default(25) .describe("Maximum number of spans to retrieve (optional, default is 25)"), pageCursor: z .string() .optional() .describe("Cursor to retrieve the next page (optional)"), });
- src/index.ts:25-30 (registration)Registration of the 'search_spans' tool on the MCP server with name, description, input schema, and handler.server.tool( "search_spans", "Tool for searching Datadog trace spans", searchSpansZodSchema.shape, searchSpansHandler );
- src/datadog/spans/search.ts:5-51 (helper)Core helper function that performs the actual Datadog API call to search spans using the SpansApi, maps the response to the expected format, and handles pagination cursor.export const searchSpans = async ( params: SpanSearchParams ): Promise<SpanSearchResult> => { try { const configuration = createConfiguration(); const spansApi = new v2.SpansApi(configuration); const response = await spansApi.listSpansGet({ filterQuery: params.filterQuery, filterFrom: params.filterFrom.toISOString(), filterTo: params.filterTo.toISOString(), pageLimit: params.pageLimit || 25, pageCursor: params.pageCursor, }); if (!response.data || response.data.length === 0) { return { spans: [] }; } const spans = response.data.map((spanData) => ({ id: spanData.id || "", traceId: spanData.attributes?.traceId, spanId: spanData.attributes?.spanId, parentId: spanData.attributes?.parentId, service: spanData.attributes?.service, resource: spanData.attributes?.resourceName, host: spanData.attributes?.host, env: spanData.attributes?.env, startTimestamp: spanData.attributes?.startTimestamp?.toISOString(), endTimestamp: spanData.attributes?.endTimestamp?.toISOString(), duration: spanData.attributes?.attributes?.duration, type: spanData.attributes?.type, tags: spanData.attributes?.tags || [], attributes: spanData.attributes?.attributes || {}, })); const nextCursor = response.meta?.page?.after; return { spans, nextCursor, }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); console.error(`Error searching spans: ${errorMessage}`); throw new Error(`Datadog API error: ${errorMessage}`); } };