OTLP Environment variables do not match specification #971
Comments
jsuereth
added
bug
|
Thanks for copying the relevant sections. This would mean that there can be only one OTLP exporter configured at given time ( as specified by |
|
And to add further - otel-cpp doesn't support environment variables as defined in the specs, this is also indicated clearly in the compliance matrix :
We would like to take exception for supporting the env-variables as per the specs, as the support can be added latter without breaking the API. The currently defined environment variables are proprietary to otel-cpp implementation and can co-exist along with specs env-variables once they are supported. @jsuereth - let us know if that would be fine ? |
|
Do you have users of these env variables now? The specification denotes:
If you didn't have any environment variable configuration, that would make sense. However if you do provide environment variable configuration, then it should be consistent with otel. This is a major issue for consistency across the SDKs in OTel. At a minimum, I think you should:
What's the reason for (continued) divergence right now? |
We don't know for sure, but we are trying best avoid doing breaking changes while in release candidate.
Good point. Will add support for OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE as suggested by you. |
|
@jsuereth - Can you review this PR #974 for the changes for this issue. As mentioned as comment in PR:
Another alternate suggestion from @ThomsonTan - instead of any code changes for now, we can enable the NO_ENV macro, which basically for now disable all environment variables ( used here : ), and then enable it once we are compliant with the specs |
…er, SDK, or separate component (#3730) Fixes #3721 ## Why The Go SIG is working towards stabilizing the OTLP metrics exporter. The Go SIG would prefer to manage the exporter environment variables through a distinct package: https://pkg.go.dev/go.opentelemetry.io/contrib/exporters/autoexport. This approach is akin to [Java Autoconfigure](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure). The rationale behind this decision is as follows: 1. If users aim to utilize the `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_TRACES_EXPORTER`, we aim to support all the values documented in the specification. We want to ensure that users are not prone to encountering runtime errors if a protocol driver hasn't been registered in the code. 2. Simultaneously, we wish to avoid applications to depend on all exporter implementations defined in the specification. Currently, it is not clear of such design is in compliance with the specification. ## What Define that **configuration options MAY be implemented by exporter, SDK, or separate component**. While this PR may be seen as a breaking change, because of the way how the languages adopted the specification I would say that this is a "clarification" or "adopting to the reality". Here is how different languages currently implement the OTLP configuration options. ### .NET Configuration options implemented by exporter. Side note: Per-signal endpoint configuration options are not implemented. Source code: - https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol ### C++ Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are not implemented at all. See: open-telemetry/opentelemetry-cpp#971. Source code: - https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/otlp ### Erlang Configuration options implemented by exporter. Source code: - https://github.com/open-telemetry/opentelemetry-erlang/tree/main/apps/opentelemetry_exporter ### Go Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are implemented by a separate component (autoexport) Source code (package docs): - https://pkg.go.dev/go.opentelemetry.io/contrib/exporters/autoexport - https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace ### Java Configuration options implemented by an autoconfigure component. Source code: - https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure - https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/otlp/all/src/main/java/io/opentelemetry/exporter/otlp ### JavaScript Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are implemented by a separate component (opentelemetry-sdk-node) Source code: - https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node - https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/exporter-trace-otlp-http ### PHP Configuration options implemented by exporter. Source code: - https://github.com/open-telemetry/opentelemetry-php/tree/main/src/Contrib/Otlp ### Python Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are implemented by the SDK. Source code: - https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/__init__.py - https://github.com/open-telemetry/opentelemetry-python/tree/main/exporter ### Ruby Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are implemented by the SDK. Source code: - https://github.com/open-telemetry/opentelemetry-ruby/blob/main/sdk/lib/opentelemetry/sdk/configurator.rb - https://github.com/open-telemetry/opentelemetry-ruby/tree/main/exporter/otlp-http ### Rust Configuration options implemented by exporter. Source code: - https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry-otlp ### Swift Env vars not supported. ### Previous work and discussions - #3721 - #3722
…er, SDK, or separate component (open-telemetry#3730) Fixes open-telemetry#3721 ## Why The Go SIG is working towards stabilizing the OTLP metrics exporter. The Go SIG would prefer to manage the exporter environment variables through a distinct package: https://pkg.go.dev/go.opentelemetry.io/contrib/exporters/autoexport. This approach is akin to [Java Autoconfigure](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure). The rationale behind this decision is as follows: 1. If users aim to utilize the `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_TRACES_EXPORTER`, we aim to support all the values documented in the specification. We want to ensure that users are not prone to encountering runtime errors if a protocol driver hasn't been registered in the code. 2. Simultaneously, we wish to avoid applications to depend on all exporter implementations defined in the specification. Currently, it is not clear of such design is in compliance with the specification. ## What Define that **configuration options MAY be implemented by exporter, SDK, or separate component**. While this PR may be seen as a breaking change, because of the way how the languages adopted the specification I would say that this is a "clarification" or "adopting to the reality". Here is how different languages currently implement the OTLP configuration options. ### .NET Configuration options implemented by exporter. Side note: Per-signal endpoint configuration options are not implemented. Source code: - https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol ### C++ Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are not implemented at all. See: open-telemetry/opentelemetry-cpp#971. Source code: - https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/otlp ### Erlang Configuration options implemented by exporter. Source code: - https://github.com/open-telemetry/opentelemetry-erlang/tree/main/apps/opentelemetry_exporter ### Go Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are implemented by a separate component (autoexport) Source code (package docs): - https://pkg.go.dev/go.opentelemetry.io/contrib/exporters/autoexport - https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace ### Java Configuration options implemented by an autoconfigure component. Source code: - https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure - https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/otlp/all/src/main/java/io/opentelemetry/exporter/otlp ### JavaScript Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are implemented by a separate component (opentelemetry-sdk-node) Source code: - https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node - https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/exporter-trace-otlp-http ### PHP Configuration options implemented by exporter. Source code: - https://github.com/open-telemetry/opentelemetry-php/tree/main/src/Contrib/Otlp ### Python Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are implemented by the SDK. Source code: - https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-sdk/src/opentelemetry/sdk/_configuration/__init__.py - https://github.com/open-telemetry/opentelemetry-python/tree/main/exporter ### Ruby Most configuration options implemented by exporter. However, the `*_PROTOCOL` env vars are implemented by the SDK. Source code: - https://github.com/open-telemetry/opentelemetry-ruby/blob/main/sdk/lib/opentelemetry/sdk/configurator.rb - https://github.com/open-telemetry/opentelemetry-ruby/tree/main/exporter/otlp-http ### Rust Configuration options implemented by exporter. Source code: - https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry-otlp ### Swift Env vars not supported. ### Previous work and discussions - open-telemetry#3721 - open-telemetry#3722
Currently, OTLP environment variables (OTEL_EXPORTER_OTLP_GRPC_ENDPOINT) does not match the specification.
Copied relevant sections:
Configuration Options
The following configuration options MUST be available to configure the OTLP exporter. Each configuration option MUST be overridable by a signal specific option.
OTEL_EXPORTER_ENDPOINTwith OTLP/HTTP, exporters SHOULD follow the collector convention of appending the version and signal to the path (e.g.v1/tracesorv1/metrics). The per-signal endpoint configuration options take precedence and can be used to override this behavior. See the [OTLP Specification][otlphttp-req] for more details.https://localhost:4317OTEL_EXPORTER_OTLP_ENDPOINTOTEL_EXPORTER_OTLP_TRACES_ENDPOINTOTEL_EXPORTER_OTLP_METRICS_ENDPOINTOTEL_EXPORTER_OTLP_CERTIFICATEOTEL_EXPORTER_OTLP_TRACES_CERTIFICATEOTEL_EXPORTER_OTLP_METRICS_CERTIFICATEOTEL_EXPORTER_OTLP_HEADERSOTEL_EXPORTER_OTLP_TRACES_HEADERSOTEL_EXPORTER_OTLP_METRICS_HEADERSgzipOTEL_EXPORTER_OTLP_COMPRESSIONOTEL_EXPORTER_OTLP_TRACES_COMPRESSIONOTEL_EXPORTER_OTLP_METRICS_COMPRESSIONOTEL_EXPORTER_OTLP_TIMEOUTOTEL_EXPORTER_OTLP_TRACES_TIMEOUTOTEL_EXPORTER_OTLP_METRICS_TIMEOUTSupported values for
OTEL_EXPORTER_OTLP_*COMPRESSIONoptions:gzipis the only specified compression method for now. Other options MAY be supported by language SDKs and should be documented for each particular language.Example 1
The following configuration sends all signals to the same collector:
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317Example 2
Traces and metrics are sent to different collectors:
Specify Protocol
Currently, OTLP has more than one transport protocol it can support, e.g.
grpc,http/json,http/protobuf. As of 1.0 of the specification, thereis no specified default, or configuration via environment variables. We
reserve the following environment variables for configuration of protocols in
the future:
OTEL_EXPORTER_OTLP_PROTOCOLOTEL_EXPORTER_OTLP_TRACES_PROTOCOLOTEL_EXPORTER_OTLP_METRICS_PROTOCOLSDKs have an unspecified default, if no configuration is provided.
Specifying headers via environment variables
The
OTEL_EXPORTER_OTLP_HEADERS,OTEL_EXPORTER_OTLP_TRACES_HEADERS,OTEL_EXPORTER_OTLP_METRICS_HEADERSenvironment variables will contain a list of key value pairs, and these are expected to be represented in a format matching to the W3C Correlation-Context, except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings.The text was updated successfully, but these errors were encountered: