Functions¶
The Grafana Tempo API of this SDK. Every function exists in all five languages with the same
behaviour, named per language convention (getTrace in TypeScript and Java, get_trace in Python
and Rust, GetTrace in Go). Each module page shows every function with an example per language.
| Module | Page | What |
|---|---|---|
| Client | Client and probes | TempoClient: health, ping, serverVersion, buildInfo, echo, ready, close |
| Query | Query client | TempoQueryClient: getTrace, search, searchTraces, searchTags, searchTagValues, listServices, listOperations, traceQLMetrics, waitForTrace, getDependencies |
| TraceQL | TraceQL builder | TraceQL: spanset filters, escaping, structural operators, select |
| Tracing | Tracing setup | initTracing with the Tempo OTLP preset and tenant header; span helpers in Tracing |
Overview¶
| Function | Tempo endpoint | Integration test |
|---|---|---|
health() |
GET /ready |
every language (core.health) |
ping() |
GET /api/v2/search/tags?scope=intrinsic |
every language, single- and multi-tenant |
serverVersion() |
GET /api/status/buildinfo, fallback GET /status/version |
every language |
buildInfo(), echo(), ready() |
/api/status/buildinfo, /api/echo, /ready |
every language |
getTrace(id, {start, end}) |
GET /api/v2/traces/{id}, v1 GET /api/traces/{id} on a route 404 |
every language |
search({traceql, start, end, limit, spss}) |
GET /api/search |
every language |
searchTraces(query) |
GET /api/search (TraceQL built from the query) |
every language (tracing.services) |
searchTags({scope, query, start, end}) |
GET /api/v2/search/tags |
every language |
searchTagValues(tag, {query, start, end}) |
GET /api/v2/search/tag/{tag}/values |
every language |
listServices(), listOperations(service) |
tag values of resource.service.name / name |
every language |
traceQLMetrics(query, range) |
GET /api/metrics/query_range |
every language |
waitForTrace(id, options) |
polls getTrace |
every language (tracing.tree) |
getDependencies(range) |
none | unit tests only: always UNSUPPORTED |
initTracing(config) |
OTLP POST /v1/traces (4318) or gRPC TraceService/Export (4317) |
every language, HTTP and gRPC, single- and multi-tenant |
Service configuration¶
Precedence: explicit value > GROW_GRAFANA_TEMPO_* > Tempo's own variables (TEMPO_URL,
TEMPO_TENANT_ID) > short GROW_TEMPO_* aliases > default. An invalid value raises a
ConfigError that names the variable, never its value.
| Setting | Default | Environment variables (precedence order) |
|---|---|---|
url |
http://127.0.0.1:3200 |
GROW_GRAFANA_TEMPO_URL, TEMPO_URL, GROW_TEMPO_URL |
tenantId |
none | GROW_GRAFANA_TEMPO_TENANT_ID, TEMPO_TENANT_ID, GROW_TEMPO_TENANT_ID |
token |
none | GROW_GRAFANA_TEMPO_TOKEN, GROW_TEMPO_TOKEN |
connectTimeout, requestTimeout, totalTimeout |
10 s, 30 s, 120 s | GROW_GRAFANA_TEMPO_<NAME>, GROW_TEMPO_<NAME> (CONNECT_TIMEOUT, REQUEST_TIMEOUT, TOTAL_TIMEOUT) |
retry.maxRetries |
3 | GROW_GRAFANA_TEMPO_MAX_RETRIES, GROW_TEMPO_MAX_RETRIES |
TLS (caCertPath, clientCertPath, clientKeyPath, insecureSkipVerify) |
system roots | GROW_GRAFANA_TEMPO_CA_CERT / _CLIENT_CERT / _CLIENT_KEY / _INSECURE_SKIP_VERIFY, then the GROW_TEMPO_* alias of each |
proxy |
none | GROW_GRAFANA_TEMPO_PROXY, GROW_TEMPO_PROXY |
- Tenant.
tenantIdis sent asX-Scope-OrgIDon every query call. A multi-tenant Tempo (multitenancy_enabled: true) needs it; a single-tenant Tempo ignores it.tenant-a|tenant-bruns a federated query. Allowed characters:A-Z a-z 0-9 ! - _ . * ' ( ) |, at most 150. - Token. Tempo has no authentication of its own.
tokenis sent asAuthorization: Bearer …for an authenticating reverse proxy in front of Tempo; it is redacted in every string form, log line and error message. A blank token is aConfigError.
The tracing variables (GROW_GRAFANA_TEMPO_OTLP_*, OTEL_EXPORTER_OTLP_*, OTEL_SERVICE_NAME,
OTEL_RESOURCE_ATTRIBUTES, OTEL_TRACES_SAMPLER*) are listed on Tracing setup.
Errors¶
Tempo answers are mapped to the shared error codes:
| Tempo answer | Code |
|---|---|
| 400 (invalid TraceQL, bad parameter) | VALIDATION |
401 no org id (multi-tenant Tempo, no tenant) |
AUTHENTICATION, message "tenant required (X-Scope-OrgID)" |
| 401 / 403 from an auth proxy | AUTHENTICATION / PERMISSION_DENIED |
| 404 on a feature route (e.g. metrics disabled) | UNSUPPORTED |
v2 trace miss (200 {"trace":{}}), v1 trace miss (404) |
not an error: null / None / empty |
| 429, 5xx, network errors | RATE_LIMITED, UNAVAILABLE (retried with backoff, Retry-After honoured) |
| Invalid TraceQL found client side (unbalanced braces, unknown scope) | VALIDATION before any request |
Tempo's tag endpoints silently ignore an invalid q and return unfiltered values, so the SDK checks
TraceQL passed to searchTags / searchTagValues on the client side first.