get-spans
Retrieve individual operations or units of work from a project with filtering options for time range and pagination.
Instructions
Get spans from a project with filtering criteria.
Spans represent individual operations or units of work within a trace. They contain timing information, attributes, and context about the operation being performed.
Example usage: Get recent spans from project "my-project" Get spans in a time range from project "my-project"
Expected return: Object containing spans array and optional next cursor for pagination. Example: { "spans": [ { "id": "span123", "name": "http_request", "context": { "trace_id": "trace456", "span_id": "span123" }, "start_time": "2024-01-01T12:00:00Z", "end_time": "2024-01-01T12:00:01Z", "attributes": { "http.method": "GET", "http.url": "/api/users" } } ], "nextCursor": "cursor_for_pagination" }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectName | Yes | ||
| startTime | No | ||
| endTime | No | ||
| cursor | No | ||
| limit | No |
Implementation Reference
- The handler function for the 'get-spans' tool. It builds query parameters from the input arguments and uses the PhoenixClient to GET spans from the '/v1/projects/{project_identifier}/spans' endpoint. Returns a structured MCP response with JSON-stringified spans data and pagination cursor.
async ({ projectName, startTime, endTime, cursor, limit = 100 }) => { const params: NonNullable< Types["V1"]["operations"]["getSpans"]["parameters"]["query"] > = { limit, }; if (cursor) { params.cursor = cursor; } if (startTime) { params.start_time = startTime; } if (endTime) { params.end_time = endTime; } const response = await client.GET( "/v1/projects/{project_identifier}/spans", { params: { path: { project_identifier: projectName, }, query: params, }, } ); return { content: [ { type: "text", text: JSON.stringify( { spans: response.data?.data ?? [], nextCursor: response.data?.next_cursor ?? null, }, null, 2 ), }, ], }; } - Input validation schema for 'get-spans' tool using Zod. Requires projectName (string); optional: startTime, endTime, cursor (strings); limit (number, 1-1000, default 100).
projectName: z.string(), startTime: z.string().optional(), endTime: z.string().optional(), cursor: z.string().optional(), limit: z.number().min(1).max(1000).default(100).optional(), }, - js/packages/phoenix-mcp/src/spanTools.ts:76-132 (registration)Registers the 'get-spans' MCP tool on the server with its name, description, input schema, and handler function.
"get-spans", GET_SPANS_DESCRIPTION, { projectName: z.string(), startTime: z.string().optional(), endTime: z.string().optional(), cursor: z.string().optional(), limit: z.number().min(1).max(1000).default(100).optional(), }, async ({ projectName, startTime, endTime, cursor, limit = 100 }) => { const params: NonNullable< Types["V1"]["operations"]["getSpans"]["parameters"]["query"] > = { limit, }; if (cursor) { params.cursor = cursor; } if (startTime) { params.start_time = startTime; } if (endTime) { params.end_time = endTime; } const response = await client.GET( "/v1/projects/{project_identifier}/spans", { params: { path: { project_identifier: projectName, }, query: params, }, } ); return { content: [ { type: "text", text: JSON.stringify( { spans: response.data?.data ?? [], nextCursor: response.data?.next_cursor ?? null, }, null, 2 ), }, ], }; } ); - js/packages/phoenix-mcp/src/index.ts:44-44 (registration)Top-level call to initializeSpanTools during MCP server setup, which registers the 'get-spans' tool among others.
initializeSpanTools({ client, server });