uptrace_search_spans
Search and filter distributed tracing spans using UQL queries to analyze errors, monitor services, and investigate performance issues with custom time ranges and output formats.
Instructions
Search spans with custom filters using Uptrace Query Language (UQL). Supports WHERE clauses, filters, and aggregations. Use 'where _status_code = "error"' to find error spans.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| time_gte | Yes | Start time in ISO format (YYYY-MM-DDTHH:MM:SSZ) | |
| time_lt | Yes | End time in ISO format (YYYY-MM-DDTHH:MM:SSZ) | |
| query | No | UQL query string (e.g., 'where service_name = "aktar"' or 'where _status_code = "error"') | |
| limit | No | Maximum number of spans to return (default: 100) | |
| format | No | Output format: 'text' for human-readable format, 'json' for structured JSON with all attributes | text |
Implementation Reference
- src/uptrace_mcp/server.py:405-460 (handler)The handler logic for 'uptrace_search_spans' that validates input, calls the Uptrace client, and processes/formats the response.
if name == "uptrace_search_spans": try: time_gte = parse_datetime(arguments["time_gte"]) time_lt = parse_datetime(arguments["time_lt"]) except (KeyError, ValueError) as e: return [ TextContent( type="text", text=f"Error: {str(e)}", ) ] query = arguments.get("query") limit = arguments.get("limit", 100) output_format = arguments.get("format", "text") # "text" or "json" logger.info(f"Querying spans: {query} (limit: {limit}, format: {output_format})") response = client.get_spans( time_gte=time_gte, time_lt=time_lt, query=query, limit=limit ) # Return JSON format if requested if output_format == "json": import json # Convert spans to dict with all attributes spans_data = [] for span in response.spans: span_dict = { "id": span.id, "parent_id": span.parent_id, "trace_id": span.trace_id, "project_id": span.project_id, "group_id": span.group_id, "type": span.type, "system": span.system, "kind": span.kind, "name": span.name, "display_name": span.display_name, "time": span.time, "duration": span.duration, "status_code": span.status_code, "status_message": span.status_message, "attrs": span.attrs or {}, "events": [ {"name": event.name, "time": event.time, "attrs": event.attrs or {}} for event in span.events ], "links": span.links or [], } spans_data.append(span_dict) result = { "query": query or None, "total": response.count, "returned": len(response.spans), - src/uptrace_mcp/server.py:170-195 (schema)The tool registration and schema definition for 'uptrace_search_spans'.
Tool( name="uptrace_search_spans", description="Search spans with custom filters using Uptrace Query Language (UQL). Supports WHERE clauses, filters, and aggregations. Use 'where _status_code = \"error\"' to find error spans.", inputSchema={ "type": "object", "properties": { "time_gte": { "type": "string", "description": "Start time in ISO format (YYYY-MM-DDTHH:MM:SSZ)", }, "time_lt": { "type": "string", "description": "End time in ISO format (YYYY-MM-DDTHH:MM:SSZ)", }, "query": { "type": "string", "description": "UQL query string (e.g., 'where service_name = \"aktar\"' or 'where _status_code = \"error\"')", }, "limit": { "type": "integer", "description": "Maximum number of spans to return (default: 100)", "default": 100, }, "format": { "type": "string", "enum": ["text", "json"],