From f7c242c08a8d95ee5c0752f05077abb9a9808c12 Mon Sep 17 00:00:00 2001 From: Patrik Dudits Date: Mon, 22 Jan 2024 14:53:43 +0100 Subject: [PATCH] Mark support for signal-level OTLP exporter settings optional --- spec/src/main/asciidoc/configuration.adoc | 142 ++++++++++++---------- 1 file changed, 77 insertions(+), 65 deletions(-) diff --git a/spec/src/main/asciidoc/configuration.adoc b/spec/src/main/asciidoc/configuration.adoc index 307e946e..1a312762 100644 --- a/spec/src/main/asciidoc/configuration.adoc +++ b/spec/src/main/asciidoc/configuration.adoc @@ -23,7 +23,7 @@ OpenTelemetry MUST be configured by MicroProfile Config following the semantics of configuration properties detailed in https://github.com/open-telemetry/opentelemetry-java/tree/v{otel-java-version}/sdk-extensions/autoconfigure[OpenTelemetry SDK Autoconfigure {otel-java-version}]. Following properties MUST be supported: -=== Configuration Properties +=== Required Configuration Properties // Table with property name, default value and description [options="header"] |=== @@ -119,6 +119,82 @@ Options include grpc and http/protobuf. Default value: `grpc` +| `otel.exporter.otlp.endpoint` +| The OTLP traces, metrics, and logs endpoint to connect to. +MUST be a URL with a scheme of either http or https based on the use of TLS. +If protocol is http/protobuf the version and signal will be appended to the path (e.g. v1/traces, v1/metrics, or v1/logs) + +Default value: `http://localhost:4317` when protocol is `grpc`, `http://localhost:4318/v1/\{signal}` when protocol is `http/protobuf` + +| `otel.exporter.otlp.certificate` +| The path to the file containing trusted certificates to use when verifying an OTLP trace, metric, or log server's TLS credentials. +The file SHOULD contain one or more X.509 certificates in PEM format. + +By default the host platform's trusted root certificates are used. + +| `otel.exporter.otlp.client.key` +| The path to the file containing private client key to use when verifying an OTLP trace, metric, or log client's TLS credentials. +The file SHOULD contain one private key PKCS8 PEM format. + +By default no client key is used. + +| `otel.exporter.otlp.client.certificate` +| The path to the file containing trusted certificates to use when verifying an OTLP trace, metric, or log client's TLS credentials. +The file SHOULD contain one or more X.509 certificates in PEM format. +By default no chain file is used. + +| `otel.exporter.otlp.headers` +| Key-value pairs separated by commas to pass as request headers on OTLP trace, metric, and log requests. + +| `otel.exporter.otlp.compression` +| The compression type to use on OTLP trace, metric, and log requests. +Options include `gzip`. + +By default no compression will be used. + +| `otel.exporter.otlp.timeout` +| The maximum waiting time, in milliseconds, allowed to send each OTLP trace, metric, and log batch. + +Default value: `10000` + +| `otel.exporter.otlp.metrics.temporality.preference` +a| The preferred output aggregation temporality. + +* `CUMULATIVE`: all instruments will have cumulative temporality. +* `DELTA`: counter (sync and async) and histograms will be delta, up down counters (sync and async) will be cumulative. +* `LOWMEMORY`: sync counter and histograms will be delta, async counter and up down counters (sync and async) will be cumulative. + +Default value: `CUMULATIVE`. + +| `otel.exporter.otlp.metrics.default.histogram.aggregation` +| The preferred default histogram aggregation. +Options include `BASE2_EXPONENTIAL_BUCKET_HISTOGRAM` and `EXPLICIT_BUCKET_HISTOGRAM`. + +Default value: `EXPLICIT_BUCKET_HISTOGRAM`. + +| `otel.metrics.exemplar.filter` +| The filter for exemplar sampling. Can be `ALWAYS_OFF`, `ALWAYS_ON` or `TRACE_BASED`. + +Default value: `TRACE_BASED` + +| `otel.metric.export.interval` +| The interval, in milliseconds, between the start of two export attempts. + +Default value: `60000` +|=== + +If Environment Config Source is enabled for MicroProfile Config, then the environment variables as described by the OpenTelemetry SDK Autoconfigure are also supported. + +=== Optional Configuration Properties + +An implementation MAY support additional configuration properties. Notable examples include per-signal configuration of exporters: + +[options="header"] +|=== +|Property Name |Description + +2+h| OTLP Exporter + | `otel.exporter.otlp.traces.protocol` | The transport protocol to use on OTLP trace requests. Options include grpc and http/protobuf. @@ -131,13 +207,6 @@ Options include grpc and http/protobuf. Default value: `grpc` -| `otel.exporter.otlp.endpoint` -| The OTLP traces, metrics, and logs endpoint to connect to. -MUST be a URL with a scheme of either http or https based on the use of TLS. -If protocol is http/protobuf the version and signal will be appended to the path (e.g. v1/traces, v1/metrics, or v1/logs) - -Default value: `http://localhost:4317` when protocol is `grpc`, `http://localhost:4318/v1/\{signal}` when protocol is `http/protobuf` - | `otel.exporter.otlp.traces.endpoint` | The OTLP traces endpoint to connect to. MUST be a URL with a scheme of either http or https based on the use of TLS. @@ -150,12 +219,6 @@ MUST be a URL with a scheme of either http or https based on the use of TLS. Default value: `http://localhost:4317` when protocol is `grpc`, and `http://localhost:4318/v1/metrics` when protocol is `http/protobuf` -| `otel.exporter.otlp.certificate` -| The path to the file containing trusted certificates to use when verifying an OTLP trace, metric, or log server's TLS credentials. -The file SHOULD contain one or more X.509 certificates in PEM format. - -By default the host platform's trusted root certificates are used. - | `otel.exporter.otlp.traces.certificate` | The path to the file containing trusted certificates to use when verifying an OTLP trace server's TLS credentials. The file SHOULD contain one or more X.509 certificates in PEM format. @@ -168,12 +231,6 @@ The file SHOULD contain one or more X.509 certificates in PEM format. By default the host platform's trusted root certificates are used. -| `otel.exporter.otlp.client.key` -| The path to the file containing private client key to use when verifying an OTLP trace, metric, or log client's TLS credentials. -The file SHOULD contain one private key PKCS8 PEM format. - -By default no client key is used. - | `otel.exporter.otlp.traces.client.key` | The path to the file containing private client key to use when verifying an OTLP trace client's TLS credentials. The file SHOULD contain one private key PKCS8 PEM format. @@ -186,11 +243,6 @@ The file SHOULD contain one private key PKCS8 PEM format. By default no client key file is used. -| `otel.exporter.otlp.client.certificate` -| The path to the file containing trusted certificates to use when verifying an OTLP trace, metric, or log client's TLS credentials. -The file SHOULD contain one or more X.509 certificates in PEM format. -By default no chain file is used. - | `otel.exporter.otlp.traces.client.certificate` | The path to the file containing trusted certificates to use when verifying an OTLP trace server's TLS credentials. The file SHOULD contain one or more X.509 certificates in PEM format. @@ -203,21 +255,12 @@ The file SHOULD contain one or more X.509 certificates in PEM format. By default no chain file is used. -| `otel.exporter.otlp.headers` -| Key-value pairs separated by commas to pass as request headers on OTLP trace, metric, and log requests. - | `otel.exporter.otlp.traces.headers` | Key-value pairs separated by commas to pass as request headers on OTLP trace requests. | `otel.exporter.otlp.metrics.headers` | Key-value pairs separated by commas to pass as request headers on OTLP metric requests. -| `otel.exporter.otlp.compression` -| The compression type to use on OTLP trace, metric, and log requests. -Options include `gzip`. - -By default no compression will be used. - | `otel.exporter.otlp.traces.compression` | The compression type to use on OTLP trace requests. Options include `gzip`. @@ -230,11 +273,6 @@ Options include `gzip`. By default no compression will be used. -| `otel.exporter.otlp.timeout` -| The maximum waiting time, in milliseconds, allowed to send each OTLP trace, metric, and log batch. - -Default value: `10000` - | `otel.exporter.otlp.traces.timeout` | The maximum waiting time, in milliseconds, allowed to send each OTLP trace batch. @@ -245,34 +283,8 @@ Default value: `10000` Default value: `10000` -| `otel.exporter.otlp.metrics.temporality.preference` -a| The preferred output aggregation temporality. - -* `CUMULATIVE`: all instruments will have cumulative temporality. -* `DELTA`: counter (sync and async) and histograms will be delta, up down counters (sync and async) will be cumulative. -* `LOWMEMORY`: sync counter and histograms will be delta, async counter and up down counters (sync and async) will be cumulative. - -Default value: `CUMULATIVE`. - -| `otel.exporter.otlp.metrics.default.histogram.aggregation` -| The preferred default histogram aggregation. -Options include `BASE2_EXPONENTIAL_BUCKET_HISTOGRAM` and `EXPLICIT_BUCKET_HISTOGRAM`. - -Default value: `EXPLICIT_BUCKET_HISTOGRAM`. - -| `otel.metrics.exemplar.filter` -| The filter for exemplar sampling. Can be `ALWAYS_OFF`, `ALWAYS_ON` or `TRACE_BASED`. - -Default value: `TRACE_BASED` - -| `otel.metric.export.interval` -| The interval, in milliseconds, between the start of two export attempts. - -Default value: `60000` |=== -If Environment Config Source is enabled for MicroProfile Config, then the environment variables as described by the OpenTelemetry SDK Autoconfigure are also supported. - [[sec:service-loader-support]] === Service Loader Support