query_spans
Search and filter API traffic span recordings to find specific API calls, identify errors or slow requests, and debug API performance issues.
Instructions
Search and filter API traffic span recordings.
Use this tool to:
Find specific API calls by endpoint name, HTTP method, or status code
Search for errors or slow requests
Get recent traffic for a specific endpoint
Debug specific API calls
Examples:
Find failed requests: where.name = { contains: "/api/users" }, jsonbFilters = [{ column: "outputValue", jsonPath: "$.statusCode", gte: 400, castAs: "int" }]
Find slow requests: where.duration = { gt: 1000 }
Recent traffic for endpoint: where.name = { eq: "/api/orders" }, limit = 10, orderBy = [{ field: "timestamp", direction: "DESC" }]
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| observableServiceId | No | Service ID to query (required if multiple services available) | |
| where | No | Filter conditions for spans | |
| jsonbFilters | No | JSONB path filters for inputValue/outputValue | |
| orderBy | No | Ordering | |
| limit | No | Max results to return | |
| offset | No | Pagination offset | |
| includeInputOutput | No | Include full inputValue/outputValue (verbose) | |
| maxPayloadLength | No | Truncate payload strings to this length |
Implementation Reference
- src/tools/querySpans.ts:158-203 (handler)The handler function for the query_spans tool. Parses input using the schema, calls the API client's querySpans method, formats the spans into a readable text summary, and returns it as MCP content.
export async function handleQuerySpans( client: TuskDriftApiClient, args: Record<string, unknown> ): Promise<{ content: Array<{ type: "text"; text: string }> }> { const input = querySpansInputSchema.parse(args) as QuerySpansInput; const result = await client.querySpans(input); const summary = [ `Found ${result.total} spans (showing ${result.spans.length})`, result.hasMore ? `More results available (offset: ${(input.offset || 0) + result.spans.length})` : "", ] .filter(Boolean) .join("\n"); const spansText = result.spans .map((span, i) => { const lines = [ `[${i + 1}] ${span.name}`, ` ID: ${span.id}`, ` Trace: ${span.traceId}`, ` Package: ${span.packageName}`, ` Duration: ${span.duration.toFixed(2)}ms`, ` Status: ${span.status.code === 0 ? "OK" : span.status.code === 1 ? "UNSET" : "ERROR"}`, ` Timestamp: ${span.timestamp}`, ]; if (span.inputValue && input.includeInputOutput) { lines.push(` Input: ${JSON.stringify(span.inputValue, null, 2).split("\n").join("\n ")}`); } if (span.outputValue && input.includeInputOutput) { lines.push(` Output: ${JSON.stringify(span.outputValue, null, 2).split("\n").join("\n ")}`); } return lines.join("\n"); }) .join("\n\n"); return { content: [ { type: "text", text: `${summary}\n\n${spansText}`, }, ], }; } - src/types.ts:167-184 (schema)Zod schema defining the input structure and validation for the query_spans tool, including filters, ordering, pagination, and payload options.
export const querySpansInputSchema = z.object({ observableServiceId: z.string().optional().describe("Service ID to query (required if multiple services available)"), where: spanWhereClauseSchema.optional().describe("Filter conditions for spans"), jsonbFilters: z.array(jsonbFilterSchema).optional().describe("JSONB path filters for inputValue/outputValue"), orderBy: z .array( z.object({ field: z.enum(["timestamp", "duration", "name"]), direction: z.enum(["ASC", "DESC"]), }) ) .optional() .describe("Ordering"), limit: z.number().min(1).max(100).default(20).describe("Max results to return"), offset: z.number().min(0).default(0).describe("Pagination offset"), includeInputOutput: z.boolean().default(false).describe("Include full inputValue/outputValue (verbose)"), maxPayloadLength: z.number().min(0).default(500).describe("Truncate payload strings to this length"), }); - src/tools/index.ts:24-31 (registration)Registration of the query_spans handler in the toolHandlers map, linking the tool name to its execution function.
export const toolHandlers: Record<string, ToolHandler> = { query_spans: handleQuerySpans, get_schema: handleGetSchema, list_distinct_values: handleListDistinctValues, aggregate_spans: handleAggregateSpans, get_trace: handleGetTrace, get_spans_by_ids: handleGetSpansByIds, }; - src/tools/index.ts:10-17 (registration)Registration of the querySpansTool in the exported tools array for MCP tool discovery.
export const tools: Tool[] = [ querySpansTool, getSchemaTool, listDistinctValuesTool, aggregateSpansTool, getTraceTool, getSpansByIdsTool, ]; - src/tools/querySpans.ts:5-156 (registration)Definition of the querySpansTool object, including name, description, and JSON inputSchema for MCP tool protocol.
export const querySpansTool: Tool = { name: "query_spans", description: `Search and filter API traffic span recordings. Use this tool to: - Find specific API calls by endpoint name, HTTP method, or status code - Search for errors or slow requests - Get recent traffic for a specific endpoint - Debug specific API calls Examples: - Find failed requests: where.name = { contains: "/api/users" }, jsonbFilters = [{ column: "outputValue", jsonPath: "$.statusCode", gte: 400, castAs: "int" }] - Find slow requests: where.duration = { gt: 1000 } - Recent traffic for endpoint: where.name = { eq: "/api/orders" }, limit = 10, orderBy = [{ field: "timestamp", direction: "DESC" }]`, inputSchema: { type: "object", properties: { observableServiceId: { type: "string", description: "Service ID to query. Required if multiple services are available.", }, where: { type: "object", description: "Filter conditions for spans", properties: { name: { type: "object", description: "Filter by span/endpoint name", properties: { eq: { type: "string" }, contains: { type: "string" }, startsWith: { type: "string" }, in: { type: "array", items: { type: "string" } }, }, }, packageName: { type: "object", description: "Filter by instrumentation package (http, pg, fetch, grpc, etc.)", properties: { eq: { type: "string" }, in: { type: "array", items: { type: "string" } }, }, }, instrumentationName: { type: "object", description: "Filter by instrumentation name", properties: { eq: { type: "string" } }, }, duration: { type: "object", description: "Filter by duration in milliseconds", properties: { gt: { type: "number" }, gte: { type: "number" }, lt: { type: "number" }, lte: { type: "number" }, }, }, traceId: { type: "object", description: "Filter by trace ID", properties: { eq: { type: "string" } }, }, isRootSpan: { type: "object", description: "Filter by root span status", properties: { eq: { type: "boolean" } }, }, AND: { type: "array", description: "Combine conditions with AND", }, OR: { type: "array", description: "Combine conditions with OR", }, }, }, jsonbFilters: { type: "array", description: "Filters for JSONB columns (inputValue, outputValue, metadata)", items: { type: "object", properties: { column: { type: "string", enum: ["inputValue", "outputValue", "metadata", "status"], description: "JSONB column to filter", }, jsonPath: { type: "string", description: "JSONPath expression starting with $ (e.g., $.statusCode, $.body.userId)", }, eq: { description: "Equals value" }, neq: { description: "Not equals value" }, gt: { type: "number", description: "Greater than" }, gte: { type: "number", description: "Greater than or equal" }, lt: { type: "number", description: "Less than" }, lte: { type: "number", description: "Less than or equal" }, contains: { type: "string", description: "String contains" }, castAs: { type: "string", enum: ["text", "int", "float", "boolean"], description: "Cast JSONB value to type for comparison", }, decodeBase64: { type: "boolean", description: "Decode base64 string before applying filter", }, thenPath: { type: "string", description: "Additional JSONPath to apply after base64 decoding", }, }, required: ["column", "jsonPath"], }, }, orderBy: { type: "array", description: "Order results", items: { type: "object", properties: { field: { type: "string", enum: ["timestamp", "duration", "name"] }, direction: { type: "string", enum: ["ASC", "DESC"] }, }, required: ["field", "direction"], }, }, limit: { type: "number", description: "Maximum results to return (1-100, default 20)", default: 20, }, offset: { type: "number", description: "Pagination offset", default: 0, }, includeInputOutput: { type: "boolean", description: "Include full inputValue/outputValue in results (can be verbose)", default: false, }, maxPayloadLength: { type: "number", description: "Truncate payload strings to this length", default: 500, }, }, }, };