From 908eb79378372b09391817cbb78072afd8db1a0c Mon Sep 17 00:00:00 2001 From: Patrik Dudits Date: Wed, 13 Dec 2023 16:56:52 +0100 Subject: [PATCH 1/5] Specification of Telemetry Metrics API requirements --- spec/src/main/asciidoc/configuration.adoc | 307 ++++++++++++++++++ spec/src/main/asciidoc/integration.adoc | 79 +++++ spec/src/main/asciidoc/metrics.adoc | 17 +- .../microprofile-telemetry-spec.asciidoc | 3 + .../src/main/asciidoc/opentelemetry-apis.adoc | 90 +++++ spec/src/main/asciidoc/tracing.adoc | 288 +--------------- 6 files changed, 483 insertions(+), 301 deletions(-) create mode 100644 spec/src/main/asciidoc/configuration.adoc create mode 100644 spec/src/main/asciidoc/integration.adoc create mode 100644 spec/src/main/asciidoc/opentelemetry-apis.adoc diff --git a/spec/src/main/asciidoc/configuration.adoc b/spec/src/main/asciidoc/configuration.adoc new file mode 100644 index 00000000..307e946e --- /dev/null +++ b/spec/src/main/asciidoc/configuration.adoc @@ -0,0 +1,307 @@ +// +// Copyright (c) 2023 Contributors to the Eclipse Foundation +// +// See the NOTICE file(s) distributed with this work for additional +// information regarding copyright ownership. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +[[sec:configuration-properties]] +== Configuration + +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 +// Table with property name, default value and description +[options="header"] +|=== +|Property Name |Description + +// sub-section, colspan=3 +2+h| Global Configuration + +|`otel.sdk.disabled` +| Set to `false` to enable OpenTelemetry. + +Default value: `true` +2+h| Exporters configuration + +|`otel.traces.exporter` +| List of exporters to be used for tracing, separated by commas. +`none` means no autoconfigured exporter. +Values other than `none` and `otlp` might link:#sec:service-loader-support[require additional libraries] + +Default value: `otlp` + +|`otel.metrics.exporter` +| List of exporters to be used for metrics, separated by commas. +Values other than `none` and `otlp` might link:#sec:service-loader-support[require additional libraries] + +Default value: `otlp` + +| `otel.propagators` +| The propagators to be used. +Values other than `none`, `tracecontext` and `baggage` might link:#sec:service-loader-support[require additional libraries] + +Default value: `tracecontext, baggage` + +2+h| Resource attributes + +| `otel.resource.attributes` +| Specify resource attributes in the following format: `key1=val1, key2=val2, key3=val3` + +| `otel.service.name` +| Specify logical service name. +Takes precedence over `service.name` defined with `otel.resource.attributes` + +Default value: application name (if applicable) + +2+h| Batch Span Processor + +| `otel.bsp.schedule.delay` +| The interval, in milliseconds, between two consecutive exports. + +Default value: `5000` + +| `otel.bsp.max.queue.size` +| The maximum queue size. + +Default value: `2048` + +| `otel.bsp.max.export.batch.size` +| The maximum batch size. + +Default value: `512` + +| `otel.bsp.export.timeout` +| The maximum allowed time, in milliseconds, to export data. + +Default value: `30000` + +2+h| Sampler + +| `otel.traces.sampler` +a| The sampler to use for tracing. +Supported values are: + +* `always_on` +* `always_off` +* `traceidratio` +* `parentbased_always_on` +* `parentbased_always_off` +* `parentbased_traceidratio` + +Support for other samplers might be added with link:#sec:service-loader-support[additional libraries] + +Default value: `parentbased_always_on` + +| `otel.traces.sampler.arg` +| An argument to the configured tracer if supported, for example a ratio. +Consult OpenTelemetry documentation for details. + +2+h| OTLP Exporter + +| `otel.exporter.otlp.protocol` +| The transport protocol to use on OTLP trace, metric, and log requests. +Options include grpc and http/protobuf. + +Default value: `grpc` + +| `otel.exporter.otlp.traces.protocol` +| The transport protocol to use on OTLP trace requests. +Options include grpc and http/protobuf. + +Default value: `grpc` + +| `otel.exporter.otlp.metrics.protocol` +| The transport protocol to use on OTLP metric requests. +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. + +Default value: `http://localhost:4317` when protocol is `grpc`, and `http://localhost:4318/v1/traces` when protocol is `http/protobuf` + +| `otel.exporter.otlp.metrics.endpoint` +| The OTLP metrics endpoint to connect to. +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. + +By default the host platform's trusted root certificates are used. + +| `otel.exporter.otlp.metrics.certificate` +| The path to the file containing trusted certificates to use when verifying an OTLP metric 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.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. + +By default no client key file is used. + +| `otel.exporter.otlp.metrics.client.key` +| The path to the file containing private client key to use when verifying an OTLP metric client's TLS credentials. +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. + +By default no chain file is used. + +| `otel.exporter.otlp.metrics.client.certificate` +| The path to the file containing trusted certificates to use when verifying an OTLP metric server'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.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`. + +By default no compression will be used. + +| `otel.exporter.otlp.metrics.compression` +| The compression type to use on OTLP metric 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.traces.timeout` +| The maximum waiting time, in milliseconds, allowed to send each OTLP trace batch. + +Default value: `10000` + +| `otel.exporter.otlp.metrics.timeout` +| The maximum waiting time, in milliseconds, allowed to send each OTLP metric 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. + +[[sec:service-loader-support]] +=== Service Loader Support + +Implementation will load additional configuration related components by means of service loader. +This allows the application to define its own metadata and trace handling behavior. +The following components are supported + +[options=header] +|=== +| Component interface | Purpose + +| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/ConfigurablePropagatorProvider.html[`ConfigurablePropagatorProvider`] +| Provides implementation for a name referred in `otel.propagators` + +| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/traces/ConfigurableSpanExporterProvider.html[`ConfigurableSpanExporterProvider`] +| Provides implementation for a name referred in `otel.traces.exporter` + +| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/traces/ConfigurableSamplerProvider.html[`ConfigurableSamplerProvider`] +| Provides implementation for a name referred in `otel.traces.sampler` + +| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/AutoConfigurationCustomizerProvider.html[`AutoConfigurationCustomizerProvider`] +| Customizes configuration properties before they are applied to the SDK + +| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/ResourceProvider.html[`ResourceProvider`] +| Defines resource attributes describing the application + +| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/metrics/ConfigurableMetricExporterProvider.html[`ConfigurableMetricExporterProvider`] +| Provides implementation for a name referred in `otel.metrics.exporter` +|=== + +Behavior when multiple implementations are found for a given component name is undefined. +Behavior when customizer changes other properties than those listed in the spec is also undefined. \ No newline at end of file diff --git a/spec/src/main/asciidoc/integration.adoc b/spec/src/main/asciidoc/integration.adoc new file mode 100644 index 00000000..73b44a17 --- /dev/null +++ b/spec/src/main/asciidoc/integration.adoc @@ -0,0 +1,79 @@ +// +// Copyright (c) 2023 Contributors to the Eclipse Foundation +// +// See the NOTICE file(s) distributed with this work for additional +// information regarding copyright ownership. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +== SDK integration + +Implementations SHALL provide integration by appropriately configuring compatible OpenTelemetry SDK for application runtime. +Regardless of signal type being considered -- traces or metrics -- following requirements SHALL be met: + +[[sec:enabling-opentelemetry-support]] +=== Enabling OpenTelemetry support +By default, MicroProfile Telemetry is deactivated. + +In order to enable any of aspects of integration, the configuration `otel.sdk.disabled=false` MUST be specified in any of the configuration sources available via MicroProfile Config. + +[IMPORTANT] +===== +This is a deviation from the OpenTelemetry Specification that specifies this configuration property officially, where https://opentelemetry.io[OpenTelemetry] is activated by default! + +But in fact, it will be activated only by adding its dependency to the application or platform project. +To be able to add MicroProfile Telemetry to MicroProfile implementations by default without side effects, this deviating behaviour has been defined here (see also <>). +===== + +This property is read once when the application is starting. +Any changes afterwards will not take effect unless the application is restarted. + +=== Configuration + +OpenTelemetry MUST be configured by MicroProfile Config following the semantics of configuration properties of link:https://github.com/open-telemetry/opentelemetry-java/tree/v{otel-java-version}/sdk-extensions/autoconfigure[OpenTelemetry SDK Autoconfigure extension]. + +Full list of required configuration property names are listed in <>. + +==== OTLP support + +OpenTelemetry data can be exported in various ways. +Implementation MUST support exporting data via OTLP protocol and relevant configuration properties for OTLP exporter. + +==== Service Providers support + +Additional OpenTelemetry SDK components can be integrated by means of Java Service Loader mechanism. + +Full list of supported service providers is listed in <>. + +=== Access to OpenTelemetry API + +An implementation of MicroProfile Telemetry MUST provide the following CDI beans for supporting contextual instance injection: + +* `io.opentelemetry.api.OpenTelemetry` + +Implementations MAY support: + +* `io.opentelemetry.api.GlobalOpenTelemetry.get()` + +To obtain the access to `OpenTelemetry` instance. The consumer MUST use the exact same instrumentation name and version used by the implementation. +Failure to do so, MAY result in a different tracing and metrics components to be used. + +Later sections provide more beans for particular signal types. + +==== API classes + +In order to provide integration with OpenTelemetry the implementations SHALL make number of OpenTelemetry packages available to applications. +The full list of packages is listed in <>. + + diff --git a/spec/src/main/asciidoc/metrics.adoc b/spec/src/main/asciidoc/metrics.adoc index d56f279f..1ada3411 100644 --- a/spec/src/main/asciidoc/metrics.adoc +++ b/spec/src/main/asciidoc/metrics.adoc @@ -21,25 +21,15 @@ == Metrics - === Access to the OpenTelemetry Metrics API An implementation of MicroProfile Telemetry Metrics MUST provide the following CDI beans for supporting contextual instance injection: - -=== Supported OpenTelemetry API Classes -Classes from the following API packages MUST be supported by implementations of this specification, though this specification does not prevent additional API classes from being supported. -Implementations are allowed to pull in a more recent patch version of the API classes. - -==== Metrics APIs +* `io.opentelemetry.api.metrics.Meter` -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/metrics/package-summary.html[io.opentelemetry.api.metrics] -==== Autoconfigure SPI -This is the programmatic interface that allows users to register extensions when using the SDK Autoconfigure Extension (which we use for configuration). - ==== Semantic Conventions @@ -49,8 +39,3 @@ These packages are not stable and MAY be subject to breaking changes in future r ==== - -=== Configuration -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}]. - -At minimum the following MicroProfile Config properties MUST be supported: diff --git a/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc b/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc index f996c0be..1e5237bc 100644 --- a/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc +++ b/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc @@ -41,7 +41,10 @@ include::license-efsl.adoc[] :sectnums: include::introduction.adoc[] +include::integration.adoc[] include::tracing.adoc[] include::metrics.adoc[] +include::configuration.adoc[] +include::opentelemetry-apis.adoc[] include::release-notes.adoc[] diff --git a/spec/src/main/asciidoc/opentelemetry-apis.adoc b/spec/src/main/asciidoc/opentelemetry-apis.adoc new file mode 100644 index 00000000..42e2f902 --- /dev/null +++ b/spec/src/main/asciidoc/opentelemetry-apis.adoc @@ -0,0 +1,90 @@ +// +// Copyright (c) 2023 Contributors to the Eclipse Foundation +// +// See the NOTICE file(s) distributed with this work for additional +// information regarding copyright ownership. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +[[sec:opentelemetry-api]] +== Supported OpenTelemetry API Classes + +Classes from the following API packages MUST be supported by implementations of this specification, though this specification does not prevent additional API classes from being supported. +Implementations are allowed to pull in a more recent patch version of the API classes. + +=== OpenTelemetry API + +Common API:: +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/package-summary.html[io.opentelemetry.api] (except `GlobalOpenTelemetry`) +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/common/package-summary.html[io.opentelemetry.api.common] +Tracing API:: +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/trace/package-summary.html[io.opentelemetry.api.trace] +Baggage API:: +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/baggage/package-summary.html[io.opentelemetry.api.baggage] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/baggage/propagation/package-summary.html[io.opentelemetry.api.baggage.propagation] +Metrics API:: +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/metrics/package-summary.html[io.opentelemetry.api.metrics] + + +[NOTE] +===== +`io.opentelemetry.api` does depend on https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/logs/package-summary.html[io.opentelemetry.api.logs], though this specification only supports the parts that relate to Tracing and Metrics. +===== + +=== Context API + +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-context/{otel-java-version}/io/opentelemetry/context/package-summary.html[io.opentelemetry.context] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-context/{otel-java-version}/io/opentelemetry/context/propagation/package-summary.html[io.opentelemetry.context.propagation] + +=== Resource SDK + +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-common/{otel-java-version}/io/opentelemetry/sdk/resources/package-summary.html[io.opentelemetry.sdk.resources] + +=== Metrics SDK + +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-metrics/{otel-java-version}/io/opentelemetry/sdk/metrics/package-summary.html[io.opentelemetry.sdk.metrics] + +=== Autoconfigure SPI +This is the programmatic interface that allows users to register extensions when using the SDK Autoconfigure Extension (which we use for configuration). + +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/package-summary.html[io.opentelemetry.sdk.autoconfigure.spi] + +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/traces/package-summary.html[io.opentelemetry.sdk.autoconfigure.spi.traces] + +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/metrics/package-summary.html[io.opentelemetry.sdk.autoconfigure.spi.metrics] + +The above packages have dependencies on the following packages which MUST be supported to the extent that they are required by the Autoconfigure SPI classes: + +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-trace/{otel-java-version}/io/opentelemetry/sdk/trace/package-summary.html[io.opentelemetry.sdk.trace] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-trace/{otel-java-version}/io/opentelemetry/sdk/trace/data/package-summary.html[io.opentelemetry.sdk.trace.data] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-trace/{otel-java-version}/io/opentelemetry/sdk/trace/export/package-summary.html[io.opentelemetry.sdk.trace.export] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-trace/{otel-java-version}/io/opentelemetry/sdk/trace/samplers/package-summary.html[io.opentelemetry.sdk.trace.samplers] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-common/{otel-java-version}/io/opentelemetry/sdk/common/package-summary.html[io.opentelemetry.sdk.common] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-metrics/{otel-java-version}/io/opentelemetry/sdk/metrics/package-summary.html[io.opentelemetry.sdk.metrics] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-metrics/{otel-java-version}/io/opentelemetry/sdk/metrics/data/package-summary.html[io.opentelemetry.sdk.metrics.data] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-metrics/{otel-java-version}/io/opentelemetry/sdk/metrics/export/package-summary.html[io.opentelemetry.sdk.metrics.export] + +=== Tracing Annotations + +* https://www.javadoc.io/doc/io.opentelemetry.instrumentation/opentelemetry-instrumentation-annotations/latest/io/opentelemetry/instrumentation/annotations/package-summary.html[io.opentelemetry.instrumentation.annotations] (`WithSpan` and `SpanAttribute` only) + +=== Semantic Conventions Attributes + +[NOTE] +==== +These packages are not stable and MAY be subject to breaking changes in future releases. +==== + +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-semconv/{otel-java-version}-alpha/io/opentelemetry/semconv/trace/attributes/package-summary.html[io.opentelemetry.semconv.trace.attributes] +* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-semconv/{otel-java-version}-alpha/io/opentelemetry/semconv/resource/attributes/package-summary.html[io.opentelemetry.semconv.resource.attributes] \ No newline at end of file diff --git a/spec/src/main/asciidoc/tracing.adoc b/spec/src/main/asciidoc/tracing.adoc index f237a158..b7ed53cd 100644 --- a/spec/src/main/asciidoc/tracing.adoc +++ b/spec/src/main/asciidoc/tracing.adoc @@ -20,7 +20,7 @@ [[tracing]] == Tracing -In the observibility, Tracing is used to diganose problems. Tracing intrumentation was used to generate tracs. +In the observability, Tracing is used to diagnose problems. Tracing instrumentation is used to generate traces. === Tracing Instrumentation This specification supports the following three types of instrumentation: @@ -159,7 +159,6 @@ Both Agent and MicroProfile Telemetry Tracing Instrumentation (if any), MUST coe === Access to the OpenTelemetry Tracing API An implementation of MicroProfile Telemetry Tracing MUST provide the following CDI beans for supporting contextual instance injection: -* `io.opentelemetry.api.OpenTelemetry` * `io.opentelemetry.api.trace.Tracer` * `io.opentelemetry.api.trace.Span` * `io.opentelemetry.api.baggage.Baggage` @@ -169,275 +168,8 @@ Calling the OpenTelemetry API directly MUST work in the same way and yield the s * `io.opentelemetry.api.trace.Span.current()` * `io.opentelemetry.api.baggage.Baggage.current()` -Implementations MAY support: - -* `io.opentelemetry.api.GlobalOpenTelemetry.get()` - -To obtain the `Tracer` with the OpenTelemetry API, the consumer MUST use the exact same instrumentation name and version used by the implementation. -Failure to do so, MAY result in a different `Tracer` and incorrect handling of the OpenTelemetry data. - - -=== Supported OpenTelemetry API Classes -Classes from the following API packages MUST be supported by implementations of this specification, though this specification does not prevent additional API classes from being supported. -Implementations are allowed to pull in a more recent patch version of the API classes. - -==== Tracing APIs - -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/package-summary.html[io.opentelemetry.api] (except `GlobalOpenTelemetry`) -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/trace/package-summary.html[io.opentelemetry.api.trace] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/common/package-summary.html[io.opentelemetry.api.common] - -[NOTE] -==== -`io.opentelemetry.api` does depend on https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/metrics/package-summary.html[io.opentelemetry.api.metrics] and https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/logs/package-summary.html[io.opentelemetry.api.logs], though this specification only supports the parts that relate to Tracing. -==== - -==== Baggage APIs - -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/baggage/package-summary.html[io.opentelemetry.api.baggage] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-api/{otel-java-version}/io/opentelemetry/api/baggage/propagation/package-summary.html[io.opentelemetry.api.baggage.propagation] - -==== Context API - -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-context/{otel-java-version}/io/opentelemetry/context/package-summary.html[io.opentelemetry.context] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-context/{otel-java-version}/io/opentelemetry/context/propagation/package-summary.html[io.opentelemetry.context.propagation] - -==== Resource SDK - -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-common/{otel-java-version}/io/opentelemetry/sdk/resources/package-summary.html[io.opentelemetry.sdk.resources] - -==== Autoconfigure SPI -This is the programmatic interface that allows users to register extensions when using the SDK Autoconfigure Extension (which we use for configuration). - -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/package-summary.html[io.opentelemetry.sdk.autoconfigure.spi] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/traces/package-summary.html[io.opentelemetry.sdk.autoconfigure.spi.traces] - -The above packages have dependencies on the following packages which MUST be supported to the extent that they are required by the Autoconfigure SPI classes: - -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-trace/{otel-java-version}/io/opentelemetry/sdk/trace/package-summary.html[io.opentelemetry.sdk.trace] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-trace/{otel-java-version}/io/opentelemetry/sdk/trace/data/package-summary.html[io.opentelemetry.sdk.trace.data] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-trace/{otel-java-version}/io/opentelemetry/sdk/trace/export/package-summary.html[io.opentelemetry.sdk.trace.export] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-trace/{otel-java-version}/io/opentelemetry/sdk/trace/samplers/package-summary.html[io.opentelemetry.sdk.trace.samplers] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-sdk-common/{otel-java-version}/io/opentelemetry/sdk/common/package-summary.html[io.opentelemetry.sdk.common] - -==== Annotations - -* https://www.javadoc.io/doc/io.opentelemetry.instrumentation/opentelemetry-instrumentation-annotations/latest/io/opentelemetry/instrumentation/annotations/package-summary.html[io.opentelemetry.instrumentation.annotations] (`WithSpan` and `SpanAttribute` only) - -==== Semantic Conventions - -[NOTE] -==== -These packages are not stable and MAY be subject to breaking changes in future releases. -==== - -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-semconv/{otel-java-version}-alpha/io/opentelemetry/semconv/trace/attributes/package-summary.html[io.opentelemetry.semconv.trace.attributes] -* https://www.javadoc.io/static/io.opentelemetry/opentelemetry-semconv/{otel-java-version}-alpha/io/opentelemetry/semconv/resource/attributes/package-summary.html[io.opentelemetry.semconv.resource.attributes] - -=== Configuration -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}]. - -At minimum the following MicroProfile Config properties MUST be supported: - -// Table with property name, default value and description -[options="header"] -|=== -|Property Name |Description - -// sub-section, colspan=3 -2+h| Global Configuration - -|`otel.sdk.disabled` -| Set to `false` to enable OpenTelemetry. - -Default value: `true` -2+h| Exporters configuration - -|`otel.traces.exporter` -| List of exporters to be used for tracing, separated by commas. -`none` means no autoconfigured exporter. -Values other than `none` and `otlp` might link:#sec:service-loader-support[require additional libraries] - -Default value: `otlp` - -| `otel.propagators` -| The propagators to be used. -Values other than `none`, `tracecontext` and `baggage` might link:#sec:service-loader-support[require additional libraries] - -Default value: `tracecontext, baggage` - -2+h| Resource attributes - -| `otel.resource.attributes` -| Specify resource attributes in the following format: `key1=val1, key2=val2, key3=val3` - -| `otel.service.name` -| Specify logical service name. -Takes precedence over `service.name` defined with `otel.resource.attributes` - -Default value: application name (if applicable) - -2+h| Batch Span Processor - -| `otel.bsp.schedule.delay` -| The interval, in milliseconds, between two consecutive exports. - -Default value: `5000` - -| `otel.bsp.max.queue.size` -| The maximum queue size. - -Default value: `2048` - -| `otel.bsp.max.export.batch.size` -| The maximum batch size. - -Default value: `512` - -| `otel.bsp.export.timeout` -| The maximum allowed time, in milliseconds, to export data. - -Default value: `30000` - -2+h| Sampler - -| `otel.traces.sampler` -a| The sampler to use for tracing. -Supported values are: - -* `always_on` -* `always_off` -* `traceidratio` -* `parentbased_always_on` -* `parentbased_always_off` -* `parentbased_traceidratio` - -Support for other samplers might be added with link:#sec:service-loader-support[additional libraries] - -Default value: `parentbased_always_on` - -| `otel.traces.sampler.arg` -| An argument to the configured tracer if supported, for example a ratio. -Consult OpenTelemetry documentation for details. - -2+h| OTLP Exporter - -| `otel.exporter.otlp.protocol` -| The transport protocol to use on OTLP trace, metric, and log requests. -Options include grpc and http/protobuf. - -Default value: `grpc` - -| `otel.exporter.otlp.traces.protocol` -| The transport protocol to use on OTLP trace requests. -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. - -Default value: `http://localhost:4317` when protocol is `grpc`, and `http://localhost:4318/v1/traces` 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. -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. -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. -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.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. -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. - -Default value: `10000` -|=== - -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 -Implementation will load additional configuration related components by means of service loader. -This allows the application to define its own metadata and trace handling behavior. -The following components are supported - -[options=header] -|=== -| Component interface | Purpose - -| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/ConfigurablePropagatorProvider.html[`ConfigurablePropagatorProvider`] -| Provides implementation for a name referred in `otel.propagators` - -| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/traces/ConfigurableSpanExporterProvider.html[`ConfigurableSpanExporterProvider`] -| Provides implementation for a name referred in `otel.traces.exporter` - -| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/traces/ConfigurableSamplerProvider.html[`ConfigurableSamplerProvider`] -| Provides implementation for a name referred in `otel.traces.sampler` - -| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/AutoConfigurationCustomizerProvider.html[`AutoConfigurationCustomizerProvider`] -| Customizes configuration properties before they are applied to the SDK - -| https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/ResourceProvider.html[`ResourceProvider`] -| Defines resource attributes describing the application -|=== - -Behavior when multiple implementations are found for a given component name is undefined. -Behavior when customizer changes other properties than those listed in the spec is also undefined. - [[sec:semantic-conventions]] -=== Semantic Conventions +=== Trace Semantic Conventions The https://github.com/open-telemetry/opentelemetry-java/tree/v{otel-java-version}/semconv/src/main/java/io/opentelemetry/semconv[Trace Semantic Conventions] for Spans and Attributes MUST be followed by any compatible implementation. All attributes marked as `required` MUST be present in the context of the Span where they are defined. @@ -452,21 +184,7 @@ Implementation libraries can set the library name using the following property: `mp.telemetry.tracing.name` === Tracing Enablement -By default, MicroProfile Telemetry Tracing is deactivated. - -In order to enable any of the tracing aspects, the configuration `otel.sdk.disabled=false` MUST be specified in any of the configuration sources available via MicroProfile Config. - - -[IMPORTANT] -==== -This is a deviation from the OpenTelemetry Specification that specifies this configuration property officially, where https://opentelemetry.io[OpenTelemetry] is activated by default! - -But in fact, it will be activated only by adding it's dependency to the application or platform project. -To be able to add MicroProfile Telemetry Tracing to MicroProfile implementations by default without side effects, this deviating behaviour has been defined here (see also <>). -==== - -This property is read once when the application is starting. -Any changes afterwards will not take effect unless the application is restarted. +Tracing is activated whenever Microprofile Telemetry is enabled, as descibed in <>. === MicroProfile OpenTracing MicroProfile Telemetry Tracing supersedes MicroProfile OpenTracing. From 8aedf25f46b0270763030a008d774f662e6f445b Mon Sep 17 00:00:00 2001 From: Patrik Dudits Date: Mon, 8 Jan 2024 14:22:25 +0100 Subject: [PATCH 2/5] Fixed typos --- spec/src/main/asciidoc/configuration.adoc | 2 +- spec/src/main/asciidoc/integration.adoc | 2 +- spec/src/main/asciidoc/introduction.adoc | 2 +- spec/src/main/asciidoc/tracing.adoc | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/src/main/asciidoc/configuration.adoc b/spec/src/main/asciidoc/configuration.adoc index 307e946e..57e65f80 100644 --- a/spec/src/main/asciidoc/configuration.adoc +++ b/spec/src/main/asciidoc/configuration.adoc @@ -282,7 +282,7 @@ The following components are supported [options=header] |=== -| Component interface | Purpose +| Component interface | Purose | https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/ConfigurablePropagatorProvider.html[`ConfigurablePropagatorProvider`] | Provides implementation for a name referred in `otel.propagators` diff --git a/spec/src/main/asciidoc/integration.adoc b/spec/src/main/asciidoc/integration.adoc index 73b44a17..1975d47b 100644 --- a/spec/src/main/asciidoc/integration.adoc +++ b/spec/src/main/asciidoc/integration.adoc @@ -73,7 +73,7 @@ Later sections provide more beans for particular signal types. ==== API classes -In order to provide integration with OpenTelemetry the implementations SHALL make number of OpenTelemetry packages available to applications. +In order to provide integration with OpenTelemetry the implementations SHALL make a number of OpenTelemetry packages available to applications. The full list of packages is listed in <>. diff --git a/spec/src/main/asciidoc/introduction.adoc b/spec/src/main/asciidoc/introduction.adoc index 369cb14e..f3062bd0 100644 --- a/spec/src/main/asciidoc/introduction.adoc +++ b/spec/src/main/asciidoc/introduction.adoc @@ -32,7 +32,7 @@ The https://opentelemetry.io[OpenTelemetry] project solves these problems by pro == Architecture https://opentelemetry.io[OpenTelemetry] is a set of APIs, SDKs, tooling and integrations that are designed for the creation and management of telemetry data such as traces, metrics, and logs. -This specification defines the behaviors that allow MicroProfile applications to easily participate in an environment where distributed tracing is enabled via https://opentelemetry.io[OpenTelemetry] (a merger between https://opentracing.io[OpenTracing] and https://opencensus.io[OpenCensus]). +This specification defines the behaviors that allow MicroProfile applications to easily participate in an environment where distributed tracing is enabled via https://opentelemetry.io[OpenTelemetry]. The OpenTelemetry specification describes the cross-language requirements and expectations for all OpenTelemetry implementations. This specification is based on the https://github.com/open-telemetry/opentelemetry-java/tree/v{otel-java-version}[Java implementation v{otel-java-version}] of OpenTelemetry. An implementation of this MicroProfile Telemetry MAY consume a later patch release of the Java implementation as long as the required TCKs pass successfully. diff --git a/spec/src/main/asciidoc/tracing.adoc b/spec/src/main/asciidoc/tracing.adoc index b7ed53cd..9e721bad 100644 --- a/spec/src/main/asciidoc/tracing.adoc +++ b/spec/src/main/asciidoc/tracing.adoc @@ -184,7 +184,7 @@ Implementation libraries can set the library name using the following property: `mp.telemetry.tracing.name` === Tracing Enablement -Tracing is activated whenever Microprofile Telemetry is enabled, as descibed in <>. +Tracing is activated whenever Microprofile Telemetry is enabled, as described in <>. === MicroProfile OpenTracing MicroProfile Telemetry Tracing supersedes MicroProfile OpenTracing. From 1a202659612806c09ae76b9bf527003a660da470 Mon Sep 17 00:00:00 2001 From: Patrik Dudits Date: Mon, 22 Jan 2024 14:44:08 +0100 Subject: [PATCH 3/5] Clarify the 'supports API packages' requirement --- spec/src/main/asciidoc/opentelemetry-apis.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/src/main/asciidoc/opentelemetry-apis.adoc b/spec/src/main/asciidoc/opentelemetry-apis.adoc index 42e2f902..fe51b1cb 100644 --- a/spec/src/main/asciidoc/opentelemetry-apis.adoc +++ b/spec/src/main/asciidoc/opentelemetry-apis.adoc @@ -20,7 +20,7 @@ [[sec:opentelemetry-api]] == Supported OpenTelemetry API Classes -Classes from the following API packages MUST be supported by implementations of this specification, though this specification does not prevent additional API classes from being supported. +Classes from the following API packages MUST be available to applications by implementations of this specification, though this specification does not prevent additional API classes from being available. Implementations are allowed to pull in a more recent patch version of the API classes. === OpenTelemetry API From 806f3e5ede420d47deb6870048a980ed564f3fa5 Mon Sep 17 00:00:00 2001 From: Patrik Dudits Date: Mon, 22 Jan 2024 14:44:21 +0100 Subject: [PATCH 4/5] Fix typo --- spec/src/main/asciidoc/configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/src/main/asciidoc/configuration.adoc b/spec/src/main/asciidoc/configuration.adoc index 57e65f80..307e946e 100644 --- a/spec/src/main/asciidoc/configuration.adoc +++ b/spec/src/main/asciidoc/configuration.adoc @@ -282,7 +282,7 @@ The following components are supported [options=header] |=== -| Component interface | Purose +| Component interface | Purpose | https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/{otel-java-version}/io/opentelemetry/sdk/autoconfigure/spi/ConfigurablePropagatorProvider.html[`ConfigurablePropagatorProvider`] | Provides implementation for a name referred in `otel.propagators` From f7c242c08a8d95ee5c0752f05077abb9a9808c12 Mon Sep 17 00:00:00 2001 From: Patrik Dudits Date: Mon, 22 Jan 2024 14:53:43 +0100 Subject: [PATCH 5/5] 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