Skip to content

Compatibility

Runtimes

Language Supported Tested in CI
TypeScript Node.js ≥ 22.12, ESM and CommonJS Node 22, 24
Rust MSRV 1.85, edition 2021, tokio stable, 1.85
Go Go ≥ 1.26 1.26, 1.27
Python ≥ 3.10 3.10, 3.13, 3.14
Java ≥ 17 (Java 17 bytecode) Temurin 17, 21, 25

Grafana Tempo versions

The integration suite runs against Grafana Tempo 3.1.1, the version pinned in the Grow Codes stack catalog (grafana/tempo:3.1.1). The official image is distroless, so docker/tempo/Dockerfile builds the image exactly like the Grow Codes stack template: alpine:3.24.4 plus the SHA-256-pinned official tempo_3.1.1_linux_<arch>.tar.gz, the template's tempo.yaml (OTLP gRPC 4317 and HTTP 4318 receivers, local storage) and its start command. Two instances run side by side: grafana-tempo (single-tenant, the template config) and grafana-tempo-mt (the same image with -multitenancy.enabled=true). When the catalog bumps the Tempo version, bump the Dockerfile arguments in the same release cycle.

Other Tempo 2.x/3.x versions that expose the same HTTP API are expected to work: the v1 trace route is used when the v2 route is missing, and serverVersion() falls back to /status/version.

Functions the service or a language cannot serve

Every public function is called against the real service in the Docker suite. Functions that the service cannot serve are listed here with the reason; they are covered by unit tests.

Function Languages Reason
getDependencies all Tempo has no dependency-graph endpoint (its service-graph processor writes Prometheus metrics instead); always raises UNSUPPORTED

Behaviour covered by unit tests only

These paths cannot be produced by a healthy Tempo container and are tested against mock servers in every language:

Path Why not in Docker
Retries on 429 / 5xx and Retry-After Tempo does not rate-limit the query API
health() / ready() during start-up (HTTP 503 Ingester not ready) the suite starts after Tempo is ready
v1 fallback of getTrace (v2 route missing) Tempo 3.1.1 has the v2 route
UNSUPPORTED for a feature route that answers 404 (e.g. metrics generator disabled) the template enables every route used
Proxy authentication (token, 401 / 403 from a reverse proxy) Tempo has no authentication of its own
Partial v2 responses (status: partial) and zero-valued metric samples without value hard to reproduce on demand

Tempo quirks the SDK handles

Quirk SDK behaviour
v2 trace miss is HTTP 200 {"trace":{},"metrics":{}}; v1 miss is 404 both return "no trace" (null / None / empty / nil)
Ids in trace-by-id JSON are base64; search traceID is hex without leading zeros converted to lower-case hex, left-padded to 32 / 16 characters
Enum names (SPAN_KIND_SERVER, STATUS_CODE_ERROR), unset status is {}, timestamps are decimal strings in ns normalized Span.kind, Span.status, microsecond times
Search, tags and metrics see new data about 30 s after ingest documented; integration tests poll up to 150 s
Search span sets carry no span name unless the query has \| select(name) name is optional in search spans
Metric samples omit value when it is 0 filled in as 0
Tag endpoints ignore an invalid q and return unfiltered values TraceQL is checked client side (VALIDATION)
Query without a tenant on a multi-tenant Tempo → 401 no org id AUTHENTICATION "tenant required (X-Scope-OrgID)"
OTLP export without a tenant on a multi-tenant Tempo → HTTP 503 / gRPC Unavailable (code 14) cannot be surfaced from initTracing (exporters retry, then drop); documented on Tracing setup
/status/buildinfo is not a route (connection closed) serverVersion() uses /api/status/buildinfo, fallback /status/version
The trace-by-id start / end range does not hide recent (live-store) data documented

Skipped conformance scenarios

Scenario Reason
— none; core.health, tracing.services (polled for the 30 s search delay) and tracing.tree pass in all five languages

Language differences

The API is the same in every language; only the conventions differ (naming, durations, async model). Decisions that affect behaviour:

Topic Difference
gRPC insecureSkipVerify Python (grpcio) and Rust (tonic) cannot skip certificate verification for OTLP/gRPC, so insecureSkipVerify with an https gRPC endpoint is a ConfigError there. OTLP/HTTP supports it in every language; TypeScript, Go and Java also support it for gRPC.
limit, spss, exemplars = 0 a VALIDATION error in TypeScript, Rust, Python and Java. Go uses the zero value of SearchRequest.Limit / SpansPerSpanSet / MetricsRange.Exemplars for "not set" (server default); only negative values are rejected there.
TraceQL.span(map) order Go maps have no order, so Go sorts the keys; the other languages keep insertion order. Use And for a fixed order.
Numbers in TraceQL TypeScript cannot tell 1 from 1.0 and writes 1; the other languages write floats with a decimal point.
Tracing config defaults Rust and Python configs always carry protocol, compression and sampler values, so the environment applies while they hold the defaults.
listServices / listOperations time range TypeScript and Python accept an optional start / end; Rust, Go and Java follow the shared TraceQueryClient signature without one.
Python gRPC export needs the grpc extra (pip install "grow-grafana-tempo[grpc]").

Java cannot change the process environment, so loadEnv sets system properties instead and returns the names it set.