get_spans_by_ids
Retrieve detailed span recordings including payloads by specifying their IDs. Use to examine specific API requests, database queries, or distributed traces captured by Tusk Drift.
Instructions
Fetch specific span recordings by their IDs.
Use this tool when you have span IDs from a previous query and need the full details including payloads.
This is useful for:
Getting full details for spans found via query_spans
Examining specific requests in detail
Comparing multiple specific spans
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| observableServiceId | No | Service ID to query (required if multiple services available) | |
| ids | Yes | Span recording IDs to fetch | |
| includePayloads | No | Include inputValue/outputValue | |
| maxPayloadLength | No | Truncate payload strings |
Implementation Reference
- src/tools/getSpansByIds.ts:42-94 (handler)Main handler function: parses input with schema, calls API client.getSpansByIds, formats spans as markdown text response.export async function handleGetSpansByIds( client: TuskDriftApiClient, args: Record<string, unknown> ): Promise<{ content: Array<{ type: "text"; text: string }> }> { const input = getSpansByIdsInputSchema.parse(args) as GetSpansByIdsInput; const result = await client.getSpansByIds(input); if (result.spans.length === 0) { return { content: [ { type: "text", text: `No spans found for the provided IDs.`, }, ], }; } const spansText = result.spans .map((span, i) => { const lines = [ `## Span ${i + 1}: ${span.name}`, `- **ID:** ${span.id}`, `- **Trace ID:** ${span.traceId}`, `- **Span ID:** ${span.spanId}`, `- **Package:** ${span.packageName}`, `- **Duration:** ${span.duration.toFixed(2)}ms`, `- **Status:** ${span.status.code === 0 ? "OK" : span.status.code === 1 ? "UNSET" : "ERROR"}`, `- **Timestamp:** ${span.timestamp}`, `- **Root Span:** ${span.isRootSpan ? "Yes" : "No"}`, ]; if (span.inputValue) { lines.push(`\n**Input:**\n\`\`\`json\n${JSON.stringify(span.inputValue, null, 2)}\n\`\`\``); } if (span.outputValue) { lines.push(`\n**Output:**\n\`\`\`json\n${JSON.stringify(span.outputValue, null, 2)}\n\`\`\``); } return lines.join("\n"); }) .join("\n\n---\n\n"); return { content: [ { type: "text", text: `Found ${result.spans.length} spans:\n\n${spansText}`, }, ], }; }
- src/types.ts:244-249 (schema)Zod input schema defining parameters: observableServiceId, ids (array 1-20), includePayloads, maxPayloadLength.export const getSpansByIdsInputSchema = z.object({ observableServiceId: z.string().optional().describe("Service ID to query (required if multiple services available)"), ids: z.array(z.string()).min(1).max(20).describe("Span recording IDs to fetch"), includePayloads: z.boolean().default(true).describe("Include inputValue/outputValue"), maxPayloadLength: z.number().min(0).default(500).describe("Truncate payload strings"), });
- src/tools/getSpansByIds.ts:5-40 (registration)Tool object registration: defines name, description, and inline JSON schema (mirrors Zod schema). Exported and collected in tools/index.ts for MCP server.export const getSpansByIdsTool: Tool = { name: "get_spans_by_ids", description: `Fetch specific span recordings by their IDs. Use this tool when you have span IDs from a previous query and need the full details including payloads. This is useful for: - Getting full details for spans found via query_spans - Examining specific requests in detail - Comparing multiple specific spans`, inputSchema: { type: "object", properties: { observableServiceId: { type: "string", description: "Service ID to query. Required if multiple services are available.", }, ids: { type: "array", items: { type: "string" }, description: "Span recording IDs to fetch (max 20)", }, includePayloads: { type: "boolean", description: "Include full inputValue/outputValue", default: true, }, maxPayloadLength: { type: "number", description: "Truncate payload strings to this length", default: 500, }, }, required: ["ids"], }, };
- src/tools/index.ts:10-31 (registration)Central registration: adds getSpansByIdsTool to tools[] array and maps get_spans_by_ids to handleGetSpansByIds in toolHandlers. Used by src/index.ts to register with MCP server.export const tools: Tool[] = [ querySpansTool, getSchemaTool, listDistinctValuesTool, aggregateSpansTool, getTraceTool, getSpansByIdsTool, ]; export type ToolHandler = ( client: TuskDriftApiClient, args: Record<string, unknown> ) => Promise<{ content: Array<{ type: "text"; text: string }> }>; 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/apiClient.ts:101-112 (helper)API client helper: makes HTTP POST to /api/drift/query/spans-by-id with resolved service ID and input params./** * Get span recordings by IDs */ async getSpansByIds(input: GetSpansByIdsInput): Promise<{ spans: SpanRecording[]; }> { const { observableServiceId, ...rest } = input; return this.request("/spans-by-id", { observableServiceId: this.resolveServiceId(observableServiceId), ...rest, }); }