Troubleshooting¶
The client cannot connect¶
health()returnshealthy: false, status: "unreachable": the URL is wrong or the service is down. CheckGROW_OPENTELEMETRY_COLLECTOR_URL(defaulthttp://127.0.0.1:4318) and that the port is reachable from where your code runs (inside Docker,127.0.0.1is the container itself).- Calls fail with
UNAVAILABLEafter several seconds: the client retried with backoff. LowermaxRetriesortotalTimeoutto fail faster. - Behind a corporate proxy:
HTTP_PROXY/HTTPS_PROXYare ignored on purpose. Setproxy(orGROW_OPENTELEMETRY_COLLECTOR_PROXY).
CONFIG errors¶
The message names the setting or environment variable, never its value. Typical causes: a URL
without http:// or https://, a duration such as 10 sec (use 10s or 10000), a client
certificate without its key, MAX_RETRIES below 0.
AUTHENTICATION or PERMISSION_DENIED¶
- The collector needs no credentials by default. These errors come from an authenticator extension
(for example
bearertokenauth) or a gateway in front of the collector. ping()is the quickest check: it sends an empty OTLP export with the configured headers.- Put credentials in
headers(OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer%20<token>"orGROW_OPENTELEMETRY_COLLECTOR_HEADERS); values are percent-encoded. Explicit config values win over the environment. - The SDK never prints credentials, so
toString()of the config shows[REDACTED]for header values.
health() says zpages or unreachable¶
details.source = "zpages":health_checkon port 13133 was unreachable and zpages answered. This is normal for collectors with the image's built-in configuration (Grow stacks), which bindhealth_checktolocalhost. Bind it to0.0.0.0:13133to use it directly.status = "unreachable": neitherhealthUrl(default host ofurl, port 13133) norzpagesUrl(port 55679) answered. SethealthUrl/zpagesUrlwhen the admin ports are mapped elsewhere.serverVersion()raisesUNSUPPORTEDwhen zpages is off; settelemetryUrlto the internal telemetry endpoint (http://<collector>:8888/metrics) to readtarget_infoinstead.
Nothing arrives at the collector¶
- Telemetry is batched: call
forceFlush()(orshutdown()/client.close()) before the process exits. grpcuses port 4317 (grpcUrl, default host ofurl),http/protobufport 4318. A per-signal URL (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, …) is used as is, in both protocols.OTEL_SDK_DISABLED=trueorOTEL_<SIGNAL>_EXPORTER=noneswitches signals off.- The Python gRPC exporter needs the
grpcextra:pip install "grow-opentelemetry-collector[grpc]".
TLS errors¶
- Self-signed or private CA: set
tls.caCertPath(GROW_OPENTELEMETRY_COLLECTOR_CA_CERTorOTEL_EXPORTER_OTLP_CERTIFICATE). - Mutual TLS: set both
tls.clientCertPathandtls.clientKeyPath. tls.insecureSkipVerifyonly for local tests; withgrpcit is aCONFIGerror in Python and Rust.
RATE_LIMITED¶
The service asked the client to slow down. The client waits for Retry-After up to
maxRetryAfter (60 s); longer waits fail at once with retryAfter set on the error so your code
can schedule a later attempt.
TIMEOUT¶
requestTimeout (30 s) bounds one attempt and totalTimeout (120 s) the whole call including
retries. Raise them for slow operations, or pass a per-call deadline (signal, ctx, cancel token,
future timeout).
See what the client does¶
Turn on the logger or add hooks: both see every attempt with redacted headers and URLs.
Docker integration tests fail¶
- Run one language:
make test-docker LANGS=go. - In CI, download the
compose-logs-<lang>artifact of the failed job. - Locally, the stack is removed after each run; rerun with Docker logs open
(
docker compose -f docker/compose.yml logs -f) in a second terminal.
Still stuck?¶
Open an issue with the language, package version, OpenTelemetry Collector version and a minimal reproduction (with secrets removed): https://github.com/grow-codes-packages/opentelemetry-collector/issues.