Skip to content

Compatibility

Runtimes

Language Supported Tested in CI
TypeScript Node.js ≥ 22.12, ESM and CommonJS Node 22, 24
Rust MSRV 1.88, edition 2021, tokio stable, 1.88
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

Python 3.10 runs only in CI: the development host has no 3.10 interpreter, so local runs use a newer Python (the code avoids 3.11+ APIs).

OpenTelemetry Collector versions

The integration suite runs against otel/opentelemetry-collector-contrib:0.165.0, the tag pinned in the Grow Codes stack catalog, with two collectors: one with the test configuration (docker/config/collector.yaml) and one with the image's built-in configuration, exactly as Grow stacks run it. Exports use plain OTLP (/v1/traces, /v1/logs, /v1/metrics on 4318 and the OTLP gRPC services on 4317), so any collector or OTLP-compatible backend should work. The admin endpoints (health_check on 13133, zpages on 55679, internal telemetry on 8888) are optional; see below.

Functions covered by unit tests only

Every public function is called against the real collector in the Docker suite. These cases cannot be produced by the collector container, so they are covered by unit tests against mock HTTP and gRPC servers in all five languages:

Case Why the container cannot produce it
health() with HTTP 503 (unhealthy) health_check only answers 503 while the pipelines are not ready, a window the fixture cannot hold open
Retries on HTTP 429/502/503/504 and gRPC UNAVAILABLE/RESOURCE_EXHAUSTED, Retry-After, retry exhaustion the collector accepts everything the test sends
Partial success (rejected > 0) the collector reports no rejected records for valid data
TLS and mutual TLS (tls.*, https:// endpoints) the fixture has no TLS listener (decision for v0.1)
Kubernetes and container resource detection the test containers run without a Kubernetes downward API; detectors are tested with fake environments and files
serverVersion() from target_info only the fixture also exposes zpages; the fallback is tested with mocks (the internal telemetry endpoint is read in Docker too)

The trace and log query clients (traceQuery(), logQuery()) are called in Docker and return UNSUPPORTED there: the collector stores nothing. The integration tests read telemetry back through test-only adapters (the collector's file exporter, served over HTTP, and a Jaeger 2.23.0 sidecar); those adapters are not part of the packages.

Skipped conformance scenarios

Scenario Reason
— none: core.health, logging.batch, logging.redaction, logging.roundtrip, tracing.services and tracing.tree pass in every language

Collector behaviour the SDK adapts to

Behaviour of the collector What the SDK does
The image's built-in configuration (used by Grow stacks) binds health_check to localhost:13133, so it is unreachable from other containers health() falls back to zpages /debug/servicez on 55679 (details.source = "zpages"); the test fixture overrides health_check to 0.0.0.0:13133. Platform follow-up: bind health_check to 0.0.0.0 in Grow stacks
No version endpoint serverVersion() parses the "Version" row of zpages /debug/servicez, then service_version of target_info at telemetryUrl (:8888/metrics); UNSUPPORTED when neither answers
zpages tracez returns 404 in 0.165.0 not used
A body over the receiver's size limit gets HTTP 400, not 413 mapped to VALIDATION
A malformed gRPC message gets INTERNAL (13), not INVALID_ARGUMENT mapped to VALIDATION (not retryable, per the OTLP rules)
No authentication by default ping() sends the configured headers; with bearertokenauth or a gateway, 401 / gRPC UNAUTHENTICATED → AUTHENTICATION, 403 / PERMISSION_DENIED → PERMISSION_DENIED
An empty OTLP export returns 200 and stores nothing used by ping() as the authenticated round trip
No native protocol protocol: native → CONFIG

Error mapping of OTLP responses

HTTP statuses use the shared SDK table (Error handling); the error message comes from the google.rpc.Status body (protobuf or JSON). gRPC status codes map the same way in every language:

gRPC status SDK code Retryable
CANCELLED (1) CANCELLED no
INVALID_ARGUMENT (3), FAILED_PRECONDITION (9), OUT_OF_RANGE (11), INTERNAL (13) VALIDATION no
DEADLINE_EXCEEDED (4) TIMEOUT yes
NOT_FOUND (5), UNIMPLEMENTED (12) NOT_FOUND no
ALREADY_EXISTS (6) CONFLICT no
PERMISSION_DENIED (7) PERMISSION_DENIED no
RESOURCE_EXHAUSTED (8) RATE_LIMITED yes
UNAUTHENTICATED (16) AUTHENTICATION no
UNKNOWN (2), ABORTED (10), UNAVAILABLE (14), DATA_LOSS (15), any other code UNAVAILABLE yes

Errors from OTLP exports keep the natural retryable flag of their code. The official exporters have already retried by the OTLP rules (429/502/503/504 and the retryable gRPC codes) before the error reaches you, so do not wrap an export in a second retry loop.

A call on a closed client (health, ping, version, or creating a handle, log client or exporter) fails with CANCELLED in every language.

Language differences

The API is the same in every language; only the conventions differ (naming, durations, async model). The differences below are limits of the official OpenTelemetry libraries of a language or of the generated code:

Topic Languages Difference
gRPC with tls.insecureSkipVerify Python, Rust CONFIG: grpcio and tonic cannot skip certificate verification. Use a CA bundle (tls.caCertPath) or http/protobuf. TypeScript, Go and Java support it (tests only)
Partial success of gRPC log exports Rust not reported: the official tonic log exporter drops the response, so rejected stays 0 (HTTP log exports and all other languages report it)
Custom log severity text Rust a severity text other than TRACE … FATAL becomes the canonical text of its severity number (the Rust OpenTelemetry SDK keeps a &'static str)
Exporter retries Rust the opentelemetry-otlp 0.31 exporters do not retry. Retryable log export failures are retried by the SDK's log batch processor; span and metric exports are not retried. The other languages retry inside the official exporters
Runtime metrics (runtimeMetrics: true) all metric names follow each runtime: TypeScript process.memory.usage, v8js.memory.heap.used, process.cpu.time, nodejs.eventloop.delay.p99, process.uptime; Rust process.* and rust.tokio.workers, rust.tokio.alive_tasks; Go the OpenTelemetry contrib runtime instrumentation (go.memory.*, go.goroutine.count, …); Python process.* and cpython.gc.collections; Java jvm.memory.*, jvm.cpu.*, jvm.thread.count, jvm.class.count, process.uptime
retryable on errors Java the generated exception classes take no flag, so retryable() always equals the default of the error code. The other languages accept an override, which this package never uses on the export paths, so all five report the same flags
Per-signal endpoint setters Rust, Java builder methods take the signal (signal_url(Signal::Traces, …), signalUrl(Signal.TRACES, …)) instead of tracesUrl / logsUrl / metricsUrl
Closing an initTelemetry handle Python, Java the handle is also a context manager / AutoCloseable (with …, try-with-resources)

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