Correct description of OTEL_EXPORTER_JAEGER_ENDPOINT and OTEL_TRACES_EXPORTER

[yurishkuro]

Fixes #2331

Changes

The OTEL_EXPORTER_JAEGER_ENDPOINT env var description is updated:

• clarify that it refers to Thrift over HTTP endpoint, provide a link to Jaeger API spec
• change the default value to point to the correct HTTP port, not the gRPC port
• clarify that the path (/api/traces) must be included in the value, to support installations running at remapped URLs

The OTEL_TRACES_EXPORTER env var description updated to reflect state of the world where all but Java SDKs implement http/thrift protocol, not gRPC as was stated in the description.

[abe545]

This is much clearer, thanks!

[carlosalberto]

@yurishkuro Should we get this as part of 1.9, or should we hold this? (Sounds like the former?)

[yurishkuro]

Yes, would be good to include that (ref #2329)

[pellared]

I do not find this PR as a "complete" solution, because:

• It is a breaking change for the default value which is used e.g. in OTel Java
• it does not play well with the OTEL_TRACES_EXPORTER=jaeger which is defined as Jaeger over gRPC (it is defined in the same markdown file)

I propose defining OTEL_EXPORTER_JAEGER_PROTOCOL. Then the default value of OTEL_EXPORTER_JAEGER_ENDPOINT could depend on the selected protocol. This would be similar to the OTLP Exporter configuration.

[tigrannajaryan]

Let's not delay 1.9.0 release if there are still debates on this PR. We have delayed the release for a while now.

(Unless this a critical fix and we cannot release without it).

[yurishkuro]

@pellared I do not believe that OTEL_TRACES_EXPORTER=jaeger == gRPC is actually respected by the SDKs, because Java is the only SDK that even has a + against Protobuf/gRPC in the compliance matrix, whereas almost all SDKs support Thrift/HTTP. So I would suggest changing the description for OTEL_TRACES_EXPORTER=jaeger to say something like "usually HTTP, sometimes gRPC, please check the SDK docs". Then introducing OTEL_EXPORTER_JAEGER_PROTOCOL should be a separate PR since (a) I don't know the level of consensus around it, and (b) this PR is mostly about correcting the wrong value for HTTP endpoint that all (except Java) SDKs implement currently.

[pellared]

@pellared I do not believe that OTEL_TRACES_EXPORTER=jaeger == gRPC is actually respected by the SDKs, because Java is the only SDK that even has a + against Protobuf/gRPC in the compliance matrix, whereas almost all SDKs support Thrift/HTTP. So I would suggest changing the description for OTEL_TRACES_EXPORTER=jaeger to say something like "usually HTTP, sometimes gRPC, please check the SDK docs". Then introducing OTEL_EXPORTER_JAEGER_PROTOCOL should be a separate PR since (a) I don't know the level of consensus around it, and (b) this PR is mostly about correcting the wrong value for HTTP endpoint that all (except Java) SDKs implement currently.

It could be done similarly to the OTLP Exporter. Something like:

[*] If no configuration is provided
the default protocol SHOULD be `http/thrift`
unless SDKs have good reasons to choose other as the default
(e.g. for backward compatibility reasons
when `grpc` was already the default in a stable SDK release).

[nrcventura]

So I would suggest changing the description for OTEL_TRACES_EXPORTER=jaeger to say something like "usually HTTP, sometimes gRPC, please check the SDK docs".

I think that updating that description would be great, and better matches the behavior I saw described across a handful of SDK implementations.

I think that adding the protocol environment variable to the spec is something that's nice to have, but should probably be discussed separately.

[carlosalberto]

@pellared Does the latest commit fix your issue?