From 87a820c7f2136cf2e41892685c9d63bb55e9d658 Mon Sep 17 00:00:00 2001 From: Emily Jiang Date: Tue, 7 Nov 2023 18:01:52 +0000 Subject: [PATCH] Restructure to include metrics and merge specs together --- pom.xml | 6 +- {tracing/spec => spec}/pom.xml | 8 +- spec/src/main/asciidoc/introduction.adoc | 52 +++++++ .../src/main/asciidoc/license-alv2.adoc | 0 spec/src/main/asciidoc/license-efsl.adoc | 39 +++++ spec/src/main/asciidoc/metrics.adoc | 56 +++++++ .../microprofile-telemetry-spec.asciidoc | 47 ++++++ spec/src/main/asciidoc/release-notes.adoc | 43 ++++++ .../src/main/asciidoc/tracing.adoc | 103 ++----------- .../src/main/resources/META-INF/LICENSE | 0 .../src/main/resources/META-INF/NOTICE | 0 tck/README.adoc | 21 +++ tck/metrics/README.adoc | 138 ++++++++++++++++++ tck/metrics/pom.xml | 116 +++++++++++++++ {tracing => tck}/pom.xml | 24 +-- {tracing/tck => tck/tracing}/README.adoc | 4 +- {tracing/tck => tck/tracing}/pom.xml | 16 +- .../tracing/tck/BasicHttpClient.java | 0 .../telemetry/tracing/tck/ConfigAsset.java | 0 .../tracing/tck/TestApplication.java | 0 .../telemetry/tracing/tck/TestLibraries.java | 0 .../tck/async/JaxRsClientAsyncTest.java | 0 .../async/JaxRsClientAsyncTestEndpoint.java | 0 .../tck/async/JaxRsServerAsyncTest.java | 0 .../async/JaxRsServerAsyncTestEndpoint.java | 0 .../JaxRsServerAsyncTestEndpointClient.java | 0 .../tck/async/MpRestClientAsyncTest.java | 0 .../async/MpRestClientAsyncTestEndpoint.java | 0 .../tracing/tck/cdi/BaggageBeanTest.java | 0 .../tck/cdi/OpenTelemetryBeanTest.java | 0 .../tracing/tck/cdi/SpanBeanTest.java | 0 .../telemetry/tracing/tck/cdi/TracerTest.java | 0 .../tck/exporter/InMemorySpanExporter.java | 0 .../InMemorySpanExporterProvider.java | 0 .../tck/rest/B3MultiPropagationTest.java | 0 .../tracing/tck/rest/B3PropagationTest.java | 0 .../tracing/tck/rest/BaggageTest.java | 0 .../tck/rest/JaegerPropagationTest.java | 0 .../tracing/tck/rest/PropagationHelper.java | 0 .../tracing/tck/rest/PropagatorSpiTest.java | 0 .../tck/rest/RestClientSpanDefaultTest.java | 0 .../tck/rest/RestClientSpanDisabledTest.java | 0 .../tracing/tck/rest/RestClientSpanTest.java | 0 .../tracing/tck/rest/RestSpanDefaultTest.java | 0 .../tck/rest/RestSpanDisabledTest.java | 0 .../tracing/tck/rest/RestSpanTest.java | 0 .../tracing/tck/rest/TestPropagator.java | 0 .../tck/rest/TestPropagatorProvider.java | 0 .../tck/rest/W3BaggagePropagationTest.java | 0 .../tracing/tck/rest/W3PropagationTest.java | 0 .../tracing/tck/spi/CustomizerSpiTest.java | 0 .../tracing/tck/spi/ExporterSpiTest.java | 0 .../tracing/tck/spi/ResourceSpiTest.java | 0 .../tracing/tck/spi/SamplerSpiTest.java | 0 .../tracing/tck/spi/TestCustomizer.java | 0 .../tracing/tck/spi/TestResourceProvider.java | 0 .../tracing/tck/spi/TestSampler.java | 0 .../tracing/tck/spi/TestSamplerProvider.java | 0 .../src/main/resources/META-INF/LICENSE | 0 .../src/main/resources/META-INF/NOTICE | 0 .../tracing}/src/main/resources/META-INF/tck | 0 tracing/README.adoc | 66 --------- .../spec/src/main/asciidoc/license-efsl.adoc | 76 ---------- 63 files changed, 553 insertions(+), 262 deletions(-) rename {tracing/spec => spec}/pom.xml (78%) create mode 100644 spec/src/main/asciidoc/introduction.adoc rename tracing/spec/src/main/asciidoc/license-alv2.asciidoc => spec/src/main/asciidoc/license-alv2.adoc (100%) create mode 100644 spec/src/main/asciidoc/license-efsl.adoc create mode 100644 spec/src/main/asciidoc/metrics.adoc create mode 100644 spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc create mode 100644 spec/src/main/asciidoc/release-notes.adoc rename tracing/spec/src/main/asciidoc/microprofile-telemetry-tracing-spec.asciidoc => spec/src/main/asciidoc/tracing.adoc (81%) rename {tracing/spec => spec}/src/main/resources/META-INF/LICENSE (100%) rename {tracing/spec => spec}/src/main/resources/META-INF/NOTICE (100%) create mode 100644 tck/README.adoc create mode 100644 tck/metrics/README.adoc create mode 100644 tck/metrics/pom.xml rename {tracing => tck}/pom.xml (78%) rename {tracing/tck => tck/tracing}/README.adoc (97%) rename {tracing/tck => tck/tracing}/pom.xml (89%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/BasicHttpClient.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/ConfigAsset.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestApplication.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestLibraries.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTestEndpoint.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpoint.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpointClient.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTestEndpoint.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/BaggageBeanTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/OpenTelemetryBeanTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/SpanBeanTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporter.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporterProvider.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3MultiPropagationTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3PropagationTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/JaegerPropagationTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagationHelper.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagatorSpiTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDefaultTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDefaultTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagator.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagatorProvider.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3BaggagePropagationTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3PropagationTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/CustomizerSpiTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ExporterSpiTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ResourceSpiTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/SamplerSpiTest.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestCustomizer.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestResourceProvider.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSampler.java (100%) rename {tracing/tck => tck/tracing}/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSamplerProvider.java (100%) rename {tracing/tck => tck/tracing}/src/main/resources/META-INF/LICENSE (100%) rename {tracing/tck => tck/tracing}/src/main/resources/META-INF/NOTICE (100%) rename {tracing/tck => tck/tracing}/src/main/resources/META-INF/tck (100%) delete mode 100644 tracing/README.adoc delete mode 100644 tracing/spec/src/main/asciidoc/license-efsl.adoc diff --git a/pom.xml b/pom.xml index 2133deb5..e83a53b6 100644 --- a/pom.xml +++ b/pom.xml @@ -32,6 +32,9 @@ 2022 1.29.0 + 3.0.1 + 3.1 + 4.2.0 @@ -69,7 +72,8 @@ - tracing + spec + tck diff --git a/tracing/spec/pom.xml b/spec/pom.xml similarity index 78% rename from tracing/spec/pom.xml rename to spec/pom.xml index cf8c344a..51e1692b 100644 --- a/tracing/spec/pom.xml +++ b/spec/pom.xml @@ -17,13 +17,13 @@ 4.0.0 - org.eclipse.microprofile.telemetry.tracing - microprofile-telemetry-tracing-parent + org.eclipse.microprofile.telemetry + microprofile-telemetry-parent 1.2-SNAPSHOT - microprofile-telemetry-tracing-spec + microprofile-telemetry-spec pom - MicroProfile Telemetry Tracing Specification + MicroProfile Telemetry Specification \ No newline at end of file diff --git a/spec/src/main/asciidoc/introduction.adoc b/spec/src/main/asciidoc/introduction.adoc new file mode 100644 index 00000000..369cb14e --- /dev/null +++ b/spec/src/main/asciidoc/introduction.adoc @@ -0,0 +1,52 @@ +// +// Copyright (c) 2022, 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. +// + +[[introduction]] +== 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. +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. + +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. + +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]). + +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. + +Refer to the OpenTelemetry specification repo to understand some essential terms. + +* https://opentelemetry.io/docs/specs/otel/overview/[OpenTelemetry Overview] +* https://opentelemetry.io/docs/specs/otel/trace/api/[Tracing API] +* https://opentelemetry.io/docs/specs/otel/baggage/api/[Baggage API] +* https://opentelemetry.io/docs/specs/otel/context/[Context API] +* https://opentelemetry.io/docs/specs/otel/resource/sdk/[Resource SDK] + +[IMPORTANT] +==== +The Logging integrations of https://opentelemetry.io[OpenTelemetry] are out of scope of this specification. +Implementations are free to provide support for Logging if desired. +==== \ No newline at end of file diff --git a/tracing/spec/src/main/asciidoc/license-alv2.asciidoc b/spec/src/main/asciidoc/license-alv2.adoc similarity index 100% rename from tracing/spec/src/main/asciidoc/license-alv2.asciidoc rename to spec/src/main/asciidoc/license-alv2.adoc diff --git a/spec/src/main/asciidoc/license-efsl.adoc b/spec/src/main/asciidoc/license-efsl.adoc new file mode 100644 index 00000000..f30ab5c0 --- /dev/null +++ b/spec/src/main/asciidoc/license-efsl.adoc @@ -0,0 +1,39 @@ +[subs="normal"] +.... +Specification: {doctitle} + +Version: {revnumber} + +Status: {revremark} + +Release: {revdate} +.... + +== Copyright + +Copyright (c) {inceptionYear} , {currentYear} Eclipse Foundation. + +=== Eclipse Foundation Specification License - v1.1 + +By using and/or copying this document, or the Eclipse Foundation document from which this statement is linked or incorporated by reference, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions: + +Permission to copy, and distribute the contents of this document, or the Eclipse Foundation document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use: + +* link or URL to the original Eclipse Foundation document. +* All existing copyright notices, or if one does not exist, a notice (hypertext is preferred, but a textual representation is permitted) of the form: "Copyright (c) [$date-of-document] Eclipse Foundation AISBL <> " + +Inclusion of the full text of this NOTICE must be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof. + +No right to create modifications or derivatives of Eclipse Foundation documents is granted pursuant to this license, except anyone may prepare and distribute derivative works and portions of this document in software that implements the specification, in supporting materials accompanying such software, and in documentation of such software, PROVIDED that all such works include the notice below. HOWEVER, the publication of derivative works of this document for use as a technical specification is expressly prohibited. + +The notice is: + +"Copyright (c) [$date-of-document] Eclipse Foundation AISBL. This software or document includes material copied from or derived from [title and URI of the Eclipse Foundation specification document]." + +==== Disclaimers + +THIS DOCUMENT IS PROVIDED "AS IS," AND TO THE EXTENT PERMITTED BY APPLICABLE LAW THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION AISBL MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. + +TO THE EXTENT PERMITTED BY APPLICABLE LAW THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION AISBL WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF. + +The name and trademarks of the copyright holders or the Eclipse Foundation AISBL may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders. diff --git a/spec/src/main/asciidoc/metrics.adoc b/spec/src/main/asciidoc/metrics.adoc new file mode 100644 index 00000000..d56f279f --- /dev/null +++ b/spec/src/main/asciidoc/metrics.adoc @@ -0,0 +1,56 @@ +// +// Copyright (c) 2022, 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. +// + +[[metrics]] +== 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 + + +* 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 + +[NOTE] +==== +These packages are not stable and MAY be subject to breaking changes in future releases. +==== + + + +=== 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 new file mode 100644 index 00000000..f996c0be --- /dev/null +++ b/spec/src/main/asciidoc/microprofile-telemetry-spec.asciidoc @@ -0,0 +1,47 @@ +// +// Copyright (c) 2022, 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. +// + += MicroProfile Telemetry +:authors: MicroProfile Telemetry Team (Roberto Cortez, Emily Jiang, Bruno Baptista, Jan Westerkamp, Felix Wong, Yasmin Aumeeruddy, Patrik Duditš) +:email: +:version-label!: +:sectanchors: +:doctype: book +:license: Eclipse Foundation Specification License v1.1 +:source-highlighter: coderay +:toc: left +:toclevels: 4 +:sectnumlevels: 4 +ifdef::backend-pdf[] +:pagenums: +endif::[] +// Attributes defined in the microprofile-telemetry (parent) maven POM: +//:otel-java-version: + + +// == License +:sectnums!: +include::license-efsl.adoc[] +:sectnums: + +include::introduction.adoc[] +include::tracing.adoc[] +include::metrics.adoc[] +include::release-notes.adoc[] + diff --git a/spec/src/main/asciidoc/release-notes.adoc b/spec/src/main/asciidoc/release-notes.adoc new file mode 100644 index 00000000..9e97245e --- /dev/null +++ b/spec/src/main/asciidoc/release-notes.adoc @@ -0,0 +1,43 @@ +// +// Copyright (c) 2022, 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. +// + +[[release-notes]] +== Release Notes +This section documents the changes introduced by individual releases. + +[[release_notes_11]] +=== Release Notes for MicroProfile Telemetry 1.1 +A full list of changes delivered in the 1.1 release can be found at link:https://github.com/eclipse/microprofile-telemetry/milestone/1?closed=1[MicroProfile Telemetry 1.1 Milestone]. + +==== Incompatible Changes +None. + +==== API/SPI Changes +Consume the OpenTelemetry Java release link:https://github.com/open-telemetry/opentelemetry-java/releases/tag/v1.29.0[v1.29.0]. The full comparison with the link:https://github.com/open-telemetry/opentelemetry-java/releases/tag/v1.19.0[v1.19.0] supported by MicroProfile Telemetry 1.0 can be found link:https://github.com/open-telemetry/opentelemetry-java/compare/v1.19.0...v1.29.0[here]. + +==== Other Changes + +* Consume the latest OpenTelemetry Tracing (https://github.com/eclipse/microprofile-telemetry/issues/88[88]) +* Clarify which API classes MUST be available to users (https://github.com/eclipse/microprofile-telemetry/issues/91[91]) +* Clarify the behaviour of Span and Baggage beans when the current span or baggage changes (lhttps://github.com/eclipse/microprofile-telemetry/issues/90[90]) +* TCK: Implement tests in a way that is not timestamp dependent (https://github.com/eclipse/microprofile-telemetry/issues/44[44]) +* TCK: TCK RestClientSpanTest Span Name Doesn't Follow Semantic Conv (https://github.com/eclipse/microprofile-telemetry/issues/86[86]) +* TCK: Adding missing TCKs (https://github.com/eclipse/microprofile-telemetry/issues/89[89]) +* TCK: TCK cannot be run using the Arquillian REST protocol (https://github.com/eclipse/microprofile-telemetry/issues/72[72]) +* Typos in spec document (https://github.com/eclipse/microprofile-telemetry/issues/80[80]) diff --git a/tracing/spec/src/main/asciidoc/microprofile-telemetry-tracing-spec.asciidoc b/spec/src/main/asciidoc/tracing.adoc similarity index 81% rename from tracing/spec/src/main/asciidoc/microprofile-telemetry-tracing-spec.asciidoc rename to spec/src/main/asciidoc/tracing.adoc index 9da07adf..f237a158 100644 --- a/tracing/spec/src/main/asciidoc/microprofile-telemetry-tracing-spec.asciidoc +++ b/spec/src/main/asciidoc/tracing.adoc @@ -1,5 +1,5 @@ // -// Copyright (c) 2022 Contributors to the Eclipse Foundation +// Copyright (c) 2022, 2023 Contributors to the Eclipse Foundation // // See the NOTICE file(s) distributed with this work for additional // information regarding copyright ownership. @@ -17,63 +17,12 @@ // limitations under the License. // -= MicroProfile Telemetry Tracing -:authors: MicroProfile Telemetry Team (Roberto Cortez, Emily Jiang, Bruno Baptista, Jan Westerkamp, Felix Wong, Yasmin Aumeeruddy, Patrik Duditš) -:email: -:version-label!: -:sectanchors: -:doctype: book -:license: Eclipse Foundation Specification License v1.0 -:source-highlighter: coderay -:toc: left -:toclevels: 4 -:sectnumlevels: 4 -ifdef::backend-pdf[] -:pagenums: -endif::[] -// Attributes defined in the microprofile-telemetry (parent) maven POM: -//:otel-java-version: +[[tracing]] +== Tracing +In the observibility, Tracing is used to diganose problems. Tracing intrumentation was used to generate tracs. -// == License -:sectnums!: -include::license-efsl.adoc[] -:sectnums: - - -== 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. -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. - -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. - -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]). - -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. - -Refer to the OpenTelemetry specification repo to understand some essential terms. - -* https://opentelemetry.io/docs/specs/otel/overview/[OpenTelemetry Overview] -* https://opentelemetry.io/docs/specs/otel/trace/api/[Tracing API] -* https://opentelemetry.io/docs/specs/otel/baggage/api/[Baggage API] -* https://opentelemetry.io/docs/specs/otel/context/[Context API] -* https://opentelemetry.io/docs/specs/otel/resource/sdk/[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. -==== - +=== Tracing Instrumentation This specification supports the following three types of instrumentation: * <> @@ -81,16 +30,16 @@ This specification supports the following three types of instrumentation: * <> [[sec:automatic-instrumentation]] -=== 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 Tracing API. These SHOULD follow the rules specified in the <> section. [[sec:manual-instrumentation]] -=== Manual Instrumentation +==== Manual Instrumentation Explicit manual instrumentation can be added into a MicroProfile application in the following ways: -==== @WithSpan +===== @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. @@ -123,7 +72,7 @@ class SpanBean { } ---- -==== Obtain a SpanBuilder +===== 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. @@ -157,7 +106,7 @@ public class SpanResource { 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 +===== Obtain the current Span By obtaining the current `Span` to add attributes. The Span lifecycle is managed by the implementation. @@ -196,7 +145,7 @@ public class SpanResource { ---- [[sec:agent-instrumentation]] -=== 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. @@ -502,7 +451,7 @@ Implementation libraries can set the library name using the following property: `mp.telemetry.tracing.name` -== Tracing Enablement +=== 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. @@ -519,7 +468,7 @@ To be able to add MicroProfile Telemetry Tracing to MicroProfile implementations 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 OpenTracing MicroProfile Telemetry Tracing supersedes MicroProfile OpenTracing. Even if the end goal is the same, there are some considerable differences: @@ -553,29 +502,5 @@ GlobalTracer.registerIfAbsent(tracer); ---- [[sec:microprofile-telemetry-and-microprofile-opentracing]] -== MicroProfile Telemetry and MicroProfile OpenTracing +=== MicroProfile Telemetry and MicroProfile OpenTracing If MicroProfile Telemetry and MicroProfile OpenTracing are both present in one application, it is recommended to only enable one of them, otherwise non-portable behaviour MAY occur. - -== Release Notes -This section documents the changes introduced by individual releases. - -[[release_notes_11]] -=== Release Notes for MicroProfile Telemetry 1.1 -A full list of changes delivered in the 1.1 release can be found at link:https://github.com/eclipse/microprofile-telemetry/milestone/1?closed=1[MicroProfile Telemetry 1.1 Milestone]. - -==== Incompatible Changes -None. - -==== API/SPI Changes -Consume the OpenTelemetry Java release link:https://github.com/open-telemetry/opentelemetry-java/releases/tag/v1.29.0[v1.29.0]. The full comparison with the link:https://github.com/open-telemetry/opentelemetry-java/releases/tag/v1.19.0[v1.19.0] supported by MicroProfile Telemetry 1.0 can be found link:https://github.com/open-telemetry/opentelemetry-java/compare/v1.19.0...v1.29.0[here]. - -==== Other Changes - -* Consume the latest OpenTelemetry Tracing (https://github.com/eclipse/microprofile-telemetry/issues/88[88]) -* Clarify which API classes MUST be available to users (https://github.com/eclipse/microprofile-telemetry/issues/91[91]) -* Clarify the behaviour of Span and Baggage beans when the current span or baggage changes (lhttps://github.com/eclipse/microprofile-telemetry/issues/90[90]) -* TCK: Implement tests in a way that is not timestamp dependent (https://github.com/eclipse/microprofile-telemetry/issues/44[44]) -* TCK: TCK RestClientSpanTest Span Name Doesn't Follow Semantic Conv (https://github.com/eclipse/microprofile-telemetry/issues/86[86]) -* TCK: Adding missing TCKs (https://github.com/eclipse/microprofile-telemetry/issues/89[89]) -* TCK: TCK cannot be run using the Arquillian REST protocol (https://github.com/eclipse/microprofile-telemetry/issues/72[72]) -* Typos in spec document (https://github.com/eclipse/microprofile-telemetry/issues/80[80]) diff --git a/tracing/spec/src/main/resources/META-INF/LICENSE b/spec/src/main/resources/META-INF/LICENSE similarity index 100% rename from tracing/spec/src/main/resources/META-INF/LICENSE rename to spec/src/main/resources/META-INF/LICENSE diff --git a/tracing/spec/src/main/resources/META-INF/NOTICE b/spec/src/main/resources/META-INF/NOTICE similarity index 100% rename from tracing/spec/src/main/resources/META-INF/NOTICE rename to spec/src/main/resources/META-INF/NOTICE diff --git a/tck/README.adoc b/tck/README.adoc new file mode 100644 index 00000000..c2ff94a2 --- /dev/null +++ b/tck/README.adoc @@ -0,0 +1,21 @@ +// +// 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 TCK +This module contains TCKs for both Metrics and Tracing. \ No newline at end of file diff --git a/tck/metrics/README.adoc b/tck/metrics/README.adoc new file mode 100644 index 00000000..2fb941c2 --- /dev/null +++ b/tck/metrics/README.adoc @@ -0,0 +1,138 @@ +// +// Copyright (c) 2022-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. +// + += MicroProfile Telemetry Metrics TCK +Any MicroProfile Telemetry implementation must pass this test suite. +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 + * 4 GB of RAM or more + * 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] +---- + + + org.eclipse.microprofile.telemetry + microprofile-telemetry-metrics-tck + 2.0 + test + + +---- + +== Declaring the Tests to run +There are multiple groups of optional tests. These include: + +* `optional-tests`: `B3` and `Jaeger` progagation formats. ++ +These tests test the B3 and Jaeger propagation formats which are not required. If your implementation does not include support for these propagation formats, you should exclude the `optional-tests` group. + +* `optional-jaxrs-tests` JAX-RS server async programming models ++ +Although support for JAX-RS server async programming models is not optional, these tests depend on Jakarta Concurrency because they use `ManagedExecutorService`. ++ +If you are testing in an environment which does not provide Jakarta Concurrency, you should exclude the `optional-jaxrs-tests` group. + +Test groups can be excluded in the TestNG XML file. E.g. create a file `tck-suite.xml` in your project which contains the following content: + +[source, xml] +---- + + + + + + + + + +---- + +If you want to run the optional tests, you can specify all tests in the `tck-suite.xml`. E.g. + +[source, xml] +---- + + + + + + + + + +---- + +== Configuration in Apache Maven pom.xml +If you use Apache Maven then the tests are run via the `maven-surefire-plugin` + +[source, xml] +---- + + + + org.apache.maven.plugins + maven-surefire-plugin + 2.22.2 + + + tck-suite.xml + + + + + +---- + +== 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] +---- + + + + org.apache.maven.plugins + maven-surefire-plugin + 2.22.2 + + + org.eclipse.microprofile.telemetry:microprofile-telemetry-metrics-tck + + + + + +---- diff --git a/tck/metrics/pom.xml b/tck/metrics/pom.xml new file mode 100644 index 00000000..30e6397b --- /dev/null +++ b/tck/metrics/pom.xml @@ -0,0 +1,116 @@ + + + + 4.0.0 + + + org.eclipse.microprofile.telemetry + microprofile-telemetry-tck-parent + 1.2-SNAPSHOT + + + microprofile-telemetry-metrics-tck + MicroProfile Telemetry Metrics TCK + + + + org.eclipse.microprofile.config + microprofile-config-api + + + org.eclipse.microprofile.rest.client + microprofile-rest-client-api + + + jakarta.enterprise + jakarta.enterprise.cdi-api + + + jakarta.ws.rs + jakarta.ws.rs-api + + + io.opentelemetry + opentelemetry-sdk + + + io.opentelemetry + opentelemetry-sdk-extension-autoconfigure + + + jakarta.enterprise.concurrent + jakarta.enterprise.concurrent-api + 3.0.3 + + + io.opentelemetry.instrumentation + opentelemetry-instrumentation-annotations + + + io.opentelemetry + opentelemetry-semconv + + + org.testng + testng + + + org.jboss.arquillian.testng + arquillian-testng-container + + + org.jboss.shrinkwrap + shrinkwrap-api + + + org.jboss.shrinkwrap.resolver + shrinkwrap-resolver-impl-maven + + + org.jboss.shrinkwrap.resolver + shrinkwrap-resolver-api-maven + + + org.awaitility + awaitility + ${version.awaitility} + + + + + + + + com.coderplus.maven.plugins + copy-rename-maven-plugin + ${version.plugin.copy.rename} + + + copy-readme + prepare-package + + copy + + + ../README.adoc + target/classes/README.adoc + + + + + + + diff --git a/tracing/pom.xml b/tck/pom.xml similarity index 78% rename from tracing/pom.xml rename to tck/pom.xml index c5a6dae8..930914f0 100644 --- a/tracing/pom.xml +++ b/tck/pom.xml @@ -21,24 +21,26 @@ microprofile-telemetry-parent 1.2-SNAPSHOT - org.eclipse.microprofile.telemetry.tracing - microprofile-telemetry-tracing-parent + + microprofile-telemetry-tck-parent + 1.2-SNAPSHOT pom - MicroProfile Telemetry Tracing + MicroProfile Telemetry TCK - spec - tck + tracing + metrics - - 3.0.1 - 3.1 - 4.2.0 - - + + org.eclipse.microprofile + microprofile-tck-bom + 3.2 + pom + import + org.eclipse.microprofile.config microprofile-config-api diff --git a/tracing/tck/README.adoc b/tck/tracing/README.adoc similarity index 97% rename from tracing/tck/README.adoc rename to tck/tracing/README.adoc index ee12a1c2..d77f2011 100644 --- a/tracing/tck/README.adoc +++ b/tck/tracing/README.adoc @@ -41,7 +41,7 @@ To enable the tests in your project you need to add the following dependency to ---- - org.eclipse.microprofile.telemetry.tracing + org.eclipse.microprofile.telemetry microprofile-telemetry-tracing-tck 1.0 test @@ -137,7 +137,7 @@ Once you've added the dependency, you don't need a `tck-suite.xml` you can just 2.22.2 - org.eclipse.microprofile.telemetry.tracing:microprofile-telemetry-tracing-tck + org.eclipse.microprofile.telemetry:microprofile-telemetry-tracing-tck diff --git a/tracing/tck/pom.xml b/tck/tracing/pom.xml similarity index 89% rename from tracing/tck/pom.xml rename to tck/tracing/pom.xml index 9e084265..9bab5487 100644 --- a/tracing/tck/pom.xml +++ b/tck/tracing/pom.xml @@ -17,25 +17,15 @@ 4.0.0 - org.eclipse.microprofile.telemetry.tracing - microprofile-telemetry-tracing-parent + org.eclipse.microprofile.telemetry + microprofile-telemetry-tck-parent 1.2-SNAPSHOT microprofile-telemetry-tracing-tck MicroProfile Telemetry Tracing TCK - - - - org.eclipse.microprofile - microprofile-tck-bom - 3.2 - pom - import - - - + diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/BasicHttpClient.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/BasicHttpClient.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/BasicHttpClient.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/BasicHttpClient.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/ConfigAsset.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/ConfigAsset.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/ConfigAsset.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/ConfigAsset.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestApplication.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestApplication.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestApplication.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestApplication.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestLibraries.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestLibraries.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestLibraries.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/TestLibraries.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTestEndpoint.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTestEndpoint.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTestEndpoint.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsClientAsyncTestEndpoint.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpoint.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpoint.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpoint.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpoint.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpointClient.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpointClient.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpointClient.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/JaxRsServerAsyncTestEndpointClient.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTestEndpoint.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTestEndpoint.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTestEndpoint.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/async/MpRestClientAsyncTestEndpoint.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/BaggageBeanTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/BaggageBeanTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/BaggageBeanTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/BaggageBeanTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/OpenTelemetryBeanTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/OpenTelemetryBeanTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/OpenTelemetryBeanTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/OpenTelemetryBeanTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/SpanBeanTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/SpanBeanTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/SpanBeanTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/SpanBeanTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/cdi/TracerTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporter.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporter.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporter.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporter.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporterProvider.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporterProvider.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporterProvider.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/exporter/InMemorySpanExporterProvider.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3MultiPropagationTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3MultiPropagationTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3MultiPropagationTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3MultiPropagationTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3PropagationTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3PropagationTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3PropagationTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/B3PropagationTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/BaggageTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/JaegerPropagationTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/JaegerPropagationTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/JaegerPropagationTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/JaegerPropagationTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagationHelper.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagationHelper.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagationHelper.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagationHelper.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagatorSpiTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagatorSpiTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagatorSpiTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/PropagatorSpiTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDefaultTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDefaultTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDefaultTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDefaultTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanDisabledTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestClientSpanTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDefaultTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDefaultTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDefaultTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDefaultTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanDisabledTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/RestSpanTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagator.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagator.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagator.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagator.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagatorProvider.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagatorProvider.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagatorProvider.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/TestPropagatorProvider.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3BaggagePropagationTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3BaggagePropagationTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3BaggagePropagationTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3BaggagePropagationTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3PropagationTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3PropagationTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3PropagationTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/rest/W3PropagationTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/CustomizerSpiTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/CustomizerSpiTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/CustomizerSpiTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/CustomizerSpiTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ExporterSpiTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ExporterSpiTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ExporterSpiTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ExporterSpiTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ResourceSpiTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ResourceSpiTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ResourceSpiTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/ResourceSpiTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/SamplerSpiTest.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/SamplerSpiTest.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/SamplerSpiTest.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/SamplerSpiTest.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestCustomizer.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestCustomizer.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestCustomizer.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestCustomizer.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestResourceProvider.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestResourceProvider.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestResourceProvider.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestResourceProvider.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSampler.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSampler.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSampler.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSampler.java diff --git a/tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSamplerProvider.java b/tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSamplerProvider.java similarity index 100% rename from tracing/tck/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSamplerProvider.java rename to tck/tracing/src/main/java/org/eclipse/microprofile/telemetry/tracing/tck/spi/TestSamplerProvider.java diff --git a/tracing/tck/src/main/resources/META-INF/LICENSE b/tck/tracing/src/main/resources/META-INF/LICENSE similarity index 100% rename from tracing/tck/src/main/resources/META-INF/LICENSE rename to tck/tracing/src/main/resources/META-INF/LICENSE diff --git a/tracing/tck/src/main/resources/META-INF/NOTICE b/tck/tracing/src/main/resources/META-INF/NOTICE similarity index 100% rename from tracing/tck/src/main/resources/META-INF/NOTICE rename to tck/tracing/src/main/resources/META-INF/NOTICE diff --git a/tracing/tck/src/main/resources/META-INF/tck b/tck/tracing/src/main/resources/META-INF/tck similarity index 100% rename from tracing/tck/src/main/resources/META-INF/tck rename to tck/tracing/src/main/resources/META-INF/tck diff --git a/tracing/README.adoc b/tracing/README.adoc deleted file mode 100644 index e560a5cf..00000000 --- a/tracing/README.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// -// 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 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 moves to OpenTelemetry -With the merge of OpenTracing and OpenCensus, OpenTelemetry holds the future. -OpenTelemetry consists of Tracing, Logging, Metrics and Baggage support. - -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: - -* OpenTelemetry is a specification under CNCF -* OpenTelemetry is widely adopted by different vendors and languages -* 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 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 Web Services. -It provides 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 Tracing API. - -* Manual Instrumentation - -Explicit manual instrumentation can be added into a MicroProfile application using annotation or programmatic lookup. - -* Agent Instrumentation - -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.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/spec/src/main/asciidoc/license-efsl.adoc b/tracing/spec/src/main/asciidoc/license-efsl.adoc deleted file mode 100644 index 73427a20..00000000 --- a/tracing/spec/src/main/asciidoc/license-efsl.adoc +++ /dev/null @@ -1,76 +0,0 @@ -[subs="normal"] -.... -Specification: {doctitle} - -Version: {revnumber} - -Status: {revremark} - -Release: {revdate} -.... - -== Copyright - -Copyright (c) {inceptionYear} , {currentYear} Eclipse Foundation. - -=== Eclipse Foundation Specification License - -By using and/or copying this document, or the Eclipse Foundation -document from which this statement is linked, you (the licensee) agree -that you have read, understood, and will comply with the following -terms and conditions: - -Permission to copy, and distribute the contents of this document, or -the Eclipse Foundation document from which this statement is linked, in -any medium for any purpose and without fee or royalty is hereby -granted, provided that you include the following on ALL copies of the -document, or portions thereof, that you use: - -* link or URL to the original Eclipse Foundation document. -* All existing copyright notices, or if one does not exist, a notice - (hypertext is preferred, but a textual representation is permitted) - of the form: "Copyright (c) [$date-of-document] - Eclipse Foundation, Inc. \<>" - -Inclusion of the full text of this NOTICE must be provided. We -request that authorship attribution be provided in any software, -documents, or other items or products that you create pursuant to the -implementation of the contents of this document, or any portion -thereof. - -No right to create modifications or derivatives of Eclipse Foundation -documents is granted pursuant to this license, except anyone may -prepare and distribute derivative works and portions of this document -in software that implements the specification, in supporting materials -accompanying such software, and in documentation of such software, -PROVIDED that all such works include the notice below. HOWEVER, the -publication of derivative works of this document for use as a technical -specification is expressly prohibited. - -The notice is: - -"Copyright (c) [$date-of-document] Eclipse Foundation. This software or -document includes material copied from or derived from [title and URI -of the Eclipse Foundation specification document]." - -==== Disclaimers - -THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT -HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR -WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, -WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, -NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE -SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS -WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR -OTHER RIGHTS. - -THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE -FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT -OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE -CONTENTS THEREOF. - -The name and trademarks of the copyright holders or the Eclipse -Foundation may NOT be used in advertising or publicity pertaining to -this document or its contents without specific, written prior -permission. Title to copyright in this document will at all times -remain with copyright holders.