Add OTEL_EXPORTER_JAEGER_PROTOCOL and improve description of other OT…

…EL_EXPORTER_JAEGER_* env vars (#2341) * Standardize OTEL_EXPORTER_JAEGER_PROTOCOL * Update sdk-environment-variables.md * Update CHANGELOG.md * Update CHANGELOG.md * Update CHANGELOG.md * Add udp/thrift.binary and reformat table * Update sdk-environment-variables.md Co-authored-by: Carlos Alberto Cortez <[email protected]>
open-telemetry · Feb 17, 2022 · 9a0a330 · 9a0a330
1 parent e16e1a7
commit 9a0a330
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 21 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -44,7 +44,7 @@ release.
 ### Traces
 
 - Clarify `StartSpan` returning the parent as a non-recording Span when no SDK
- is in use
+ is in use.
  ([#2121](https:/open-telemetry/opentelemetry-specification/pull/2121))
 - Align Jaeger remote sampler endpoint with OTLP endpoint.
  ([#2246](https:/open-telemetry/opentelemetry-specification/pull/2246))
@@ -53,9 +53,13 @@ release.
 - Add support for probability sampling in the OpenTelemetry `tracestate` entry and
  add optional specification for consistent probability sampling.
  ([#2047](https:/open-telemetry/opentelemetry-specification/pull/2047))
-- Change description and default value of OTEL_EXPORTER_JAEGER_ENDPOINT env var
- to point to the correct HTTP port and correct description of OTEL_TRACES_EXPORTER
- ([#2333](https:/open-telemetry/opentelemetry-specification/pull/2333)).
+- Change description and default value of `OTEL_EXPORTER_JAEGER_ENDPOINT` environment
+ variable to point to the correct HTTP port and correct description of
+ `OTEL_TRACES_EXPORTER`.
+ ([#2333](https:/open-telemetry/opentelemetry-specification/pull/2333))
+- Add `OTEL_EXPORTER_JAEGER_PROTOCOL` environment variable to select the protocol
+ used by the Jaeger exporter.
+ ([#2341](https:/open-telemetry/opentelemetry-specification/pull/2341))
 
 ### Metrics
 

diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md
@@ -126,16 +126,25 @@ See [OpenTelemetry Protocol Exporter Configuration Options](./protocol/exporter.
 
 | Name | Description | Default |
 |---------------------------------|------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
-| OTEL_EXPORTER_JAEGER_AGENT_HOST | Hostname for the Jaeger agent [1] | "localhost" |
-| OTEL_EXPORTER_JAEGER_AGENT_PORT | Port for the Jaeger agent `compact` Thrift protocol | 6831 |
-| OTEL_EXPORTER_JAEGER_ENDPOINT | Full URL of [Thrift over HTTP][jaeger_http] endpoint for Jaeger traces [2] | <!-- markdown-link-check-disable --> `"http://localhost:14268/api/traces"` <!-- markdown-link-check-enable --> |
-| OTEL_EXPORTER_JAEGER_TIMEOUT | Maximum time the Jaeger exporter will wait for each batch export | 10s |
-| OTEL_EXPORTER_JAEGER_USER | Username to be used for HTTP basic authentication | |
-| OTEL_EXPORTER_JAEGER_PASSWORD | Password to be used for HTTP basic authentication | |
+| OTEL_EXPORTER_JAEGER_PROTOCOL | The transport protocol. The value MUST be one of: [`http/thrift.binary`][jaeger_http], [`grpc`][jaeger_grpc], [`udp/thrift.compact`][jaeger_udp], [`udp/thrift.binary`][jaeger_udp] | `http/thrift.binary` [1] |
+| OTEL_EXPORTER_JAEGER_ENDPOINT (`http/thrift.binary` protocol) | Full URL of the [Jaeger HTTP endpoint][jaeger_collector] | `http://localhost:14268/api/traces` |
+| OTEL_EXPORTER_JAEGER_ENDPOINT (`grpc` protocol) | URL of the [Jaeger gRPC endpoint][jaeger_collector] | `http://localhost:14250` |
+| OTEL_EXPORTER_JAEGER_TIMEOUT (`http/thrift.binary`, `grpc` protocols) | Maximum time the Jaeger exporter will wait for each batch export | 10s |
+| OTEL_EXPORTER_JAEGER_USER (`http/thrift.binary`, `grpc` protocols) | Username to be used for HTTP basic authentication | |
+| OTEL_EXPORTER_JAEGER_PASSWORD (`http/thrift.binary`, `grpc` protocols) | Password to be used for HTTP basic authentication | |
+| OTEL_EXPORTER_JAEGER_AGENT_HOST (`udp/thrift.*` protocols) | Hostname of the [Jaeger agent][jaeger_agent] | `localhost` |
+| OTEL_EXPORTER_JAEGER_AGENT_PORT (`udp/thrift.compact` protocol) | `udp/thrift.compact` port of the [Jaeger agent][jaeger_agent] | `6831` |
+| OTEL_EXPORTER_JAEGER_AGENT_PORT (`udp/thrift.binary` protocol) | `udp/thrift.binary` port of the [Jaeger agent][jaeger_agent] | `6832` |
+
+[1] The default transport SHOULD be `http/thrift.binary` unless
+ SDKs have good reasons to choose other as the default
+ (e.g. for backward compatibility reasons).
 
-[1] See [Jaeger Agent](https://www.jaegertracing.io/docs/latest/deployment/#agent) documentation.
-
-[2] When the exporter uses the gRPC protocol, the environment variable refers to the gRPC endpoint and the default value should be `http://localhost:14250`.
+[jaeger_http]: https://www.jaegertracing.io/docs/latest/apis/#thrift-over-http-stable
+[jaeger_grpc]: https://www.jaegertracing.io/docs/latest/apis/#protobuf-via-grpc-stable
+[jaeger_udp]: https://www.jaegertracing.io/docs/latest/apis/#thrift-over-udp-stable
+[jaeger_collector]: https://www.jaegertracing.io/docs/latest/deployment/#collector
+[jaeger_agent]: https://www.jaegertracing.io/docs/latest/deployment/#agent
 
 ## Zipkin Exporter
 
@@ -181,11 +190,7 @@ The SDK MAY accept a comma-separated list to enable setting multiple exporters.
 Known values for `OTEL_TRACES_EXPORTER` are:
 
 - `"otlp"`: [OTLP](./protocol/otlp.md)
-- `"jaeger"`: export in Jaeger data model. If no additional configuration is
- provided the default protocol SHOULD be [Thrift over HTTP][jaeger_http] unless
- SDKs have good reasons to choose [gRPC][jaeger_grpc] as the default
- (e.g. for backward compatibility reasons when gRPC was already the default
- in a stable SDK release).
+- `"jaeger"`: export in Jaeger data model
 - `"zipkin"`: [Zipkin](https://zipkin.io/zipkin-api/) (Defaults to [protobuf](https:/openzipkin/zipkin-api/blob/master/zipkin.proto) format)
 - `"none"`: No automatically configured exporter for traces.
 
@@ -228,6 +233,3 @@ To ensure consistent naming across projects, this specification recommends that
 ```
 OTEL_{LANGUAGE}_{FEATURE}
 ```
-
-[jaeger_http]: https://www.jaegertracing.io/docs/latest/apis/#thrift-over-http-stable
-[jaeger_grpc]: https://www.jaegertracing.io/docs/latest/apis/#protobuf-via-grpc-stable