From a683ed7daf0639ccc40fa3e896828b8837ecc566 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Thu, 13 Aug 2020 10:43:02 -0500 Subject: [PATCH 1/5] Allow specifying a single configuration The following change describes that the OTLP exporter must support configuration for all signals via a single set of configuration options. There is also an example for configuring different signals with different endpoints via environment variables. --- specification/trace/sdk_exporters/otlp.md | 40 ++++++++++++++++++----- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/specification/trace/sdk_exporters/otlp.md b/specification/trace/sdk_exporters/otlp.md index fd55e867430..3189632027b 100644 --- a/specification/trace/sdk_exporters/otlp.md +++ b/specification/trace/sdk_exporters/otlp.md @@ -1,20 +1,42 @@ # OpenTelemetry Protocol Exporter -This document specifies the configuration options available to the OpenTelemetry Protocol ([OTLP](https://github.com/open-telemetry/oteps/blob/master/text/0035-opentelemetry-protocol.md)) `SpanExporter` and `MetricsExporter` as well as the retry behavior. +This document specifies the configuration options available to the OpenTelemetry Protocol ([OTLP](https://github.com/open-telemetry/oteps/blob/master/text/0035-opentelemetry-protocol.md)) Exporter as well as the retry behavior. ## Configuration Options -The configuration options are configurable separately for the `SpanExporter` and the `MetricsExporter`. +The following configuration options MUST be available to configure the OTLP exporter. Each configuration option MUST be overridable by a signal specific option. | 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:55680` | `OTEL_EXPORTER_OTLP_SPAN_ENDPOINT` `OTEL_EXPORTER_OTLP_METRIC_ENDPOINT` | -| Protocol | The protocol used to transmit the data. One of `grpc`,`http/json`,`http/proto`. | `grpc` | `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_SPAN_INSECURE` `OTEL_EXPORTER_OTLP_METRIC_INSECURE` | -| Certificate File | Certificate file for TLS credentials of gRPC client. Should only be used if `insecure` is set to `false`. | n/a | `OTEL_EXPORTER_OTLP_SPAN_CERTIFICATE` `OTEL_EXPORTER_OTLP_METRIC_CERTIFICATE` | -| Headers | The headers associated with gRPC or HTTP requests. | n/a | `OTEL_EXPORTER_OTLP_SPAN_HEADERS` `OTEL_EXPORTER_OTLP_METRIC_HEADERS` | -| Compression | Compression key for supported compression types. Supported compression: `gzip`| no 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. | 60s | `OTEL_EXPORTER_OTLP_SPAN_TIMEOUT` `OTEL_EXPORTER_OTLP_METRIC_TIMEOUT` | +| 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:55680` | `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/proto`. | `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 | 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` | +| Headers | The headers associated with gRPC or HTTP requests. | 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 compression | `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. | 60s | `OTEL_EXPORTER_OTLP_TIMEOUT` `OTEL_EXPORTER_OTLP_SPAN_TIMEOUT` `OTEL_EXPORTER_OTLP_METRIC_TIMEOUT` | + +Example 1 + +The following configuration sends all signals to the same collector: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=collector:55680 +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc +``` + +Example 2 + +Traces and metrics are sent to different collectors using different protocols: + +```bash +export OTEL_EXPORTER_OTLP_SPAN_ENDPOINT=collector:55680 +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 +``` ## Retry From c9d29328d79176f4f78b842f9331c58c169cd13f Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Tue, 18 Aug 2020 11:55:50 -0500 Subject: [PATCH 2/5] adding a third example --- specification/trace/sdk_exporters/otlp.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/specification/trace/sdk_exporters/otlp.md b/specification/trace/sdk_exporters/otlp.md index 3189632027b..7e2cb7c1ea8 100644 --- a/specification/trace/sdk_exporters/otlp.md +++ b/specification/trace/sdk_exporters/otlp.md @@ -38,6 +38,18 @@ export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=collector.example.com/v1/metrics export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http ``` +Example 3 + +Traces are configured using the generic configuration, metrics are configured using specific configuration: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=collector:55680 +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc + +export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=collector.example.com/v1/metrics +export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http +``` + ## Retry [Transient errors](#transient-errors) MUST be handled with a retry strategy. This retry strategy MUST implement an exponential back-off with jitter to avoid overwhelming the destination until the network is restored or the destination has recovered. From b22080658a3da367b7c54ed097a56a2fd53cb993 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Tue, 18 Aug 2020 12:33:55 -0500 Subject: [PATCH 3/5] moving otlp exporter into protocol directory --- .../{trace/sdk_exporters/otlp.md => protocol/exporter.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename specification/{trace/sdk_exporters/otlp.md => protocol/exporter.md} (100%) diff --git a/specification/trace/sdk_exporters/otlp.md b/specification/protocol/exporter.md similarity index 100% rename from specification/trace/sdk_exporters/otlp.md rename to specification/protocol/exporter.md From b74137f5136c001e61adb445a5e6562f087422d5 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Tue, 18 Aug 2020 15:59:07 -0500 Subject: [PATCH 4/5] add link to exporter from readme --- specification/protocol/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/protocol/README.md b/specification/protocol/README.md index d0357ccdbc1..8d8be4d35bd 100644 --- a/specification/protocol/README.md +++ b/specification/protocol/README.md @@ -5,3 +5,4 @@ This is the specification of new OpenTelemetry protocol (OTLP). - [Design Goals](design-goals.md). - [Requirements](requirements.md). - [Specification](otlp.md). +- [Exporter](exporter.md). From e5c1da227cab18f1510c44942245822ecdd4514f Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 19 Aug 2020 09:28:19 -0500 Subject: [PATCH 5/5] apply review feedback --- specification/protocol/README.md | 2 +- specification/protocol/exporter.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/protocol/README.md b/specification/protocol/README.md index 8d8be4d35bd..2d7ecec9449 100644 --- a/specification/protocol/README.md +++ b/specification/protocol/README.md @@ -5,4 +5,4 @@ This is the specification of new OpenTelemetry protocol (OTLP). - [Design Goals](design-goals.md). - [Requirements](requirements.md). - [Specification](otlp.md). -- [Exporter](exporter.md). +- [SDK Exporter](exporter.md). diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 7e2cb7c1ea8..65f5c3f5e3e 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -14,7 +14,7 @@ The following configuration options MUST be available to configure the OTLP expo | Certificate File | 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` | | Headers | The headers associated with gRPC or HTTP requests. | 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 compression | `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. | 60s | `OTEL_EXPORTER_OTLP_TIMEOUT` `OTEL_EXPORTER_OTLP_SPAN_TIMEOUT` `OTEL_EXPORTER_OTLP_METRIC_TIMEOUT` | +| 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` | Example 1