Specification of Telemetry Metrics API requirements

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.

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 <<sec:microprofile-telemetry-and-microprofile-opentracing>>).
+=====
+
+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 <<sec:configuration-properties>>.
+
+==== 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 <<sec:service-loader-support>>.
+
+=== 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 <<sec:opentelemetry-api>>.
+
+