Tempo MCP Server Tools Reference

The TalkOps Tempo MCP Server exposes 16 specialized tools categorized into search, retrieval, metrics, pivots, diagnostics, and topology.

---

1. Search & Retrieval Tools

tempo_traceql_search

Search for distributed traces using raw TraceQL expressions or structured Kubernetes filters (namespace, service, deployment, status, duration).

Parameters:

Parameter	Type	Required	Description
q	string	No	Raw TraceQL query expression.
service	string	No	Service name filter (e.g. checkout-service).
namespace	string	No	Kubernetes namespace filter (e.g. production).
status	string	No	Trace status filter: 'error', 'ok', 'unset'.
min_duration	string	No	Minimum duration filter (e.g. '500ms', '2s').
max_duration	string	No	Maximum duration filter.
start	string	No	Start time window (ISO timestamp or duration string like '1h').
end	string	No	End time window.
limit	integer	No	Maximum traces to return (default: 20, clamped to 100).

Example Invocation:

{
  "service": "order-api",
  "status": "error",
  "min_duration": "1500ms",
  "start": "30m"
}

---

tempo_get_trace

Retrieve a single distributed trace by its 32-character hexadecimal trace ID using Tempo 2.9+ LLM-optimized format.

Parameters:

Parameter	Type	Required	Description
trace_id	string	Yes	32-character hex trace identifier.

---

tempo_summarize_trace

Primary Analysis Primitive: Analyzes a full trace DAG to extract the critical path, detect error spans, isolate suspected root-cause services, and provide time-gap disambiguation (separating true critical-path delays from async background timers).

Parameters:

Parameter	Type	Required	Description
trace_id	string	Yes	32-character hex trace identifier.

Example Output:

{
  "trace_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "root_service": "frontend-gateway",
  "total_duration_ms": 4250,
  "critical_path_duration_ms": 4210,
  "async_time_gap_ms": 40,
  "suspected_root_cause": {
    "service": "inventory-service",
    "operation": "SELECT * FROM inventory FOR UPDATE",
    "duration_ms": 3850,
    "percentage_of_trace": 91.4,
    "error": false
  },
  "recommended_queries": [
    "{service.name=\"inventory-service\" && name=\"SELECT * FROM inventory FOR UPDATE\"}"
  ]
}

---

tempo_compare_traces

Performs a 5-dimensional structural and timing diff between two traces (trace_id_a vs trace_id_b): services involved, span count, duration, error states, and critical path changes.

Parameters:

Parameter	Type	Required	Description
trace_id_a	string	Yes	Baseline (healthy) trace ID.
trace_id_b	string	Yes	Degraded (slow or errored) trace ID.

---

tempo_find_related_traces

Finds correlated traces using correlation strategies: same_service_errors, same_endpoint, or temporal_neighbors.

Parameters:

Parameter	Type	Required	Description
trace_id	string	Yes	Seed trace identifier.
strategy	string	Yes	Correlation strategy: 'same_service_errors', 'same_endpoint', 'temporal_neighbors'.
limit	integer	No	Maximum related traces to return (default: 5).

---

2. Metrics & Cross-Pillar Pivots

tempo_traceql_metrics_range

Executes TraceQL metric range queries to calculate RED metrics (Rate, Errors, Duration) over time.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	TraceQL metric expression.
start	string	No	Start time.
end	string	No	End time.
step	string	No	Step interval (e.g. '1m').

Example Invocation:

{
  "query": "rate({status=error} [5m])",
  "start": "1h",
  "step": "1m"
}

---

tempo_traceql_metrics_instant

Executes an instant point-in-time snapshot of a TraceQL metric query.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	TraceQL metric expression.

---

tempo_get_exemplar_traces

Extracts exemplar trace IDs from a TraceQL metrics query result for instant drill-down.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	TraceQL metric expression.

---

tempo_get_trace_from_log

Parses a trace ID out of a raw log line (supporting trace_id=, traceId:, etc.) and automatically fetches the summarized trace.

Parameters:

Parameter	Type	Required	Description
log_line	string	Yes	Raw log message containing a trace identifier.

---

3. Schema & Topology Tools

tempo_get_attribute_names

Discovers indexed attribute names grouped by scope (resource, span, intrinsic, event, link).

Parameters:

Parameter	Type	Required	Description
scope	string	No	Scope filter: 'resource', 'span', 'intrinsic', 'all'.

---

tempo_get_attribute_values

Enumerates distinct indexed values for a specific attribute name within a time window.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Attribute name (e.g. http.status_code, service.name).

---

tempo_get_k8s_attribute_map

Returns the canonical mapping between Kubernetes resource concepts and OpenTelemetry trace attributes.

---

tempo_get_service_dependencies

Maps service dependencies, request volumes, and error rates using metrics-generator service graph data.

Parameters:

Parameter	Type	Required	Description
service	string	No	Filter topology by a focal service.

---

4. Diagnostics & Alerting

tempo_list_backends

Lists all configured Tempo backend endpoints and their health statuses.

---

tempo_get_diagnostics

Comprehensive diagnostics reporting health, component services, and ring member states.

Parameters:

Parameter	Type	Required	Description
backend_id	string	No	Target backend identifier (default: 'default').

---

tempo_generate_alerting_expression

Translates a high-latency or error trace pattern into a ready-to-deploy PromQL alerting rule.

Parameters:

Parameter	Type	Required	Description
service	string	Yes	Service identifier.
threshold_duration_ms	number	No	Latency threshold in milliseconds.
error_rate_threshold	number	No	Error rate threshold percentage.