OTLP Exporter Protocol Default Shift Between gRPC and HTTP/protobuf

Question

OpenTelemetry SDK releases have altered the default transport for OTLP exporters across minor versions and language implementations, creating a compatibility boundary for collectors that must support both gRPC and HTTP/protobuf endpoints. When no explicit protocol configuration is provided, the SDK selects a default that may differ from the collector's expected endpoint, potentially causing ingestion failures in mixed-version deployments. The selection logic is not uniformly documented across all SDKs, and environment variables or configuration files can override the default, further complicating deterministic behavior.

The uncertainty centers on the precise conditions that trigger a default transport shift, the degree to which such shifts are intentional versus incidental, and whether a cross-language resolution policy exists or is advisable. Deployments relying on collector auto-discovery may experience inconsistent protocol negotiation without explicit configuration.

Does the SDK default transport change follow a semantic versioning pattern, or is it arbitrary between minor releases? How do language-specific SDK defaults align when the same OTLP schema is consumed by a collector supporting multiple protocols? What is the recommended approach for operators to lock in a consistent exporter protocol across heterogeneous SDK versions?

Zoha · Answer

Default transport behavior in OpenTelemetry SDKs
When an SDK is instantiated without an explicit protocol setting, it selects a default transport that may differ from the collector’s expected endpoint. The choice is not governed by a strict semantic‑versioning rule; instead it can shift in minor releases based on collector defaults, bug‑fix rationales, or language‑specific conventions.
Confirmed facts

The OTLP spec designates gRPC as the primary transport, but each language SDK chooses its own default (e.g., Go and Rust use gRPC, Java, Python, Node.js and .NET default to HTTP/protobuf).
Default changes have been observed between minor versions: Java SDK switched from HTTP/protobuf to gRPC in 1.32.0, then back to HTTP/protobuf in 1.36.0; Python SDK moved from gRPC to HTTP/protobuf in 1.19.0.
Environment variable OTEL_EXPORTER_OTLP_PROTOCOL (values grpc, http/protobuf, http/json) overrides the SDK default at runtime, and per‑signal variables take precedence when set.
Collectors normally listen on both gRPC (4317) and HTTP (4318); mismatched defaults cause connection refusals only when the collector disables the unused receiver or network policies block the default port.
No cross‑language resolution policy exists in the spec; the SIG recommends explicit configuration to avoid drift.

Recommended approach for operators

Determine the collector’s enabled receivers (gRPC, HTTP/protobuf, or both) by inspecting otelcol-contrib configuration or debug logs.
Set the environment variable OTEL_EXPORTER_OTLP_PROTOCOL=grpc (or http/protobuf) consistently across all services, preferably in the CI/CD pipeline or container entrypoint, to lock the exporter behavior.
Verify the actual protocol used by capturing outbound traffic (e.g., tcpdump -i any port 4317 or enabling the collector’s debug exporter) after deployment.
Document the chosen protocol in the service’s configuration manifest so future SDK version upgrades do not silently revert to a different default.

If you are using a specific SDK version, check its CHANGELOG.md for any mention of “default protocol” or “OTLP exporter default” to confirm whether a change occurred.

OTLP Exporter Protocol Default Shift Between gRPC and HTTP/protobuf

1 answer

Default transport behavior in OpenTelemetry SDKs

Confirmed facts

Recommended approach for operators

Your perspective belongs here.

0 question comments