Document that the go SDK ignores the OTEL_*_EXPORTER env-vars#7946
Document that the go SDK ignores the OTEL_*_EXPORTER env-vars#7946ringerc wants to merge 2 commits intoopen-telemetry:mainfrom
Conversation
The OpenTelemetry environment variables spec https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#exporter-selection documents the env-vars * OTEL_TRACES_EXPORTER * OTEL_METRICS_EXPORTER * OTEL_LOGS_EXPORTER While these are marked as "MAY" support for providers, it's confusing that the opentelemetry-go docs link to these env-var docs in many other places without mentioning that this part of the spec is not supported. As no logs are emitted to warn that these settings will be ignored, explicitly document the lack of support for them in the relevant godoc.
Make the godocs a bit more explicit about how exporters are registered for each provider class, and what happens if none is explicitly registered.
ringerc
requested review from
MrAlias,
XSAM,
dashpole,
dmathieu,
flc1125 and
pellared
as code owners
|
I believe those environment variables are supported by https://pkg.go.dev/go.opentelemetry.io/contrib/exporters/autoexport. But I agree that it isn't very discoverable right now. |
|
open-telemetry/opentelemetry.io#9128 seems related |
|
@dashpole Definitely not discoverable. I assume it's not mentioned in the otel spec compliance doc because it's a contrib? Ideally it'd be mentioned in the entrypoints for the opentelemetry-go tracing, metric and log packages but since it's a contrib, I'm not sure if that's routinely done. It doesn't help that search engines consistently find the env-var spec https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/ ahead of the general SDK configuration docs https://opentelemetry.io/docs/languages/sdk-configuration/general/ ; the former is much more specific, but is not at all clear that implementations may silently ignore unsupported env-vars such as those for exporter configuration. I wonder if the main otel docs have a list of services with autodiscovery that could be linked to from the env-var docs? |
|
I still think the best place for this to live is on opentelemetry.io. OTOH, it might be helpful (for maintainers as well) to put all of the features (not just env vars) the API + SDK don't support into our package documentation so that it is clearer. I just worry that the list will be really long, and probably will still be buried in a way that isn't super visible. |
TBH, we should document in our package documentation what env vars are supported 😉 |
3 participants
Document that the OpenTelemetry Go SDK ignores the
OTEL_LOGS_EXPORTER,OTEL_METRICS_EXPORTERandOTEL_TRACES_EXPORTERenv-vars documented in the OpenTelemetry Environment Variables Specification.This is permitted, as they are "MAY" features, but it's confusing for users. The opentelemetry-go docs link to the env-var spec in many other places, but don't make it clear (IMO) that only a subset of functionality might actually work.
There's actually a spec compliance document that shows these features as unsupported, but it's not visibly linked to from https://opentelemetry.io/docs/languages/go/ or any other obvious location I could find. I stumbled across it in the opentelemetry-specification source code, then located it in the website under the "Status" top bar element, then the link "For more details on the specification compliance per implementation, see the Spec Compliance Matrix" below the language matrix. There, the environment variables section notes it as unsupported.
Since the Go SDK does support env-vars for some functionality, its docs should be more explicit about which env-vars are supported and which will be silently ignored. Notably, the following are ignored in the go SDK
I've addressed these 3 env-vars. I'm not sure where to place mention of
OTEL_SDK_DISABLEDalso being unsupported. The log-specific ones should go in the log sdk package. I can address these in separate PRs.This PR also adds a couple of small, related updates to the docs regarding how exporters are configured.
I've raised related open-telemetry/opentelemetry-specification#4901 to make it easier to find the compliance matrix when reviewing env-var docs. It's particularly important to refer to for env-vars because an unsupported env-var silently has no effect.
See: