From 6a30cf2db8808ffc1751b68287e1d03a2df77906 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 20 Jan 2021 12:24:53 -0500 Subject: [PATCH 1/5] OAdapt #1340 for 1.0 of Trace. - Ensure environment variables have consistent names - Update documentation to leave format UNSPECIFIED in 1.0 with an allowance to add config later. --- specification/protocol/exporter.md | 15 ++++++++++++++- specification/sdk-environment-variables.md | 11 +++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index a4cc39a38d1..d3e603fc8cb 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -9,7 +9,6 @@ The following configuration options MUST be available to configure the OTLP expo | Configuration Option | Description | Default | Env variable | | -------------------- | ------------------------------------------------------------ | ----------------- | ------------------------------------------------------------ | | Endpoint | Target to which the exporter is going to send spans or metrics. The endpoint MUST be a valid URL with scheme (http or https) and host, and MAY contain a port and path. A scheme of https indicates a secure connection. When using `OTEL_EXPORTER_ENDPOINT` with OTLP/HTTP, exporters SHOULD follow the collector convention of appending the version and signal to the path (e.g. `v1/traces` or `v1/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:4317` | `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | -| Protocol | The protocol used to transmit the data. One of `grpc`,`http/json`,`http/protobuf`. | `grpc` | `OTEL_EXPORTER_OTLP_PROTOCOL` `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | | Certificate File | Path to certificate file for TLS credentials of gRPC client. Should only be used for a secure connection. | n/a | `OTEL_EXPORTER_OTLP_CERTIFICATE` `OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE` `OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE` | | Headers | Key-value pairs to be used as headers associated with gRPC or HTTP requests. See [Specifying headers](./exporter.md#specifying-headers-via-environment-variables) for more details. | n/a | `OTEL_EXPORTER_OTLP_HEADERS` `OTEL_EXPORTER_OTLP_TRACES_HEADERS` `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | | Compression | Compression key for supported compression types. Supported compression: `gzip`| No value | `OTEL_EXPORTER_OTLP_COMPRESSION` `OTEL_EXPORTER_OTLP_TRACES_COMPRESSION` `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION` | @@ -53,6 +52,20 @@ export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://collector.example.com/v1/metri export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json ``` +### Specify Protocol + +Currently, OTLP haas more than one transport protocol it can support, e.g. +`grpc`, `http/json`, `http/protobuf`. As of 1.0 of the specification, there +*is no specified default, or configuration via environment variables*. We +reserve the following environment variables for configuration of protocols in +the future: + +- `OTEL_EXPORTER_OTLP_PROTOCOL` +- `OTEL_EXPORTER_OTLP_SPAN_PROTOCOL` +- `OTEL_EXPORTER_OTLP_METRIC_PROTOCOL` + +SDKs are free to choose a 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_HEADERS` environment 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](https://github.com/w3c/baggage/blob/master/baggage/HTTP_HEADER_FORMAT.md), except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings. diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 96dc542996b..8fa8769b66f 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -91,6 +91,17 @@ See [OpenTelemetry Protocol Exporter Configuration Options](./protocol/exporter. | ----------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | OTEL_EXPORTER_ZIPKIN_ENDPOINT | Endpoint for Zipkin traces | "http://localhost:9411/api/v2/spans" | +Addtionally, the following environment variables are reserved for future +usage in Zipkin Exporter configuration: + +- `OTEL_EXPORTER_ZIPKIN_PROTOCOL` + +This will be used to specify whether or not the exporter uses v1 or v2, json, +thrift or protobuf. As of 1.0 of the specification, there +*is no specified default, or configuration via environment variables*. + + + ## Prometheus Exporter | Name | Description | Default | From c664bf42228c794e2832e47da23e32e1a1d4b573 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 20 Jan 2021 12:29:40 -0500 Subject: [PATCH 2/5] Fix formatting. --- specification/protocol/exporter.md | 4 ++-- specification/sdk-environment-variables.md | 4 +--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index d3e603fc8cb..6a9ce3cc9db 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -54,8 +54,8 @@ export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json ### Specify Protocol -Currently, OTLP haas more than one transport protocol it can support, e.g. -`grpc`, `http/json`, `http/protobuf`. As of 1.0 of the specification, there +Currently, OTLP haas more than one transport protocol it can support, e.g. +`grpc`, `http/json`, `http/protobuf`. As of 1.0 of the specification, there *is no specified default, or configuration via environment variables*. We reserve the following environment variables for configuration of protocols in the future: diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 8fa8769b66f..120f105df14 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -97,11 +97,9 @@ usage in Zipkin Exporter configuration: - `OTEL_EXPORTER_ZIPKIN_PROTOCOL` This will be used to specify whether or not the exporter uses v1 or v2, json, -thrift or protobuf. As of 1.0 of the specification, there +thrift or protobuf. As of 1.0 of the specification, there *is no specified default, or configuration via environment variables*. - - ## Prometheus Exporter | Name | Description | Default | From 2fbe2a2fb51e75f32ed8bdf33bab153776264d90 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 21 Jan 2021 13:54:53 -0500 Subject: [PATCH 3/5] Update specification/protocol/exporter.md Co-authored-by: Anuraag Agrawal --- specification/protocol/exporter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 6a9ce3cc9db..8bcdb0813f9 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -54,7 +54,7 @@ export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json ### Specify Protocol -Currently, OTLP haas more than one transport protocol it can support, e.g. +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, there *is no specified default, or configuration via environment variables*. We reserve the following environment variables for configuration of protocols in From 67d9ecb1a01b4b0e8e6545607211aa3b9f8601d7 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 25 Jan 2021 12:37:41 -0500 Subject: [PATCH 4/5] Update specification/protocol/exporter.md Co-authored-by: Bartlomiej Obecny --- specification/protocol/exporter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 8bcdb0813f9..a6809ba0a2f 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -61,7 +61,7 @@ reserve the following environment variables for configuration of protocols in the future: - `OTEL_EXPORTER_OTLP_PROTOCOL` -- `OTEL_EXPORTER_OTLP_SPAN_PROTOCOL` +- `OTEL_EXPORTER_OTLP_TRACE_PROTOCOL` - `OTEL_EXPORTER_OTLP_METRIC_PROTOCOL` SDKs are free to choose a default, if no configuration is provided. From c17e3247c5ab813ad77860681b7694cec13e44b2 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 28 Jan 2021 15:39:24 -0500 Subject: [PATCH 5/5] Fixes from review. --- specification/protocol/exporter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index a6809ba0a2f..9f43e197c0b 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -64,7 +64,7 @@ the future: - `OTEL_EXPORTER_OTLP_TRACE_PROTOCOL` - `OTEL_EXPORTER_OTLP_METRIC_PROTOCOL` -SDKs are free to choose a default, if no configuration is provided. +SDKs have an unspecified default, if no configuration is provided. ### Specifying headers via environment variables