| name | tempo-api |
| description | SignalDB Tempo API compatibility - implemented/stub endpoints, query flow, admin API, Grafana native plugin, and built-in Tempo datasource support. Use when working with HTTP API, Grafana integration, or query endpoints. |
| user-invocable | false |
| sources | ["src/router/src/endpoints/tempo.rs","src/router/src/endpoints/admin.rs","src/grafana-plugin/src/**","src/grafana-plugin/backend/src/**"] |
SignalDB Tempo API Compatibility
Implemented Endpoints (Router :3000)
| Endpoint | Status | Description |
|---|
GET /tempo/api/echo | Implemented | Health check |
GET /tempo/api/traces/{trace_id} | Implemented | Single trace lookup -> routes to Querier; start/end time hints prune the scanned range |
GET /tempo/api/v2/traces/{trace_id} | Implemented | Same handler as v1 for now |
GET /tempo/api/search | Implemented | Trace search with filters -> routes to Querier; spss caps spans per span set in the response |
GET /tempo/api/search/tags | Implemented | Static tag set of actually-queryable tags (service.name, name, status) |
GET /tempo/api/search/tag/{tag_name}/values | Implemented | Real data: distinct column values via Flight SQL for supported tags; static values for status; 501 for unindexed attribute tags |
GET /tempo/api/v2/search/tags | Implemented | Same tag set, scoped (resource/intrinsic) |
GET /tempo/api/v2/search/tag/{tag_name}/values | Implemented | Same backing as v1 tag values |
GET /tempo/api/metrics/query | 501 Not Implemented | TraceQL metrics not implemented (returns 501 since #552, no fabricated series) |
GET /tempo/api/metrics/query_range | 501 Not Implemented | Same as above |
Query Flow
- Client -> Router HTTP API (:3000)
- Router validates auth (API key -> TenantContext)
- Router discovers Querier via
QueryExecution capability
- Router sends Flight
do_get ticket to Querier
- Ticket format:
find_trace:{tenant_slug}:{dataset_slug}:{trace_id}[:{start}:{end}] (unix-second time hints, appended only when present) or search_traces:{tenant_slug}:{dataset_slug}:{params}
- Querier executes DataFusion SQL against Iceberg tables
- Results stream back as Arrow RecordBatches (trace not found -> Flight
not_found status -> HTTP 404)
- Router formats as Tempo JSON response
Tempo gRPC Querier Protocol (standalone querier)
The standalone querier serves Tempo's internal tempopb.Querier gRPC
protocol on its Flight port (default :50054) so a Tempo query-frontend can
use SignalDB as a querier (src/querier/src/services/tempo.rs):
FindTraceByID / SearchRecent: implemented, backed by TraceService- Tenant: authenticated
TenantContext extension wins, else X-Scope-OrgID
header (dataset default), else default/default
SearchBlock: Unimplemented (no Tempo block model in SignalDB)- Tag endpoints: static queryable tag set; tag values empty (HTTP API serves
real values via Flight SQL)
Admin API Endpoints
Requires admin_api_key from config:
| Endpoint | Method | Description |
|---|
/api/v1/admin/tenants | GET/POST | List/create tenants |
/api/v1/admin/tenants/{id} | GET/PUT/DELETE | Manage tenant |
/api/v1/admin/tenants/{id}/api-keys | GET/POST | List/create API keys |
/api/v1/admin/tenants/{id}/api-keys/{key_id} | DELETE | Revoke API key |
/api/v1/admin/tenants/{id}/datasets | GET/POST | List/create datasets |
/api/v1/admin/tenants/{id}/datasets/{dataset_id} | DELETE | Delete dataset |
A separate tenant self-service API is mounted at /api/v1 (see the
multi-tenancy skill).
Grafana Integration
Native Datasource Plugin (src/grafana-plugin/)
- Frontend: TypeScript React-based query/config editors (
@grafana/data, @grafana/ui)
- Backend: Rust via
grafana-plugin-sdk, connects to Router's Flight service (default http://localhost:50053); standalone cargo workspace (own lockfile/target), built via npm run build:backend
- Auth passthrough: API key, tenant ID, dataset ID from Grafana secure JSON -> Flight headers
- Signal support: Traces, metrics, logs query types
- Arrow conversion: Direct RecordBatch -> Grafana Frame
Using Grafana's Built-in Tempo Datasource
The Router's Tempo-compatible endpoints at /tempo/api/... work directly with Grafana's Tempo datasource for trace lookup and basic search.
Key Files
| File | Purpose |
|---|
src/router/src/endpoints/tempo.rs | Tempo API HTTP handlers |
src/router/src/endpoints/admin.rs | Admin API handlers |
src/tempo-api/ | Protobuf definitions and Tempo types |
src/querier/src/flight.rs | Query execution, ticket parsing |
src/grafana-plugin/ | Native Grafana plugin |
