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 |
SigNoz versions¶
The integration suite runs against the same images as the Grow stack templates:
| Component | Image / version |
|---|---|
| SigNoz (query service + UI) | signoz/signoz-community:v0.150.0 |
| SigNoz OTel Collector | v0.144.15 (release binary, OTLP gRPC 4317 / HTTP 4318) |
| ClickHouse | 25.12.5 (one-node cluster, embedded Keeper) |
The SDK uses these query API versions: POST /api/v5/query_range (logs, spans, aggregations,
services, operations), POST /api/v4/traces/{id}/waterfall (traces), GET /api/v3/logs/livetail
(tail), GET /api/v1/fields/keys|values (fields, labels, streams), POST /api/v1/dependency_graph
(dependencies), GET /api/v1/health and GET /api/v1/version. SigNoz has changed its query API
several times; older servers without v5 query_range answer unknown routes with the web UI, which
the SDK reports as UNSUPPORTED. Only MIT-licensed community APIs are used (no ee/ endpoints).
When the stack catalog bumps the SigNoz image, docker/compose.service.yml is bumped in the same
release cycle.
Functions the service or a language cannot serve¶
Every public function is called against the real service in the Docker suite. These behaviours cannot be produced by the self-hosted community stack and are covered by unit tests (mock HTTP / gRPC servers) in all five languages:
| Function / behaviour | Reason |
|---|---|
serverVersion() returning a value |
the community image reports "version": ""; the SDK raises UNSUPPORTED (checked against the real server) |
SigNoz Cloud ingestion key (signoz-ingestion-key header / metadata) and Cloud TLS endpoints |
needs a SigNoz Cloud tenant; the self-hosted collector ignores the header |
getTrace completion of a windowed waterfall (hasMore, more than ~10,000 spans) |
too large to generate in the test stack |
Retries on 429 and 5xx, Retry-After |
the server does not produce them on demand |
| gRPC export error-code mapping (Rust, Java success-path parsing) | the collector accepts every valid request; the mapping is tested with mock gRPC servers |
Skipped conformance scenarios¶
| Scenario step | Reason |
|---|---|
core.health → serverVersion |
gated by the version capability, which SigNoz community does not declare (empty version) |
Capabilities declared by every language: logging query, tail, streams, labels; tracing
query, services, dependencies.
Service behaviour the SDK smooths over¶
- Paging. The server
nextCursorskips rows in the millisecond before it; the SDK uses its own keyset cursor (same wire format in all languages, see Logs). - Aggregation aliases are not echoed (
__result_<i>); the SDK maps them back by index. - Unknown routes return
200 text/html(the UI) →UNSUPPORTED. - Log timestamps are int64 nanoseconds (beyond 2^53): decoded exactly in every language
(TypeScript keeps
timeUnixNanoas a string). - Waterfall times are milliseconds: span start times read through
getTraceandsearchTraces.startMicroshave millisecond precision. - Empty results come back as
rows: null; the SDK returns empty lists. CONTAINSis a LIKE pattern on the server (_and%are wildcards);FilterBuilderescapes them.- Span link attributes are dropped by SigNoz; links come back with empty attributes.
- Unknown filter fields return no rows plus a warning instead of an error.
Language differences¶
The API is the same in every language; only the conventions differ (naming, durations, async
model). Java cannot change the process environment, so loadEnv sets system properties
instead and returns the names it set. The differences below are documented on purpose.
Tracing protocol: explicit vs default¶
initTracing takes the protocol from the SigNoz config (otlpProtocol) when the tracing config
does not choose one and has no explicit endpoint.
| Language | Tracing config protocol field | Effect |
|---|---|---|
| TypeScript | optional (undefined = not set) |
an explicit http/protobuf or grpc always wins |
| Go | "" = not set |
an explicit ProtocolHTTPProtobuf or ProtocolGRPC always wins |
| Rust, Python, Java | defaults to http/protobuf (cannot be told apart from "not set") |
only an explicit grpc wins; http/protobuf follows the SigNoz config |
So with otlpProtocol = grpc and a tracing config that asks for http/protobuf without an
endpoint, TypeScript and Go export over HTTP while Rust, Python and Java export over gRPC. Set
the endpoint in the tracing config (or set otlpProtocol itself) to get the same result
everywhere. In Python, passing just a service name (init_tracing("svc")) also follows the
SigNoz config.
TLS insecureSkipVerify and OTLP/gRPC¶
insecureSkipVerify applies to the query API and to OTLP/HTTP exports in every language. The
gRPC libraries differ:
| Language | OTLP/gRPC logs | OTLP/gRPC traces |
|---|---|---|
| TypeScript | host name check skipped; the certificate chain is still verified | not applied (full verification) |
| Rust | not applied (full verification) | not applied (full verification) |
| Go | applied | applied |
| Python | CONFIG error (grpcio cannot skip verification) |
CONFIG error |
| Java | applied | applied |
Add the CA with tls.caCertPath / tls.caCertPem instead, or use http/protobuf.
Aggregate percentiles¶
TypeScript and Python check the percentile (5, 10, 20, 25, 50, 75, 90, 95, 99) and raise
VALIDATION before sending; Rust, Go and Java send any p<N> and let the server decide.
Records without a severity¶
A log record without a severity is sent and read back as INFO (severity_number 9,
severityText "INFO") in every language.
Result shapes¶
TypeScript getTrace returns a SignozTrace with complete, totalSpans, rootServiceName and
rootName in addition to the shared Trace; TypeScript log records carry the row id and
timeUnixNano. The other languages return the shared models.