get_trace
Retrieve hierarchical tree of spans in distributed traces to debug requests end-to-end, analyze call chains, and identify performance bottlenecks.
Instructions
Get all spans in a distributed trace as a hierarchical tree.
Use this tool to:
Debug a specific request end-to-end
See the full call chain from HTTP request to database queries
Understand timing and dependencies between spans
Identify bottlenecks in a request
First use query_spans to find spans, then use the traceId to get the full trace.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| observableServiceId | No | Service ID to query (required if multiple services available) | |
| traceId | Yes | Trace ID to fetch | |
| includePayloads | No | Include inputValue/outputValue | |
| maxPayloadLength | No | Truncate payload strings |
Implementation Reference
- src/tools/getTrace.ts:69-98 (handler)The handler function that implements the core logic of the 'get_trace' tool. It validates input using Zod schema, calls the API client to fetch the trace, handles no-trace cases, formats the trace tree using a helper function, and returns structured text content for MCP.
export async function handleGetTrace( client: TuskDriftApiClient, args: Record<string, unknown> ): Promise<{ content: Array<{ type: "text"; text: string }> }> { const input = getTraceInputSchema.parse(args) as GetTraceInput; const result = await client.getTrace(input); if (!result.traceTree) { return { content: [ { type: "text", text: `No trace found for ID: ${input.traceId}`, }, ], }; } const header = `Trace: ${input.traceId}\nSpan Count: ${result.spanCount}\n\nTrace Tree:\n`; const tree = formatTraceTree(result.traceTree, 0, input.includePayloads ?? false); return { content: [ { type: "text", text: header + tree, }, ], }; } - src/types.ts:237-242 (schema)Zod schema for validating the input parameters of the 'get_trace' tool, used in the handler for parsing arguments.
export const getTraceInputSchema = z.object({ observableServiceId: z.string().optional().describe("Service ID to query (required if multiple services available)"), traceId: z.string().describe("Trace ID to fetch"), includePayloads: z.boolean().default(false).describe("Include inputValue/outputValue"), maxPayloadLength: z.number().min(0).default(500).describe("Truncate payload strings"), }); - src/tools/index.ts:24-31 (registration)Registration of the 'get_trace' handler in the central toolHandlers map, which is used by the MCP server to dispatch tool calls.
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)The 'getTraceTool' is included in the exported tools array, providing the tool metadata (name, description, inputSchema) for MCP server registration.
export const tools: Tool[] = [ querySpansTool, getSchemaTool, listDistinctValuesTool, aggregateSpansTool, getTraceTool, getSpansByIdsTool, ]; - src/tools/getTrace.ts:43-67 (helper)Helper function to recursively format the trace spans as a hierarchical indented tree string with status icons, durations, IDs, and optional payloads.
function formatTraceTree(span: TraceSpan, indent: number = 0, includePayloads: boolean): string { const prefix = " ".repeat(indent); const statusIcon = span.status.code === 0 ? "✓" : span.status.code === 2 ? "✗" : "○"; let result = `${prefix}${statusIcon} ${span.name} (${span.duration.toFixed(2)}ms) [${span.packageName}]\n`; result += `${prefix} ID: ${span.spanId}\n`; if (includePayloads && span.inputValue) { const inputStr = JSON.stringify(span.inputValue, null, 2).split("\n").join(`\n${prefix} `); result += `${prefix} Input: ${inputStr}\n`; } if (includePayloads && span.outputValue) { const outputStr = JSON.stringify(span.outputValue, null, 2).split("\n").join(`\n${prefix} `); result += `${prefix} Output: ${outputStr}\n`; } if (span.children && span.children.length > 0) { for (const child of span.children) { result += formatTraceTree(child, indent + 1, includePayloads); } } return result; }