AgentSkillsCN

tempo-api

SignalDB与Tempo API的兼容性——已实现的接口与占位接口、查询流程、Admin API、Grafana原生插件，以及内置的Tempo数据源支持。适用于对接HTTP API、Grafana集成，或查询接口开发时使用。

SKILL.md
--- frontmatter
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

SignalDB Tempo API Compatibility

Implemented Endpoints (Router :3000)

EndpointStatusDescription
GET /tempo/api/echoImplementedHealth check
GET /tempo/api/traces/{trace_id}ImplementedSingle trace lookup -> routes to Querier
GET /tempo/api/searchImplementedTrace search with filters -> routes to Querier
GET /tempo/api/search/tagsStub (empty)
GET /tempo/api/search/tag/{tag_name}/valuesStub (empty)
GET /tempo/api/v2/search/tagsStub (empty)
GET /tempo/api/v2/search/tag/{tag_name}/valuesStub (empty)
GET /tempo/api/metrics/queryStub (hardcoded)
GET /tempo/api/metrics/query_rangeStub (hardcoded)

Query Flow

  1. •Client -> Router HTTP API (:3000)
  2. •Router validates auth (API key -> TenantContext)
  3. •Router discovers Querier via QueryExecution capability
  4. •Router sends Flight do_get ticket to Querier
  5. •Ticket format: find_trace:{tenant_slug}:{dataset_slug}:{trace_id} or search_traces:{tenant_slug}:{dataset_slug}:{params}
  6. •Querier executes DataFusion SQL against Iceberg tables
  7. •Results stream back as Arrow RecordBatches
  8. •Router formats as Tempo JSON response

Admin API Endpoints

Requires admin_api_key from config:

EndpointMethodDescription
/api/v1/admin/tenantsGET/POSTList/create tenants
/api/v1/admin/tenants/{id}GET/PUT/DELETEManage tenant
/api/v1/admin/tenants/{id}/api-keysGET/POSTList/create API keys
/api/v1/admin/tenants/{id}/datasetsGET/POSTList/create datasets

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)
  • •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

FilePurpose
src/router/src/tempo.rsTempo API HTTP handlers
src/router/src/admin.rsAdmin API handlers
src/tempo-api/Protobuf definitions and Tempo types
src/querier/src/flight.rsQuery execution, ticket parsing
src/grafana-plugin/Native Grafana plugin