From 6f0a4904f60a31779bc00776af15649f1b5282ba Mon Sep 17 00:00:00 2001 From: JanWesterkamp-iJUG Date: Tue, 18 Oct 2022 19:41:44 +0200 Subject: [PATCH] bump OpenTelemetry specification version including refinements (#60) * bump OpenTelemetry specification version to 1.13.0 including refinements --- NOTICE | 18 ++ README.adoc | 41 ++++- pom.xml | 2 +- tracing/README.adoc | 43 +++-- tracing/pom.xml | 1 - ...croprofile-telemetry-tracing-spec.asciidoc | 166 +++++++++--------- .../spec/src/main/resources/META-INF/NOTICE | 8 +- tracing/tck/README.adoc | 20 +-- tracing/tck/pom.xml | 2 + .../telemetry/tracing/tck/cdi/TracerTest.java | 2 +- .../tracing/tck/rest/BaggageTest.java | 2 +- .../tck/rest/RestClientSpanDisabledTest.java | 2 +- .../tracing/tck/rest/RestClientSpanTest.java | 2 +- .../tck/rest/RestSpanDisabledTest.java | 2 +- .../tracing/tck/rest/RestSpanTest.java | 2 +- .../tck/src/main/resources/META-INF/NOTICE | 13 +- 16 files changed, 201 insertions(+), 125 deletions(-) create mode 100644 NOTICE diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..4f76d0d --- /dev/null +++ b/NOTICE @@ -0,0 +1,18 @@ +========================================================================= +== NOTICE file corresponding to section 4(d) of the Apache License, == +== Version 2.0, in this case for MicroProfile Telemetry == +========================================================================= + +SPDXVersion: SPDX-2.1 +PackageName: MicroProfile +PackageHomePage: http://www.eclipse.org/microprofile +PackageLicenseDeclared: Apache-2.0 + +PackageCopyrightText: +Roberto Cortez, +Emily Jiang, +Bruno Baptista, +Jan Westerkamp, +Felix Wong, +Yasmin Aumeeruddy + \ No newline at end of file diff --git a/README.adoc b/README.adoc index 288c7a0..d088a9e 100644 --- a/README.adoc +++ b/README.adoc @@ -1,14 +1,41 @@ -# microprofile-telemetry +// +// Copyright (c) 2022 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. +// += MicroProfile Telemetry image:https://badges.gitter.im/eclipse/microprofile-telemetry.svg[link="https://gitter.im/eclipse/microprofile-telemetry?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"] This specification is to adopt https://opentelemetry.io/[OpenTelemetry] from CNCF to allow MicroProfile Applications benefit from OpenTelemetry and enable Jakarta RESTful Web Services automatically being traced if configured. -== OpenTracing move to OpenTelemetry -With the merge of OpenTracing and OpenCensus, OpenTelemetry holds the future. OpenTelemetry consists of Tracing, Logging and Metrics support. -This `tracing` directory only focuses on the tracing aspect. +== OpenTracing moves to OpenTelemetry +With the merge of OpenTracing and OpenCensus, OpenTelemetry holds the future. +OpenTelemetry consists of Tracing, Logging, Metrics and Baggage support. -== Structure of this specification -Since OpenTelemetry has three parts: Tracing, Metrics and Logging. This specification potentially adopts all three parts when they are stable in OpenTelemetry. If this is the case, they will appear as submodules in this specification. -For instance, you can find details related to `tracing` from the directory of `tracing`. This top level project specifies a particular version of OpenTelemetry to pull in so that all submodules can work together. +== Structure of this Specification +Since OpenTelemetry has three main parts and an additional one: +Tracing, Metrics, Logging and Baggage for additional information, i.e. to link between them. +This specification potentially adopts all three main parts when they are stable in OpenTelemetry. +If this is the case, they will appear as submodules in this specification. +For instance, you can find details related to `tracing` from the directory of `tracing`. +This top level project specifies a particular version of OpenTelemetry to pull in so that all submodules can work together. + +[NOTE] +==== +Currently implementations of this specification are required to support Tracing and Baggage only. +==== diff --git a/pom.xml b/pom.xml index 7157601..40a9279 100644 --- a/pom.xml +++ b/pom.xml @@ -32,7 +32,7 @@ 2022 1.13.0 - 1.18.0 + 1.19.0 3.0 diff --git a/tracing/README.adoc b/tracing/README.adoc index 2facc85..e560a5c 100644 --- a/tracing/README.adoc +++ b/tracing/README.adoc @@ -1,13 +1,32 @@ -= MicroProfile Telemetry +// +// Copyright (c) 2022 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. +// -This specification is to adopt https://opentelemetry.io/[OpenTelemetry] from CNCF to allow MicroProfile Applications benefit from OpenTelemetry and enable Jakarta RESTful Web Services automatically being traced if configured. += MicroProfile Telemetry Tracing +This specification is to adopt https://opentelemetry.io/[OpenTelemetry] from CNCF to allow MicroProfile applications benefit from OpenTelemetry and enable Jakarta RESTful Web Services automatically being traced if configured. -== OpenTracing move to OpenTelemetry -With the merge of OpenTracing and OpenCensus, OpenTelemetry holds the future. OpenTelemetry consists of Tracing, Logging and Metrics support. -This `tracing` directory only focuses on the tracing aspect. +== OpenTracing moves to OpenTelemetry +With the merge of OpenTracing and OpenCensus, OpenTelemetry holds the future. +OpenTelemetry consists of Tracing, Logging, Metrics and Baggage support. -== Directly adopt the APIs from OpenTelemetry Tracing +This `tracing` directory only focuses on the Tracing aspect (including Baggage use in this context). +== Directly adopt the APIs from OpenTelemetry Tracing This specification directly expose the Tracing APIs from OpenTelemetry and then provide CDI and Jakarta RESTful Web Services integration. The https://github.com/open-telemetry/opentelemetry-java/tree/main/api/all/src/main/java/io/opentelemetry/api/trace Tracer APIs from OpenTelemetry will be exposed. This specification does not plan to reinvent the wheels but rather exposes OpenTelemetry APIs due to the following reasons: @@ -17,14 +36,16 @@ This specification does not plan to reinvent the wheels but rather exposes OpenT * OpenTelemetry has Java API and annotations that are readily to be used * OpenTelemetry is active and open for the collaboration with us * OpenTelemetry is platform technology and we use the effort to make Java libraries to be used directly instead of reinventing our own APIs -* OpenTelemetry has broad vendor support. Many APMs are contributing to the spec, providing a guarantee that traces can be used out of the box, with minimal integrations. +* OpenTelemetry has broad vendor support. +Many observability vendors are contributing to the spec, providing a guarantee that traces can be used out of the box, with minimal integrations. * OpenTelemetry is serious with backward incompatible changes and communicates openly MicroProfile Telemetry pulls in a particular version of OpenTelemetry. Whenever we upgrade, we evaluate the backward compatibility status ourselves as well. == MicroProfile Telemetry Tracing -MicroProfile Telemetry pulls in OpenTelemetry Tracing and integrate with CDI and Jakarta Restful Services. It provides three types of instrumentations: +MicroProfile Telemetry pulls in OpenTelemetry Tracing and integrate with CDI and Jakarta RESTful Web Services. +It provides three types of instrumentation: * Automatic Instrumentation @@ -39,5 +60,7 @@ Explicit manual instrumentation can be added into a MicroProfile application usi Implementations are free to support the OpenTelemetry Agent Instrumentation. === Configuration -By default, MicroProfile Telemetry tracing is off. In order to enable any of the tracing aspects, the configuration `otel.experimental.sdk.enabled=true` must be specified in any of the config sources available via MicroProfile Config. -This property is read once when the application is starting. Any changes afterwards will not take effect unless the application is restarted. \ No newline at end of file +By default, MicroProfile Telemetry Tracing is off. +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. +This property is read once when the application is starting. +Any changes afterwards will not take effect unless the application is restarted. \ No newline at end of file diff --git a/tracing/pom.xml b/tracing/pom.xml index 2b9561b..bf66c1e 100644 --- a/tracing/pom.xml +++ b/tracing/pom.xml @@ -34,7 +34,6 @@ 3.0.1 3.0.2 - 5.9.1 4.2.0 diff --git a/tracing/spec/src/main/asciidoc/microprofile-telemetry-tracing-spec.asciidoc b/tracing/spec/src/main/asciidoc/microprofile-telemetry-tracing-spec.asciidoc index 35fb745..6567bb1 100644 --- a/tracing/spec/src/main/asciidoc/microprofile-telemetry-tracing-spec.asciidoc +++ b/tracing/spec/src/main/asciidoc/microprofile-telemetry-tracing-spec.asciidoc @@ -1,6 +1,8 @@ // -// Copyright (c) 2016-2022 Eclipse Microprofile Contributors: -// Bruno Baptista +// Copyright (c) 2022 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. @@ -16,7 +18,7 @@ // = MicroProfile Telemetry Tracing -:authors: MicroProfile Telemetry Spec Group (Roberto Cortez, Emily Jiang, Bruno Baptista, Jan Westerkamp, Felix Wong, Yasmin Aumeeruddy) +:authors: MicroProfile Telemetry Team (Roberto Cortez, Emily Jiang, Bruno Baptista, Jan Westerkamp, Felix Wong, Yasmin Aumeeruddy) :email: :version-label!: :sectanchors: @@ -40,26 +42,20 @@ include::license-efsl.adoc[] == Introduction - -In cloud-native technology stacks, distributed and polyglot architectures are the norm. Distributed architectures -introduce a variety of operational challenges including how to solve availability and performance issues quickly. +In cloud-native technology stacks, distributed and polyglot architectures are the norm. +Distributed architectures introduce a variety of operational challenges including how to solve availability and performance issues quickly. These challenges have led to the rise of observability. -Telemetry data is needed to power observability products. Traditionally, telemetry data has been provided by either -open-source projects or commercial vendors. With a lack of standardization, the net result is the lack of data -portability and the burden on the user to maintain the instrumentation. +Telemetry data is needed to power observability products. +Traditionally, telemetry data has been provided by either open-source projects or commercial vendors. +With a lack of standardization, the net result is the lack of data portability and the burden on the user to maintain the instrumentation. -The https://opentelemetry.io[OpenTelemetry] project solves these problems by providing a single, vendor-agnostic -solution. +The https://opentelemetry.io[OpenTelemetry] project solves these problems by providing a single, vendor-agnostic solution. == 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. -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] (a merger between https://opentracing.io[OpenTracing] and https://opencensus.io[OpenCensus]). This document and implementations *MUST* comply with the following OpenTelemetry {otel-spec-version} specifications: @@ -69,30 +65,33 @@ This document and implementations *MUST* comply with the following OpenTelemetry * https://github.com/open-telemetry/opentelemetry-specification/tree/v{otel-spec-version}/specification/context[Context API] * https://github.com/open-telemetry/opentelemetry-specification/blob/v{otel-spec-version}/specification/resource/sdk.md[Resource SDK] -IMPORTANT: The Metrics and Logging integrations of https://opentelemetry.io[OpenTelemetry] are out of scope of this -specification. Implementations are free to provide support for both Metrics and Logging if desired. +[IMPORTANT] +==== +The Metrics and Logging integrations of https://opentelemetry.io[OpenTelemetry] are out of scope of this specification. +Implementations are free to provide support for both Metrics and Logging if desired. +==== -This specification supports the following three type of instrumentions: Automatic Instrumentation, Manual Instrumentation and Agent Instrumentation. +This specification supports the following three types of instrumentation: -=== Automatic Instrumentation +* <> +* <> +* <> -Jakarta RESTful Web Services (server and client), and MicroProfile REST Clients are automatically enlisted to -participate in distributed tracing without code modification as specified in the -https://github.com/open-telemetry/opentelemetry-specification/blob/v{otel-spec-version}/specification/trace/api.md[Tracing API]. +[[sec:automatic-instrumentation]] +=== Automatic Instrumentation +Jakarta RESTful Web Services (server and client), and MicroProfile REST Clients are automatically enlisted to participate in distributed tracing without code modification as specified in the https://github.com/open-telemetry/opentelemetry-specification/blob/v{otel-spec-version}/specification/trace/api.md[Tracing API]. -These should follow the rules specified in the <> section. +These should follow the rules specified in the <> section. +[[sec:manual-instrumentation]] === Manual Instrumentation - Explicit manual instrumentation can be added into a MicroProfile application in the following ways: ==== @WithSpan +Annotating a method in any Jakarta CDI aware beans with the `io.opentelemetry.instrumentation.annotations.WithSpan` annotation. +This will create a new Span and establish any required relationships with the current Trace context. -Annotating a method in any Jakarta CDI aware beans with the `io.opentelemetry.extension.annotations.WithSpan` -annotation. This will create a new Span and establish any required relationships with the current Trace context. - -Method parameters can be annotated with the `io.opentelemetry.extension.annotations.SpanAttribute` annotation to -indicate which method parameters should be part of the Trace. +Method parameters can be annotated with the `io.opentelemetry.instrumentation.annotations.SpanAttribute` annotation to indicate which method parameters should be part of the Trace. Example: [source,java] @@ -109,7 +108,7 @@ class SpanBean { } - @WithSpan(kind = SERVER) + @WithSpan(kind = SpanKind.SERVER) void spanKind() { } @@ -122,10 +121,8 @@ class SpanBean { ---- ==== Obtain a SpanBuilder - -By obtaining a `SpanBuilder` from the current `Tracer` and calling -`io.opentelemetry.api.trace.Tracer.spanBuilder(String)`. In this case, it is the developer's responsibility to ensure -that the `Span` is properly created, closed, and propagated. +By obtaining a `SpanBuilder` from the current `Tracer` and calling `io.opentelemetry.api.trace.Tracer.spanBuilder(String)`. +In this case, it is the developer's responsibility to ensure that the `Span` is properly created, closed, and propagated. Example: [source,java] @@ -140,7 +137,7 @@ public class SpanResource { @Path("/span/new") public Response spanNew() { Span span = tracer.spanBuilder("span.new") - .setSpanKind(INTERNAL) + .setSpanKind(SpanKind.INTERNAL) .setParent(Context.current().with(this.span)) .setAttribute("my.attribute", "value") .startSpan(); @@ -151,12 +148,13 @@ public class SpanResource { } } ---- - -NOTE: Start and end a new `Span` will add a child `Span` to the current one enlisted by the automatic instrumentation -of Jakarta REST Applications. + +[NOTE] +==== +Start and end a new `Span` will add a child `Span` to the current one enlisted by the automatic instrumentation of Jakarta REST applications. +==== ==== Obtain the current Span - By obtaining the current `Span` to add attributes. The Span lifecycle is managed by the implementation. Example: @@ -193,13 +191,12 @@ public class SpanResource { } ---- +[[sec:agent-instrumentation]] === Agent Instrumentation +Implementations are free to support the OpenTelemetry Agent Instrumentation. +This provides the ability to gather telemetry data without code modifications by attaching a Java Agent JAR to the running JVM. -Implementations are free to support the OpenTelemetry Agent Instrumentation. This provides the ability to gather -telemetry data without code modifications by attaching a Java Agent JAR to the running JVM. - -If an implementation of MicroProfile Telemetry Tracing provides such support, it must conform to the instructions detailed -in the https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Java Instrumentation] (https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/v1.18.0[v{otel-java-version}]) project, including: +If an implementation of MicroProfile Telemetry Tracing provides such support, it must conform to the instructions detailed in the https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/v{otel-java-version}[OpenTelemetry Java Instrumentation {otel-java-version}] project, including: * https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/[Agent Configuration] * https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/#suppressing-specific-auto-instrumentation[Suppressing Instrumentation] @@ -207,9 +204,7 @@ in the https://github.com/open-telemetry/opentelemetry-java-instrumentation[Open Both Agent and MicroProfile Telemetry Tracing Instrumentation (if any), must coexist with each other. === Access to the OpenTelemetry Tracing API - -An implementation of MicroProfile Telemetry Tracing must provide the following CDI beans for supporting contextual instance -injection: +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` @@ -222,50 +217,55 @@ 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()` -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. +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. === Configuration - OpenTelemetry must be configured by MicroProfile Config following the configuration properties detailed in: -* https://github.com/open-telemetry/opentelemetry-java/tree/v{otel-java-version}/sdk-extensions/autoconfigure[OpenTelemetry SDK Autoconfigure] -(excluding properties related to Metrics and Logging). +* https://github.com/open-telemetry/opentelemetry-java/tree/v{otel-java-version}/sdk-extensions/autoconfigure[OpenTelemetry SDK Autoconfigure] (excluding properties related to Metrics and Logging) * https://opentelemetry.io/docs/instrumentation/java/manual/[Manual Instrumentation] -An implementation may opt to not support a subset of configuration properties related to a specific configuration. For -instance, `otel.traces.exporter` is required but if the implementation does not support `jaeger` as a valid exporter, -then all configuration properties referring to `otel.tracer.jaeger.*` are not required. +An implementation may opt to not support a subset of configuration properties related to a specific configuration. +For instance, `otel.traces.exporter` is required but if the implementation does not support `jaeger` as a valid exporter, then all configuration properties referring to `otel.tracer.jaeger.*` are not required. -[[semantic-conventions]] +[[sec:semantic-conventions]] === Semantic Conventions +The https://github.com/open-telemetry/opentelemetry-specification/tree/v{otel-spec-version}/specification/trace/semantic_conventions[Trace Semantic Conventions] for Spans and Attributes must be followed by any compatible implementation. -The https://github.com/open-telemetry/opentelemetry-specification/tree/v{otel-spec-version}/specification/trace/semantic_conventions[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. Any other -attribute is optional. Implementations can also add their own attributes. +All attributes marked as `required` must be present in the context of the Span where they are defined. +Any other attribute is optional. +Implementations can also add their own attributes. ==== MicroProfile Attributes - -Other MicroProfile specifications can add their own attributes under their own attribute name following the -convention `mp.[specification short name].[attribute name]`. +Other MicroProfile specifications can add their own attributes under their own attribute name following the convention `mp.[specification short name].[attribute name]`. Implementation libraries can set the library name using the following property: `mp.telemetry.tracing.name` - == Tracing Enablement +By default, MicroProfile Telemetry Tracing is deactivated. -By default, MicroProfile Telemetry tracing is off. In order to enable any of the tracing aspects, the configuration `otel.experimental.sdk.enabled=true` -must be specified in any of the config sources available via MicroProfile Config. This property is read once when the application is starting. Any changes afterwards will not take effect unless the application is restarted. +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. -== MicroProfile OpenTracing +// TODO The hard coded otel-spec-version need to be replaced in future spec releases! +[IMPORTANT] +==== +This is a deviation from the https://github.com/open-telemetry/opentelemetry-specification/blob/v1.14.0/specification/overview.md[OpenTelemetry Specification version 1.14.0] that specifies this configuration property officially, where https://opentelemetry.io[OpenTelemetry] is activated by default! -MicroProfile Telemetry Tracing supercedes MicroProfile OpenTracing. Even if the end goal is the same, -there are some considerable differences: +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 <>). + +The original definition for this configuration property and the corresponding `OTEL_SDK_DISABLED` environment variable is specified in the https://github.com/open-telemetry/opentelemetry-specification/blob/v1.14.0/specification/sdk-environment-variables.md#opentelemetry-environment-variable-specification[OpenTelemetry Environment Variable Specification version 1.14.0] and it's https://github.com/open-telemetry/opentelemetry-specification/blob/v1.14.0/specification/sdk-environment-variables.md#general-sdk-configuration[General SDK Configuration]. +==== + +This property is read once when the application is starting. +Any changes afterwards will not take effect unless the application is restarted. + +== MicroProfile OpenTracing +MicroProfile Telemetry Tracing supersedes MicroProfile OpenTracing. +Even if the end goal is the same, there are some considerable differences: * Different API (between OpenTracing and OpenTelemetry) * No `@Traced` annotation @@ -273,15 +273,14 @@ there are some considerable differences: * No customization of Span name through MicroProfile API * Differences in attribute names and mandatory ones -For these reasons, the MicroProfile Telemetry Tracing specification does not provide any migration path between -both projects. While it is certainly possible to achieve a migration path at the code level and at the specification -level (at the expense of not following the main OpenTelemetry specification), it is unlikely to be able to achieve the -same compatibility at the data layer. Regardless, implementations are still free to provide migration paths between -MicroProfile OpenTracing and MicroProfile Telemetry Tracing. +For these reasons, the MicroProfile Telemetry Tracing specification does not provide any migration path between both projects. +While it is certainly possible to achieve a migration path at the code level and at the specification level (at the expense of not following the main OpenTelemetry specification), it is unlikely to be able to achieve the same compatibility at the data layer. +Regardless, implementations are still free to provide migration paths between MicroProfile OpenTracing and MicroProfile Telemetry Tracing. -If a migration path is provided, the bridge layer provided by OpenTelemetry should be used. This bridge layer implements -OpenTracing APIs using OpenTelemetry APIs (more details can be found from https://github.com/open-telemetry/opentelemetry-specification/blob/v{otel-spec-version}/specification/compatibility/opentracing.md[OpenTracing Compatbility]. -The bridge layer takes OpenTelemetry Tracer and exposes as OpenTracing Tracer. See the example below. +If a migration path is provided, the bridge layer provided by OpenTelemetry should be used. +This bridge layer implements OpenTracing APIs using OpenTelemetry APIs (more details can be found from https://github.com/open-telemetry/opentelemetry-specification/blob/v{otel-spec-version}/specification/compatibility/opentracing.md[OpenTracing Compatbility]. +The bridge layer takes OpenTelemetry Tracer and exposes as OpenTracing Tracer. +See the example below. [source,java] ---- @@ -298,6 +297,7 @@ Afterwards, you can then register the tracer as the OpenTracing Global Tracer: GlobalTracer.registerIfAbsent(tracer); ---- +[[sec:microprofile-telemetry-and-microprofile-opentracing]] == MicroProfile Telemetry and MicroProfile OpenTracing - -If MicroProfile Telemetry and MicroProfile OpenTracing are both present in one application, it is advised only to enable one of them. Otherwise, no portalbe behaviour will occur. \ No newline at end of file +If MicroProfile Telemetry and MicroProfile OpenTracing are both present in one application, it is advised only to enable one of them. +Otherwise, no portable behaviour may occur. \ No newline at end of file diff --git a/tracing/spec/src/main/resources/META-INF/NOTICE b/tracing/spec/src/main/resources/META-INF/NOTICE index 3a48069..4f76d0d 100644 --- a/tracing/spec/src/main/resources/META-INF/NOTICE +++ b/tracing/spec/src/main/resources/META-INF/NOTICE @@ -1,6 +1,6 @@ ========================================================================= == NOTICE file corresponding to section 4(d) of the Apache License, == -== Version 2.0, in this case for MicroProfile Telemetry == +== Version 2.0, in this case for MicroProfile Telemetry == ========================================================================= SPDXVersion: SPDX-2.1 @@ -9,4 +9,10 @@ PackageHomePage: http://www.eclipse.org/microprofile PackageLicenseDeclared: Apache-2.0 PackageCopyrightText: +Roberto Cortez, +Emily Jiang, +Bruno Baptista, +Jan Westerkamp, +Felix Wong, +Yasmin Aumeeruddy \ No newline at end of file diff --git a/tracing/tck/README.adoc b/tracing/tck/README.adoc index 344d394..6b7f8e7 100644 --- a/tracing/tck/README.adoc +++ b/tracing/tck/README.adoc @@ -1,6 +1,8 @@ // -// Copyright (c) 2022 Eclipse Microprofile Contributors: -// +// Copyright (c) 2022 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. @@ -15,13 +17,11 @@ // limitations under the License. // -= Running the MicroProfile Telemetry Tracing TCK - += MicroProfile Telemetry Tracing TCK Any MicroProfile Telemetry implementation must pass this test suite. -The TCK uses `testng` +The TCK uses `TestNG` and `Arquillian`. == Hardware Requirements - All systems should meet the following recommended hardware requirements: * CPU running at 2.0 GHz or higher @@ -29,14 +29,12 @@ All systems should meet the following recommended hardware requirements: * Network access to the Internet == Software Requirements - You can run this TCK on platforms running the Solaris, Linux, Windows, and Mac OS with the following software installed: * Maven * JDK11+ == Dependencies - To enable the tests in your project you need to add the following dependency to your build: [source, xml] @@ -52,8 +50,8 @@ To enable the tests in your project you need to add the following dependency to ---- == Declaring the Tests to run - You also need to specify which tests you want to run, e.g. create a file `tck-suite.xml` in your project which contains the following content: + [source, xml] ---- @@ -71,8 +69,8 @@ You also need to specify which tests you want to run, e.g. create a file `tck-su ---- == Configuration in Apache Maven pom.xml - If you use Apache Maven then the tests are run via the `maven-surefire-plugin` + [source, xml] ---- @@ -92,11 +90,9 @@ If you use Apache Maven then the tests are run via the `maven-surefire-plugin` ---- == Running as a Scanned Dependency - You can also run the TCK as a scanned dependency. === Surefire Configuration in your pom.xml - Once you've added the dependency, you don't need a `tck-suite.xml` you can just scan the dependency for tests. [source, xml] diff --git a/tracing/tck/pom.xml b/tracing/tck/pom.xml index 37fb441..bfb3817 100644 --- a/tracing/tck/pom.xml +++ b/tracing/tck/pom.xml @@ -3,7 +3,9 @@ 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 diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java index 68e41cb..e465960 100644 --- a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java +++ b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java @@ -38,7 +38,7 @@ class TracerTest extends Arquillian { public static WebArchive createDeployment() { return ShrinkWrap.create(WebArchive.class) .addClasses(TracerBean.class) - .addAsResource(new StringAsset("otel.experimental.sdk.enabled=true"), + .addAsResource(new StringAsset("otel.sdk.disabled=false"), "META-INF/microprofile-config.properties"); } diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java index d1606ac..482da20 100644 --- a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java +++ b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java @@ -54,7 +54,7 @@ public static WebArchive createDeployment() { .addClasses(InMemorySpanExporter.class, InMemorySpanExporterProvider.class) .addAsServiceProvider(ConfigurableSpanExporterProvider.class, InMemorySpanExporterProvider.class) .addAsLibrary(TestLibraries.AWAITILITY_LIB) - .addAsResource(new StringAsset("otel.experimental.sdk.enabled=true\notel.traces.exporter=in-memory"), + .addAsResource(new StringAsset("otel.sdk.disabled=false\notel.traces.exporter=in-memory"), "META-INF/microprofile-config.properties"); } diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java index 6c580ce..693acac 100644 --- a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java +++ b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java @@ -68,7 +68,7 @@ public static WebArchive createDeployment() { .addClasses(InMemorySpanExporter.class, InMemorySpanExporterProvider.class) .addAsLibrary(TestLibraries.AWAITILITY_LIB) .addAsServiceProvider(ConfigurableSpanExporterProvider.class, InMemorySpanExporterProvider.class) - .addAsResource(new StringAsset("otel.experimental.sdk.enabled=false\notel.traces.exporter=in-memory"), + .addAsResource(new StringAsset("otel.sdk.disabled=true\notel.traces.exporter=in-memory"), "META-INF/microprofile-config.properties"); } diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java index d1c5dac..2ce7e89 100644 --- a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java +++ b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java @@ -79,7 +79,7 @@ public static WebArchive createDeployment() { .addClasses(InMemorySpanExporter.class, InMemorySpanExporterProvider.class) .addAsLibrary(TestLibraries.AWAITILITY_LIB) .addAsServiceProvider(ConfigurableSpanExporterProvider.class, InMemorySpanExporterProvider.class) - .addAsResource(new StringAsset("otel.experimental.sdk.enabled=true\notel.traces.exporter=in-memory"), + .addAsResource(new StringAsset("otel.sdk.disabled=false\notel.traces.exporter=in-memory"), "META-INF/microprofile-config.properties"); } diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java index c493b2d..a85a3a9 100644 --- a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java +++ b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java @@ -54,7 +54,7 @@ public static WebArchive createDeployment() { .addClasses(InMemorySpanExporter.class, InMemorySpanExporterProvider.class, BasicHttpClient.class) .addAsLibrary(TestLibraries.AWAITILITY_LIB) .addAsServiceProvider(ConfigurableSpanExporterProvider.class, InMemorySpanExporterProvider.class) - .addAsResource(new StringAsset("otel.experimental.sdk.enabled=false\notel.traces.exporter=in-memory"), + .addAsResource(new StringAsset("otel.sdk.disabled=true\notel.traces.exporter=in-memory"), "META-INF/microprofile-config.properties"); } diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java index 677beb0..82b67e3 100644 --- a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java +++ b/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java @@ -71,7 +71,7 @@ public static WebArchive createDeployment() { ConfigAsset config = new ConfigAsset() .add("otel.service.name", TEST_SERVICE_NAME) .add("otel.resource.attributes", SERVICE_VERSION.getKey() + "=" + TEST_SERVICE_VERSION) - .add("otel.experimental.sdk.enabled", "true") + .add("otel.sdk.disabled", "false") .add("otel.traces.exporter", "in-memory"); return ShrinkWrap.create(WebArchive.class) diff --git a/tracing/tck/src/main/resources/META-INF/NOTICE b/tracing/tck/src/main/resources/META-INF/NOTICE index 612b1aa..4f76d0d 100644 --- a/tracing/tck/src/main/resources/META-INF/NOTICE +++ b/tracing/tck/src/main/resources/META-INF/NOTICE @@ -1,13 +1,18 @@ ========================================================================= == NOTICE file corresponding to section 4(d) of the Apache License, == -== Version 2.0, in this case for MicroProfile Telemetry == +== Version 2.0, in this case for MicroProfile Telemetry == ========================================================================= -This product includes software developed at -The Apache Software Foundation (http://www.apache.org/). - SPDXVersion: SPDX-2.1 PackageName: MicroProfile PackageHomePage: http://www.eclipse.org/microprofile PackageLicenseDeclared: Apache-2.0 +PackageCopyrightText: +Roberto Cortez, +Emily Jiang, +Bruno Baptista, +Jan Westerkamp, +Felix Wong, +Yasmin Aumeeruddy + \ No newline at end of file