{ "openapi": "3.1.1", "info": { "title": "Distributed Trace Explorer API", "version": "1.0.0", "summary": "Paste an OTLP, Jaeger or Zipkin trace: span tree, critical path, self-time, N+1 calls and errors.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://distributedtraceexplorer.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Paste an OTLP, Jaeger or Zipkin trace: span tree, critical path, self-time, N+1 calls and errors.", "description": "Paste a trace exported as OTLP JSON (resourceSpans), Jaeger JSON (data[].spans) or Zipkin v2 JSON. The explorer rebuilds the span tree, computes self-time (excluding overlapping child spans), the critical path that determines end-to-end latency, the slowest services, error spans, and detects N+1 queries and fan-out (many sibling spans with the same name), with a service call graph and a waterfall.\n\nMethodology:\n- Formats: OTLP/JSON (resource service.name, startTimeUnixNano/endTimeUnixNano, status.code 2 = ERROR), Jaeger JSON (µs startTime/duration, CHILD_OF references, error=true tag) and Zipkin v2 (µs timestamp/duration, \"error\" tag; shared client/server spans are split so the server span becomes the client span's child).\n- Self-time = span duration minus the union of its children's intervals (clipped to the span), so concurrent children are not double-counted.\n- Critical path: from the longest root span, repeatedly take the child that finishes last before the current cursor, recurse into it, and move the cursor to its start; time not covered by a critical child is the span's own critical time.\n- Repeated siblings: children of one parent with the same service + normalised name/statement (ids and literals masked) at or above the threshold. If their summed duration ≈ wall time they ran sequentially (N+1); if wall time ≤ 40% of the sum they ran in parallel (fan-out).\n- Root-cause errors are error spans none of whose descendants also errored.", "tags": [ "devcloud" ], "x-mcp-tool": "distributed_trace_explorer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistributedTraceExplorerInput" }, "examples": { "example1": { "summary": "OTLP: order page with N+1 queries and a timing-out dependency", "value": { "text": "{\"resourceSpans\":[{\"resource\":{\"attributes\":[{\"key\":\"service.name\",\"value\":{\"stringValue\":\"frontend\"}}]},\"scopeSpans\":[{\"scope\":{\"name\":\"otel-js\"},\"spans\":[{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90001\",\"name\":\"GET /account/orders\",\"kind\":2,\"startTimeUnixNano\":\"1760263200000000000\",\"endTimeUnixNano\":\"1760263200182000000\",\"attributes\":[{\"key\":\"http.request.method\",\"value\":{\"stringValue\":\"GET\"}},{\"key\":\"http.route\",\"value\":{\"stringValue\":\"/account/orders\"}},{\"key\":\"http.response.status_code\",\"value\":{\"intValue\":\"200\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90002\",\"parentSpanId\":\"00f067aa0ba90001\",\"name\":\"GET orders-api\",\"kind\":3,\"startTimeUnixNano\":\"1760263200006000000\",\"endTimeUnixNano\":\"1760263200120000000\",\"attributes\":[{\"key\":\"server.address\",\"value\":{\"stringValue\":\"orders-api\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90003\",\"parentSpanId\":\"00f067aa0ba90001\",\"name\":\"GET recommendations\",\"kind\":3,\"startTimeUnixNano\":\"1760263200008000000\",\"endTimeUnixNano\":\"1760263200170000000\",\"attributes\":[{\"key\":\"server.address\",\"value\":{\"stringValue\":\"reco\"}}],\"status\":{\"code\":2,\"message\":\"upstream timeout after 150ms\"}}]}]},{\"resource\":{\"attributes\":[{\"key\":\"service.name\",\"value\":{\"stringValue\":\"orders-api\"}}]},\"scopeSpans\":[{\"scope\":{\"name\":\"otel-java\"},\"spans\":[{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90010\",\"parentSpanId\":\"00f067aa0ba90002\",\"name\":\"GET /orders\",\"kind\":2,\"startTimeUnixNano\":\"1760263200009000000\",\"endTimeUnixNano\":\"1760263200118000000\",\"attributes\":[{\"key\":\"http.route\",\"value\":{\"stringValue\":\"/orders\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90011\",\"parentSpanId\":\"00f067aa0ba90010\",\"name\":\"SELECT shop.orders\",\"kind\":3,\"startTimeUnixNano\":\"1760263200012000000\",\"endTimeUnixNano\":\"1760263200028000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM orders WHERE customer_id = 42\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90012\",\"parentSpanId\":\"00f067aa0ba90010\",\"name\":\"load order items\",\"kind\":1,\"startTimeUnixNano\":\"1760263200030000000\",\"endTimeUnixNano\":\"1760263200106000000\",\"attributes\":[]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90020\",\"parentSpanId\":\"00f067aa0ba90012\",\"name\":\"SELECT shop.order_items\",\"kind\":3,\"startTimeUnixNano\":\"1760263200032000000\",\"endTimeUnixNano\":\"1760263200040000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM order_items WHERE order_id = 1000\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90021\",\"parentSpanId\":\"00f067aa0ba90012\",\"name\":\"SELECT shop.order_items\",\"kind\":3,\"startTimeUnixNano\":\"1760263200041000000\",\"endTimeUnixNano\":\"1760263200049000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM order_items WHERE order_id = 1001\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90022\",\"parentSpanId\":\"00f067aa0ba90012\",\"name\":\"SELECT shop.order_items\",\"kind\":3,\"startTimeUnixNano\":\"1760263200050000000\",\"endTimeUnixNano\":\"1760263200058000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM order_items WHERE order_id = 1002\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90023\",\"parentSpanId\":\"00f067aa0ba90012\",\"name\":\"SELECT shop.order_items\",\"kind\":3,\"startTimeUnixNano\":\"1760263200059000000\",\"endTimeUnixNano\":\"1760263200067000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM order_items WHERE order_id = 1003\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90024\",\"parentSpanId\":\"00f067aa0ba90012\",\"name\":\"SELECT shop.order_items\",\"kind\":3,\"startTimeUnixNano\":\"1760263200068000000\",\"endTimeUnixNano\":\"1760263200076000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM order_items WHERE order_id = 1004\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90025\",\"parentSpanId\":\"00f067aa0ba90012\",\"name\":\"SELECT shop.order_items\",\"kind\":3,\"startTimeUnixNano\":\"1760263200077000000\",\"endTimeUnixNano\":\"1760263200085000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM order_items WHERE order_id = 1005\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90026\",\"parentSpanId\":\"00f067aa0ba90012\",\"name\":\"SELECT shop.order_items\",\"kind\":3,\"startTimeUnixNano\":\"1760263200086000000\",\"endTimeUnixNano\":\"1760263200094000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM order_items WHERE order_id = 1006\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90027\",\"parentSpanId\":\"00f067aa0ba90012\",\"name\":\"SELECT shop.order_items\",\"kind\":3,\"startTimeUnixNano\":\"1760263200095000000\",\"endTimeUnixNano\":\"1760263200103000000\",\"attributes\":[{\"key\":\"db.system\",\"value\":{\"stringValue\":\"postgresql\"}},{\"key\":\"db.statement\",\"value\":{\"stringValue\":\"SELECT * FROM order_items WHERE order_id = 1007\"}}]},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90030\",\"parentSpanId\":\"00f067aa0ba90010\",\"name\":\"serialize response\",\"kind\":1,\"startTimeUnixNano\":\"1760263200107000000\",\"endTimeUnixNano\":\"1760263200116000000\",\"attributes\":[]}]}]},{\"resource\":{\"attributes\":[{\"key\":\"service.name\",\"value\":{\"stringValue\":\"reco\"}}]},\"scopeSpans\":[{\"scope\":{\"name\":\"otel-python\"},\"spans\":[{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90040\",\"parentSpanId\":\"00f067aa0ba90003\",\"name\":\"POST /recommend\",\"kind\":2,\"startTimeUnixNano\":\"1760263200011000000\",\"endTimeUnixNano\":\"1760263200169000000\",\"attributes\":[],\"status\":{\"code\":2,\"message\":\"feature store timeout\"}},{\"traceId\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"spanId\":\"00f067aa0ba90041\",\"parentSpanId\":\"00f067aa0ba90040\",\"name\":\"GET feature-store\",\"kind\":3,\"startTimeUnixNano\":\"1760263200014000000\",\"endTimeUnixNano\":\"1760263200168000000\",\"attributes\":[{\"key\":\"server.address\",\"value\":{\"stringValue\":\"features.internal\"}}],\"status\":{\"code\":2,\"message\":\"deadline exceeded\"}}]}]}]}" } }, "example2": { "summary": "Zipkin v2: gateway with shared client/server spans and a 503", "value": { "text": "[{\"traceId\":\"5af7183fb1d4cf5f\",\"id\":\"6b221d5bc9e6496c\",\"name\":\"get /api\",\"timestamp\":1760263200000000,\"duration\":386000,\"kind\":\"SERVER\",\"localEndpoint\":{\"serviceName\":\"gateway\"},\"tags\":{\"http.path\":\"/api\"}},{\"traceId\":\"5af7183fb1d4cf5f\",\"parentId\":\"6b221d5bc9e6496c\",\"id\":\"352bff9a74ca9ad2\",\"name\":\"get /inventory\",\"timestamp\":1760263200010000,\"duration\":250000,\"kind\":\"CLIENT\",\"localEndpoint\":{\"serviceName\":\"gateway\"},\"remoteEndpoint\":{\"serviceName\":\"inventory\"}},{\"traceId\":\"5af7183fb1d4cf5f\",\"parentId\":\"6b221d5bc9e6496c\",\"id\":\"352bff9a74ca9ad2\",\"name\":\"get /inventory\",\"timestamp\":1760263200015000,\"duration\":240000,\"kind\":\"SERVER\",\"shared\":true,\"localEndpoint\":{\"serviceName\":\"inventory\"}},{\"traceId\":\"5af7183fb1d4cf5f\",\"parentId\":\"352bff9a74ca9ad2\",\"id\":\"a1b2c3d4e5f60718\",\"name\":\"redis get\",\"timestamp\":1760263200020000,\"duration\":3000,\"kind\":\"CLIENT\",\"localEndpoint\":{\"serviceName\":\"inventory\"},\"remoteEndpoint\":{\"serviceName\":\"redis\"}},{\"traceId\":\"5af7183fb1d4cf5f\",\"parentId\":\"6b221d5bc9e6496c\",\"id\":\"bb11cc22dd33ee44\",\"name\":\"post /audit\",\"timestamp\":1760263200270000,\"duration\":110000,\"kind\":\"CLIENT\",\"localEndpoint\":{\"serviceName\":\"gateway\"},\"remoteEndpoint\":{\"serviceName\":\"audit\"},\"tags\":{\"error\":\"503 Service Unavailable\",\"http.status_code\":\"503\"}}]", "repeatThreshold": 3 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistributedTraceExplorerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "DistributedTraceExplorerInput": { "type": "object", "additionalProperties": false, "properties": { "text": { "title": "Trace JSON", "description": "OTLP/JSON export (e.g. from the OpenTelemetry Collector file exporter), Jaeger UI \"Download JSON\" / API /api/traces/{id}, or a Zipkin v2 span array.", "type": "string", "maxLength": 3000000 }, "file": { "title": "Or upload the file", "description": "Read in memory as UTF-8 text and not stored. Max 5 MiB. Upload as {filename, contentType?, contentBase64}. Max 5120 KiB. Accepts .json.", "type": "object", "additionalProperties": false, "required": [ "filename", "contentBase64" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "contentBase64": { "type": "string" } } }, "traceId": { "title": "Trace id (optional)", "description": "If the payload contains several traces; default is the trace with the most spans.", "type": "string", "maxLength": 64 }, "repeatThreshold": { "title": "Flag repeated sibling spans from", "description": "Minimum number of same-named sibling spans to report as N+1 / fan-out.", "type": "integer", "minimum": 2, "maximum": 100, "default": 5 } }, "required": [] }, "DistributedTraceExplorerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "format", "traceId", "traceCount", "spanCount", "durationMs", "services", "criticalPath", "errors", "repeats", "spans", "orphanSpans" ], "properties": { "format": { "type": "string", "enum": [ "otlp", "jaeger", "zipkin" ] }, "traceId": { "type": "string" }, "traceCount": { "type": "integer" }, "spanCount": { "type": "integer" }, "durationMs": { "type": "number" }, "orphanSpans": { "type": "integer" }, "services": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "service", "spans", "errors", "selfMs", "selfPct", "criticalMs" ], "properties": { "service": { "type": "string" }, "spans": { "type": "integer" }, "errors": { "type": "integer" }, "selfMs": { "type": "number" }, "selfPct": { "type": "number" }, "criticalMs": { "type": "number" } } } }, "criticalPath": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "spanId", "service", "name", "durationMs", "criticalMs" ], "properties": { "spanId": { "type": "string" }, "service": { "type": "string" }, "name": { "type": "string" }, "durationMs": { "type": "number" }, "criticalMs": { "type": "number" } } } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "spanId", "service", "name", "message", "isRootCause" ], "properties": { "spanId": { "type": "string" }, "service": { "type": "string" }, "name": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "isRootCause": { "type": "boolean" } } } }, "repeats": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "parent", "parentName", "service", "name", "count", "totalMs", "wallMs", "pattern", "advice" ], "properties": { "parent": { "type": "string" }, "parentName": { "type": "string" }, "service": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "integer" }, "totalMs": { "type": "number" }, "wallMs": { "type": "number" }, "pattern": { "type": "string" }, "advice": { "type": "string" } } } }, "spans": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "spanId", "parentId", "service", "name", "kind", "depth", "startMs", "durationMs", "selfMs", "error" ], "properties": { "spanId": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "service": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "depth": { "type": "integer" }, "startMs": { "type": "number" }, "durationMs": { "type": "number" }, "selfMs": { "type": "number" }, "error": { "type": "boolean" } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }