From ccd36cf1e102b8d34eae8d77fd64482eca1fb433 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 28 Nov 2023 16:55:29 +0100 Subject: [PATCH] Clarify OTLP/HTTP endpoint configuration option handling (#3739) 1. The specification should define how the configuration options should handle the value. We cannot force the user to not set an env var value. 2. Changed `endpoint` to `option` to make it more clear that the specification says how the configuration option should work. 3. Initially I thought about defining `MUST not accept a path that contains other parts` (instead of `MAY`), but I have not found any OTLP exporter that makes such a detailed validation ([Java](https://github.com/open-telemetry/opentelemetry-java/blob/main/exporters/common/src/main/java/io/opentelemetry/exporter/internal/ExporterBuilderUtil.java), [.NET](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/OtlpExporterOptions.cs), [Python](https://github.com/open-telemetry/opentelemetry-python/blob/main/exporter/opentelemetry-exporter-otlp-proto-http/src/opentelemetry/exporter/otlp/proto/http/trace_exporter/__init__.py)). _I was even considering to remove this statement, but I feel that it may be a too drastic change._ --- CHANGELOG.md | 3 +++ specification/protocol/exporter.md | 14 ++++++++++++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e206011501..a2948386a81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,9 @@ release. ### OpenTelemetry Protocol +- Clarify HTTP endpoint configuration option handling. + ([#3739](https://github.com/open-telemetry/opentelemetry-specification/pull/3739)) + ### Compatibility ### SDK Configuration diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 32c8bc5c69e..22cf934c613 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -13,11 +13,21 @@ This document specifies the configuration options available to the OpenTelemetry The following configuration options MUST be available to configure the OTLP exporter. Each configuration option MUST be overridable by a signal specific option. -- **Endpoint (OTLP/HTTP)**: Target URL to which the exporter is going to send spans, metrics, or logs. The endpoint MUST be a valid URL with scheme (http or https) and host, MAY contain a port, SHOULD contain a path and MUST NOT contain other parts (such as query string or fragment). A scheme of https indicates a secure connection. When using `OTEL_EXPORTER_OTLP_ENDPOINT`, exporters MUST construct per-signal URLs as [described below](#endpoint-urls-for-otlphttp). The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the [OTLP Specification][otlphttp-req] for more details. +- **Endpoint (OTLP/HTTP)**: Target URL to which the exporter is going to send spans, metrics, or logs. + The implementation MUST honor the following [URL components](https://datatracker.ietf.org/doc/html/rfc3986#section-3): + - scheme (`http` or `https`) + - host + - port + - path + + The implementation MAY ignore all other URL components. + + A scheme of `https` indicates a secure connection. + When using `OTEL_EXPORTER_OTLP_ENDPOINT`, exporters MUST construct per-signal URLs as [described below](#endpoint-urls-for-otlphttp). The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the [OTLP Specification][otlphttp-req] for more details. - Default: `http://localhost:4318` [1] - Env vars: `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` -- **Endpoint (OTLP/gRPC)**: Target to which the exporter is going to send spans, metrics, or logs. The endpoint SHOULD accept any form allowed by the underlying gRPC client implementation. Additionally, the endpoint MUST accept a URL with a scheme of either `http` or `https`. A scheme of `https` indicates a secure connection and takes precedence over the `insecure` configuration setting. A scheme of `http` indicates an insecure connection and takes precedence over the `insecure` configuration setting. If the gRPC client implementation does not support an endpoint with a scheme of `http` or `https` then the endpoint SHOULD be transformed to the most sensible format for that implementation. +- **Endpoint (OTLP/gRPC)**: Target to which the exporter is going to send spans, metrics, or logs. The option SHOULD accept any form allowed by the underlying gRPC client implementation. Additionally, the option MUST accept a URL with a scheme of either `http` or `https`. A scheme of `https` indicates a secure connection and takes precedence over the `insecure` configuration setting. A scheme of `http` indicates an insecure connection and takes precedence over the `insecure` configuration setting. If the gRPC client implementation does not support an endpoint with a scheme of `http` or `https` then the endpoint SHOULD be transformed to the most sensible format for that implementation. - Default: `http://localhost:4317` [1] - Env vars: `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`