Revise documentation for MicroProfile Telemetry 2.1

Updated sections on telemetry data exporting, metrics, and logs. Added new content for MicroProfile Telemetry 2.1 features.

Author: ttelang

modules/ROOT/pages/chapter09/index.adoc

@@ -16,11 +16,14 @@ In this chapter, we will explore the fundamentals of MicroProfile Telemetry, cov
 ** Correlation
 * Instrumenting OpenTelemetry
 * Tools for Trace Analysis
-* Exporting the Traces
+* Exporting Telemetry Data
 * Types of Telemetry
+* Metrics
+* Logs
 * Agent Instrumentation
 * Analyzing Traces
 * Security Considerations for Tracing
+* What's New in MicroProfile Telemetry 2.1
 
 == Introduction to MicroProfile Telemetry
 
@@ -105,7 +108,8 @@ To enable tracing and exporting of telemetry data, include the MicroProfile Tele
 <dependency>
    <groupId>org.eclipse.microprofile.telemetry</groupId>
    <artifactId>microprofile-telemetry-api</artifactId>
-   <version>1.1</version>
+   <type>pom</type>
+   <version>2.1</version>
    <scope>provided</scope>
 </dependency>
 ----
@@ -234,57 +238,66 @@ One of Tempo’s key advantages is its tight integration with Grafana dashboards
 == Exporting the Traces
 
 To export the traces we need to configure the exporter type and endpoint in the `src/main/resources/META-INF/microprofile-config.properties`.
-For using OTLP (OpenTelemetry Protocol) export, you need to add the following configuration in:
+MicroProfile Telemetry 2.0 and later require you to configure exporters for all three signal types: traces, metrics, and logs.
+For OTLP (OpenTelemetry Protocol) export, add the following configuration:
 
 [source]
 ----
-# Enable OpenTelemetry 
-otel.traces.exporter=otlp
+# Enable OpenTelemetry
+otel.sdk.disabled=false
 
-# Set the OTLP exporter endpoint
-otel.exporter.otlp.endpoint=http://localhost:4317 
+# Set the OTLP exporter endpoint (gRPC default: port 4317)
+otel.exporter.otlp.endpoint=http://<hostname>:4317
 
 # Define the service name
-otel.service.name=payment-service 
+otel.service.name=payment-service
 
-# Sampling rate: (1.0 = always, 0.5 = 50%, 0.0 = never)
+# Sampling: parentbased_always_on is the default
 otel.traces.sampler=parentbased_always_on
 ----
 
-This sends traces directly to a observability tool, enabling real-time distributed tracing and performance monitoring. To ensure proper tracing, your observability tool (for e.g. Jaeger) must be running to receive trace data.
+Configure signal-specific exporters only when you need to override the shared OTLP endpoint or protocol:
+
+[source]
+----
+# Traces exporter (default: otlp)
+otel.traces.exporter=otlp
+
+# Metrics exporter (default: otlp)
+otel.metrics.exporter=otlp
+
+# Logs exporter (default: otlp)
+otel.logs.exporter=otlp
+----
+
+This configuration sends telemetry data directly to an observability backend, enabling real-time distributed tracing, metrics collection, and log correlation. Ensure that the observability backend (for example, Jaeger for traces, or Grafana with Tempo and Loki) is running to receive telemetry data.
 
-Using OTLP is advantageous because it is the native standard for OpenTelemetry, ensuring seamless integration with a wide range of observability tools. One of its key benefits is that it allows developers to use multiple observability platforms without changing instrumentation, providing a unified and vendor-neutral tracing solution.
+OTLP is the native standard for OpenTelemetry. It allows you to use multiple observability platforms without changing instrumentation, providing a unified, vendor-neutral telemetry solution.
 
 === Verify the Traces
 
-Once tracing is enabled and the appropriate exporter is configured, the next step is to verify that traces are being captured and sent to the observability backend. This ensures that the MicroProfile Telemetry setup is functioning correctly and that distributed tracing data is available for monitoring and debugging.
+After you enable tracing and configure the exporter, verify that the traces are being captured and sent to the observability backend. This step confirms that the MicroProfile Telemetry setup functions correctly and that distributed tracing data is available for monitoring and debugging.
 
 ==== Run Jaeger
 
-The simplest way to run Jaeger is with Docker using the command as below:
+Run Jaeger using Docker with OTLP support:
 
 [source, bash]
 ----
 docker run -d --name jaeger \
-  -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
-  -p 5775:5775/udp \
-  -p 6831:6831/udp \
-  -p 6832:6832/udp \
-  -p 5778:5778 \
   -p 16686:16686 \
-  -p 14268:14268 \
-  -p 14250:14250 \
-  -p 9411:9411 \
+  -p 4317:4317 \
+  -p 4318:4318 \
   jaegertracing/all-in-one:latest
 ----
 
-The above command runs the *all-in-one* Jaeger container, which includes the agent, collector, query service, and UI.
+The above command runs the *all-in-one* Jaeger container, which includes the agent, collector, query service, and UI, with native OTLP support on ports 4317 (gRPC) and 4318 (HTTP/protobuf).
 
-The Jaeger UI can be accessed at: `https://<hostname>:16686`. 
+Access the Jaeger UI at `http://<hostname>:16686`.
 
-Ensure all the services of our MicroProfile E-commerce applications are running.
+Ensure all the services of the MicroProfile E-commerce application are running.
 
-Search using parameters like operation name, time range, or service for the traces associated with different microservices and confirm that the telemetry data is visible.
+Search using parameters such as operation name, time range, or service name for the traces associated with different microservices, and confirm that the telemetry data is visible.
 View a detailed breakdown of each span within the trace, including timing and attributes.
 
 == Types of Telemetry
@@ -417,7 +430,101 @@ One of the key advantages of agent-based instrumentation is that it requires no
 Refer to the https://opentelemetry.io/docs/zero-code/java/agent/getting-started/[OpenTelemetry Java Agent Getting Started page] for step-by-step instructions on enabling it for your application.
 Once enabled, the agent automatically instruments the application, seamlessly integrating with distributed tracing systems without requiring developer intervention. This makes it an efficient and non-intrusive way to implement observability in MicroProfile applications.
 
-Once enabled, the agent automatically instruments the application, seamlessly integrating with distributed tracing systems without requiring developer intervention. This makes it an efficient and non-intrusive way to implement observability in MicroProfile applications.
+== Metrics
+
+Metrics are captured measurements of an application's and runtime's behavior. An application can define custom metrics in addition to the required metrics provided by the runtime.
+
+=== Access to the OpenTelemetry Metrics API
+
+MicroProfile Telemetry MUST provide the following CDI bean for supporting contextual instance injection:
+
+* `io.opentelemetry.api.metrics.Meter`
+
+Inject the `Meter` to define and record custom metrics:
+
+[source, java]
+----
+import io.opentelemetry.api.metrics.LongCounter;
+import io.opentelemetry.api.metrics.Meter;
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributeKey;
+import jakarta.annotation.PostConstruct;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+@ApplicationScoped
+public class SubscriptionService {
+
+    @Inject
+    Meter meter;
+
+    private LongCounter subscriptionCounter;
+
+    @PostConstruct
+    public void init() {
+        subscriptionCounter = meter
+                .counterBuilder("new_subscriptions")
+                .setDescription("Number of new subscriptions")
+                .setUnit("1")
+                .build();
+    }
+
+    public void subscribe(String plan) {
+        subscriptionCounter.add(1,
+                Attributes.of(AttributeKey.stringKey("plan"), plan));
+    }
+}
+----
+
+The `Meter` instance creates instruments such as counters and histograms. The runtime computes separate aggregations for each unique combination of attributes.
+
+=== Required Metrics
+
+Runtimes MUST provide the following metrics, as defined in the OpenTelemetry Semantic Conventions.
+
+.Required HTTP server metric
+[options="header"]
+|===
+|Metric Name |Type
+|`http.server.request.duration` |Histogram
+|===
+
+.Required JVM metrics
+[options="header"]
+|===
+|Metric Name |Type
+|`jvm.memory.used` |UpDownCounter
+|`jvm.memory.committed` |UpDownCounter
+|`jvm.memory.limit` |UpDownCounter
+|`jvm.memory.used_after_last_gc` |UpDownCounter
+|`jvm.gc.duration` |Histogram
+|`jvm.thread.count` |UpDownCounter
+|`jvm.class.loaded` |Counter
+|`jvm.class.unloaded` |Counter
+|`jvm.class.count` |UpDownCounter
+|`jvm.cpu.time` |Counter
+|`jvm.cpu.count` |UpDownCounter
+|`jvm.cpu.recent_utilization` |Gauge
+|===
+
+Metrics are activated whenever MicroProfile Telemetry is enabled with `otel.sdk.disabled=false`.
+
+== Logs
+
+The OpenTelemetry Logs bridge API enables existing log frameworks (such as SLF4J, Log4j, JUL, and Logback) to emit logs through OpenTelemetry. This specification does not define new Log APIs. The Logs bridge API is used by runtimes, not directly by application code. Therefore, this specification does not expose any Log APIs to applications.
+
+Log output from an application is automatically bridged to the configured OpenTelemetry SDK instance when MicroProfile Telemetry is enabled. Configure the logs exporter in `microprofile-config.properties`:
+
+[source, properties]
+----
+otel.sdk.disabled=false
+otel.logs.exporter=otlp
+otel.exporter.otlp.endpoint=http://<hostname>:4317
+----
+
+When a log record is emitted from an application, the runtime bridges it to the configured OpenTelemetry SDK instance, which then exports it using the configured log exporter (for example, via OTLP). When an active trace context exists, the log record automatically includes the `traceId` and `spanId`, enabling correlation between logs and traces.
+
+Logs are activated whenever MicroProfile Telemetry is enabled with `otel.sdk.disabled=false`.
 
 == Analyzing Traces
 
@@ -528,7 +635,6 @@ To prevent unauthorized access during transmission, ensure that telemetry data i
 
 [source, properties]
 ----
-otel.exporter.jaeger.endpoint=https://secure-jaeger-collector.example.com
 otel.exporter.otlp.endpoint=https://secure-collector.example.com
 ----
 
@@ -563,7 +669,7 @@ Random sampling to limiting the amount of trace data collected:
 [source, properties]
 ----
 otel.traces.sampler=traceidratio
-otel.traces.sampler.traceidratio=0.1
+otel.traces.sampler.arg=0.1
 ----
 
 === Compliance with Regulations
@@ -593,6 +699,21 @@ Tracing can help detect potential security incidents. Monitor traces for unusual
 Set up alerts for these anomalies to investigate and mitigate potential issues. +
 By following these security considerations, you can leverage the benefits of distributed tracing without compromising the security of your system or the privacy of your users. Careful handling of trace data, coupled with robust encryption, access controls, and compliance practices, ensures that tracing remains a valuable yet secure component of your observability strategy.
 
+== What's New in MicroProfile Telemetry 2.1
+
+MicroProfile Telemetry 2.1 is aligned with MicroProfile 7.1. The following changes are delivered in this release.
+
+* MicroProfile Telemetry 2.1 consumes https://github.com/open-telemetry/opentelemetry-java/releases/tag/v1.48.0[OpenTelemetry Java v1.48.0].
+* If you are migrating from earlier version of MicroProfile Telemetry, update the `microprofile-telemetry-api` dependency version to `2.1`.
+* Verify that your deployment environment provides the OpenTelemetry Java v1.48.0 libraries or a later patch version.
+* The stabilization of HTTP semantic conventions (attributes such as `http.method` have been renamed to `http.request.method`).
+* The introduction of a single shared OpenTelemetry SDK instance when `otel.sdk.disabled=false` is configured at runtime initialization time.
+* The addition of Metrics and Logs support.
+
+=== Impact on Existing Applications
+
+Applications that do not use JVM metrics are unaffected by the 2.1 changes. Applications relying on JVM metrics should update their `microprofile-telemetry-api` dependency version to 2.1 to benefit from the corrected JVM metrics configuration.
+
 == Conclusion
 
 MicroProfile Telemetry provides a robust foundation for observability in Java-based microservices, enabling developers to implement distributed tracing seamlessly. By leveraging this specification, you can gain deep insights into the flow of requests, identify bottlenecks, and enhance the reliability and performance of your applications. The integration of standardized tracing concepts like spans, traces, and context propagation ensures that developers can maintain a cohesive understanding of their system's behavior across service boundaries.