Update endpoint for OTLP/HTTP to allow scheme (#1234)

* Update endpoint for OTLP/HTTP to allow scheme * Update specification/protocol/exporter.md Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com> * add changelog * require schemed endpoints for OTLP/gRPC and OTLP/HTTP * document collector conventions for OTEL_EXPORTER_OTLP_ENDPOINT with OTLP/HTTP * fix endpoint default Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com> Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>
open-telemetry · Jan 14, 2021 · bab74e6 · bab74e6
1 parent 4de9921
commit bab74e6
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -37,6 +37,8 @@ Updates:
 - Add default ratio when TraceIdRatioSampler is specified by environment variable but
   no ratio is.
   ([#1322](https://github.com/open-telemetry/opentelemetry-specification/pull/1322))
+- Require schemed endpoints for OTLP exporters
+  ([1234](https://github.com/open-telemetry/opentelemetry-specification/pull/1234))
 
 ## v0.7.0 (11-18-2020)
 

diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md
@@ -8,10 +8,9 @@ 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. This MAY be configured to include a path (e.g. `example.com/v1/traces`). | `localhost:4317` | `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_SPAN_ENDPOINT` `OTEL_EXPORTER_OTLP_METRIC_ENDPOINT` |
+| 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_SPAN_ENDPOINT` `OTEL_EXPORTER_OTLP_METRIC_ENDPOINT` |
 | Protocol             | The protocol used to transmit the data. One of `grpc`,`http/json`,`http/protobuf`. | `grpc`               | `OTEL_EXPORTER_OTLP_PROTOCOL` `OTEL_EXPORTER_OTLP_SPAN_PROTOCOL` `OTEL_EXPORTER_OTLP_METRIC_PROTOCOL` |
-| Insecure             | Whether to enable client transport security for the exporter's `grpc` or `http` connection. | `false`           | `OTEL_EXPORTER_OTLP_INSECURE` `OTEL_EXPORTER_OTLP_SPAN_INSECURE` `OTEL_EXPORTER_OTLP_METRIC_INSECURE` |
-| Certificate File     | Path to certificate file for TLS credentials of gRPC client. Should only be used if `insecure` is set to `false`. | n/a               | `OTEL_EXPORTER_OTLP_CERTIFICATE` `OTEL_EXPORTER_OTLP_SPAN_CERTIFICATE` `OTEL_EXPORTER_OTLP_METRIC_CERTIFICATE` |
+| 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_SPAN_CERTIFICATE` `OTEL_EXPORTER_OTLP_METRIC_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_SPAN_HEADERS` `OTEL_EXPORTER_OTLP_METRIC_HEADERS` |
 | Compression          | Compression key for supported compression types. Supported compression: `gzip`| No value              | `OTEL_EXPORTER_OTLP_COMPRESSION` `OTEL_EXPORTER_OTLP_SPAN_COMPRESSION` `OTEL_EXPORTER_OTLP_METRIC_COMPRESSION` |
 | Timeout              | Max waiting time for the backend to process each spans or metrics batch. | 10s               | `OTEL_EXPORTER_OTLP_TIMEOUT` `OTEL_EXPORTER_OTLP_SPAN_TIMEOUT` `OTEL_EXPORTER_OTLP_METRIC_TIMEOUT` |
@@ -26,7 +25,7 @@ Example 1
 The following configuration sends all signals to the same collector:
 
 ```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT=collector:4317
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
 export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
 ```
 
@@ -35,24 +34,23 @@ Example 2
 Traces and metrics are sent to different collectors using different protocols:
 
 ```bash
-export OTEL_EXPORTER_OTLP_SPAN_ENDPOINT=collector:4317
+export OTEL_EXPORTER_OTLP_SPAN_ENDPOINT=http://collector:4317
 export OTEL_EXPORTER_OTLP_SPAN_PROTOCOL=grpc
-export OTEL_EXPORTER_OTLP_SPAN_INSECURE=true
 
-export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=collector.example.com/v1/metrics
-export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http
+export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example.com/v1/metrics
+export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
 ```
 
 Example 3
 
 Traces are configured using the generic configuration, metrics are configured using specific configuration:
 
 ```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT=collector:4317
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
 export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
 
-export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=collector.example.com/v1/metrics
-export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http
+export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://collector.example.com/v1/metrics
+export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json
 ```
 
 ### Specifying headers via environment variables
@@ -85,3 +83,5 @@ Transient errors are errors which expect the backend to recover. The following s
 | 16 | Unauthenticated |
 
 Additional details on transient errors can be found in [otep-35](https://github.com/open-telemetry/oteps/blob/master/text/0035-opentelemetry-protocol.md#export-response) for gRPC and [otep-99](https://github.com/open-telemetry/oteps/blob/master/text/0099-otlp-http.md#failures) for HTTP
+
+[otlphttp-req]: otlp.md#otlphttp-request