From a6010c13f21ab23019250aca254f8bad7ceed410 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrik=20Dudit=C5=A1?= Date: Mon, 5 Feb 2024 15:11:42 +0100 Subject: [PATCH] Specification of Telemetry Metrics API requirements (#148) * Specification of Telemetry Metrics API requirements * Fixed typos * Clarify the 'supports API packages' requirement * Fix typo * Mark support for signal-level OTLP exporter settings optional --- spec/src/main/asciidoc/configuration.adoc | 319 ++++++++++++++++++ spec/src/main/asciidoc/integration.adoc | 79 +++++ spec/src/main/asciidoc/introduction.adoc | 2 +- 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 +--------------- 7 files changed, 496 insertions(+), 302 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..1a312762 --- /dev/null +++ b/spec/src/main/asciidoc/configuration.adoc @@ -0,0 +1,319 @@ +// +// 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: + +=== Required 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.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. + +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.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.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.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.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.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.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.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` + +|=== + +[[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..1975d47b --- /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 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/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..fe51b1cb --- /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 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 + +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..9e721bad 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 described in <>. === MicroProfile OpenTracing MicroProfile Telemetry Tracing supersedes MicroProfile OpenTracing.