update open telemetry docs for telemetry 1.1

modules/ROOT/pages/microprofile-telemetry.adoc

@@ -12,19 +12,52 @@
 :page-type: general
 = Enable distributed tracing with MicroProfile Telemetry
 
+== What is OpenTelemetry ==
+
 In microservice applications, sources of latency or inaccuracy can be difficult to determine because relationships and dependencies among the constituent services are not always obvious. MicroProfile Telemetry helps you collect data on the paths that application requests take through services.
 
 One way to increase observability of an application is by emitting traces. Traces represent requests and consist of multiple spans. A span represents a single operation in a request and contains a name, time-related data, log messages, and metadata to gather data about what occurs during a transaction.
 
 link:https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-telemetry-1.0/plan%E2%80%A8%E2%80%A822.0.0.10-bet[MicroProfile Telemetry] is based on the https://opentelemetry.io/[OpenTelemetry project], which is a collection of open source vendor-agnostic tools, APIs, and SDKs for creating and managing trace data. You can enable MicroProfile Telemetry for Open Liberty by adding the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file and configuring the feature to connect to your distributed trace service.
 
-MicroProfile Telemetry supports the instrumentation of tracing data in your code in three different ways: <<#auto, automatic instrumentation>>, <<#manual, manual instrumentation>>, or <<#agent, agent instrumentation>>. The data can then be exported to tracing systems like https://www.jaegertracing.io/[Jaeger] or https://zipkin.io/[Zipkin].
-
 MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0]. 
 
+== Using OpenTelemetry ==
+
+To enable OpenTelemetry you must add one the following features `<feature>mpTelemetry-1.0</feature>` or `<feature>mpTelemetry-1.1</feature>` to your server.xml file. Then you configure one or more of: 
+
+* <<#auto, automatic instrumentation>> - which automatically traces your JAX-RS or RESTful web services.
+* <<#manual, manual instrumentation>> - which allows you to start and end telemetry spans manually.
+* <<#agent, agent instrumentation>> - which automatically adds telemetry to popular open source libraries. Agent instrumentation imposes additional limitations which are documented in <<#agent, agent instrumentation>>.
+
+OpenTelemetry requires a telemetry back end such as https://www.jaegertracing.io/[Jaeger] or https://zipkin.io/[Zipkin]. You will have to configure OpenTelemetry to use one. To do so add one of the following entries to your bootstrap.properties file:
+
+Configuring Open Telemetry to use a Jager server:
+
+[source,properties]
+----
+otel.traces.exporter=otlp
+otel.exporter.otlp.endpoint=http://localhost:4317/
+---
+
+Configuring Open Telemetry to use a Zipkin server:
+[source,properties]
+----
+otel.traces.exporter=zipkin
+otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans
+----
+
+=== Telemetry Versions and Java Enterprise Editions ===
+
+- `mpTelemetry-1.0` is compatible with `jakartaee-10.0` and `microProfile-6.0`
+- `mpTelemetry-1.0` is compatible with
+-- `javaee-7.0` and `microProfile-1.4`
+-- `jakartaee-8.0` and `microProfile-4.1`
+-- `jakartaee-9.1` and `microProfile-5.0`
+
 [#auto]
 == Automatic instrumentation
-With automatic instrumentation, you can observe traces without modifying the source code in your Jakarta RESTful web service (formerly JAX-RS) applications. To start emitting traces with automatic instrumentation, enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature in your `server.xml` file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service service requires.
+With automatic instrumentation, you can observe traces without modifying the source code in your JAX-RS or Jakarta RESTful web service applications. To start emitting traces with automatic instrumentation, enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature in your `server.xml` file by adding `<feature>mpTelemetry-1.0</feature>` or `<feature>mpTelemetry-1.1</feature>` to your server.xml file. By default, MicroProfile Telemetry automatic instrumentation is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service service requires.
 
 For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file.
 
@@ -50,7 +83,7 @@ For more information about the available properties, see xref:microprofile-confi
 
 [#manual]
 == Manual instrumentation
-Automatic instrumentation is available only for Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites.
+Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites.
 
 - Enable third-party APIs for your application by adding the following code in your `server.xml` file:
 +
@@ -79,6 +112,15 @@ Automatic instrumentation is available only for Jakarta RESTful web service appl
     </dependency>
 ----
 
+- Configure an exporter. For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file.
+
+[source,properties]
+----
+otel.sdk.disabled=false
+otel.traces.exporter=otlp
+otel.exporter.otlp.endpoint=http://localhost:4317/
+----
+
 After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API.
 
 - Add extra information, such as the user ID, to the current span. Any information that you add to a span is visible when you look at traces on your trace server.
@@ -141,6 +183,7 @@ The following important considerations apply to manual instrumentation.
 
 - You must call the `.end()` method on any span you create, otherwise the span is not recorded.
 - The current span is used as the parent for any new spans that are created. Therefore, when you create a span, you usually also want to make it current. However, you must close the `Scope` instance that is returned by the  `Span.makeCurrent()` method. You can close a `Scope` instance by specifying  a try-with-resources block, as shown in the previous example for creating a subspan.
+- Becuase Liberty supports per-application configuration it does not support `GlobalOpenTelemetry`. Using that class will not produce any telemetry data.
 
 For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own. Furthermore, be aware that this documentation includes information for the OpenTelemetry Metrics and Logging APIs, which are not supported by MicroProfile Telemetry.