Merge pull request #7556 from OpenLiberty/staging

Publish 24009 topics

modules/ROOT/nav.adoc

@@ -49,10 +49,13 @@
   ** xref:distributed-session-caching.adoc[Distributed session caching]
   ** xref:configuring-infinispan-support.adoc[Configuring Infinispan as a JCache provider]
 * xref:observability.adoc[Observability]
-  ** xref:microservice-observability-metrics.adoc[Microservice observability with metrics]
+  ** xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry]
+  ** xref:custom-mptelemetry-metrics.adoc[Define custom MicroProfile Telemetry metrics]
+  ** xref:telemetry-trace.adoc[Code instrumentation for MicroProfile Telemetry tracing]
+  ** xref:mptelemetry-logging.adoc[Write logs with MicroProfile Telemetry logging]
+  ** xref:microservice-observability-metrics.adoc[Microservice observability with with MicroProfile Metrics]
   ** xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]
   ** xref:health-check-microservices.adoc[Health checks for microservices]
-  ** xref:microprofile-telemetry.adoc[Enable distributed tracing]
   ** https://openliberty.io/guides/#observability[Guides: Observability]
 * xref:integration-testing.adoc[Testing]
   ** https://openliberty.io/guides/#test[Guides: Testing]
@@ -113,17 +116,20 @@
 
 // Begin operations section
 .Operations
+* xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]
 * xref:log-trace-configuration.adoc[Logs]
   ** xref:log-management.adoc[Log management]
   ** xref:access-logging.adoc[HTTP access logging]
   ** xref:jdbc-tracing.adoc[JDBC tracing]
+  ** xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list]
   ** xref:json-log-events-list.adoc[JSON log events reference list]
   ** xref:logstash-events-list.adoc[Logstash events reference list]
   ** xref:audit-log-events-list-cadf.adoc[Audit log events (CADF) reference list]
   ** xref:analyzing-logs-elk.adoc[Analyzing JSON logs with Elastic Stack]
   ** xref:forwarding-logs-logstash.adoc[Forwarding logs with Logstash collector]
 * xref:introduction-monitoring-metrics.adoc[Metrics]
-  ** xref:metrics-list.adoc[Metrics reference list]
+  ** xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]
+  ** xref:metrics-list.adoc[MicroProfile Metrics reference list]
   ** xref:configuring-jmx-connection.adoc[Configuring JMX connections]
   ** xref:jmx-metrics-list.adoc[JMX metrics reference list]
 * xref:slow-hung-request-detection.adoc[Slow and hung request detection]

modules/ROOT/pages/container-images.adoc

@@ -15,7 +15,7 @@
 
 A container image is a layered executable software package that contains everything you need to build and run a containerized application. You can use an Open Liberty container image to build an application image that meets your development needs.
 
-Open Liberty container images are available from link:https://www.ibm.com/cloud/container-registry[IBM Container Registry] (ICR). You can pull images from ICR without authentication.
+Open Liberty container images are available from the IBM Container Registry (ICR). You can pull images from ICR without authentication.
 
 == Container images on IBM Container Registry
 
@@ -38,9 +38,9 @@ Select from the following container image tags for the latest Open Liberty relea
 
 These tags pull the latest version because they do not specify a version number. You can specify a version other than the latest version in the image tag. If you do not specify a tag value, `latest` is used by default. For more information about these tag values, see the <<#tags,Container image tags naming conventions>> section.
 
-For more information on the full list of supported Open Liberty container images, see the link:https://github.com/OpenLiberty/ci.docker/blob/main/docs/icr-images.md[IBM Container Registry (ICR) page on the Open Liberty GitHub repository].
+After the initial release of the Liberty container images, they are refreshed regularly (every 1-2 weeks) to include fixes for the operating system (OS) and Java. For more information on the full list of supported Open Liberty container images, see the link:https://github.com/OpenLiberty/ci.docker/blob/main/docs/icr-images.md[IBM Container Registry (ICR) page on the Open Liberty GitHub repository].
 
-If you have an IBM Cloud ID, you can generate a list of the currently available images in ICR by using the link:https://cloud.ibm.com/docs/cli?topic=cli-getting-started[IBM Cloud CLI] with the link:https://cloud.ibm.com/docs/cli?topic=cli-install-devtools-manually#idt-install-container-registry-cli-plugin[IBM Cloud Container Registry CLI plug-in] installed. Authentication is required only to list the images. You can pull images from ICR without authentication. To list the images, run the following commands.
+If you have an IBM Cloud ID, you can generate a list of the currently available images in ICR by using the link:https://cloud.ibm.com/docs/cli?topic=cli-getting-started[IBM Cloud CLI] with the link:https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli[IBM Cloud Container Registry CLI plug-in] installed. Authentication is required only to list the images. You can pull images from ICR without authentication. To list the images, run the following commands.
 
 ----
 ibmcloud login

modules/ROOT/pages/custom-mptelemetry-metrics.adoc

@@ -0,0 +1,51 @@
+// Copyright (c) 2022 IBM Corporation and others.
+// Licensed under Creative Commons Attribution-NoDerivatives
+// 4.0 International (CC BY-ND 4.0)
+//   https://creativecommons.org/licenses/by-nd/4.0/
+//
+// Contributors:
+//     IBM Corporation
+//
+:page-description:
+:seo-description:
+:page-layout: general-reference
+:page-type: general
+= Define custom MicroProfile Telemetry metrics
+
+You can use the OpenTelemetry metrics API to define custom metrics in your application code. When you enable the MicroProfile Telemetry feature 2.0 or later, you can then collect and emit these metrics to customize the observability of your application.
+
+For more information about collecting and emitting metrics with MicroProfile Telemetry, see xref:microprofile-telemetry.adoc#metrics[Configuring Open Liberty to use MicroProfile Telemetry to collect metrics].
+
+For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation].
+
+Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry].
+
+The following example defines a custom counter metric:
+
+[source,java]
+----
+class WithCounter {
+    @Inject
+    Meter meter;
+
+    private LongCounter counter;
+
+    @PostConstruct
+    public void init() {
+        counter = meter
+                    .counterBuilder("new_subscriptions")
+                    .setDescription("Number of new subscriptions")
+                    .setUnit("1")
+                    .build();
+    }
+
+    void subscribe(String plan) {
+        counter.add(1,
+            Attributes.of(AttributeKey.stringKey("plan"), plan));
+    }
+}
+----
+
+In this example, `Meter` is used to define an instrument, in this case a Counter. Application code then can record measurement values along with other attributes. Measurement aggregations are computed separately for each unique combination of attributes.
+
+For a full list of available metrics, see link:https://opentelemetry.io/docs/specs/otel/metrics/api/#meter-operations[Meter operations] in the OpenTelemetry documentation.

modules/ROOT/pages/instanton.adoc

@@ -375,7 +375,7 @@ For more information, see the Red Hat documentation for link:https://docs.opensh
 [#supported-features]
 == Open Liberty InstantOn supported features
 
-InstantOn supports a subset of Open Liberty features. If a feature is enabled that InstantOn does not support, a failure occurs when you try to take a checkpoint of an application process. InstantOn supports the following Jakarta EE and MicroProfile xref:reference:feature/feature-overview.adoc#conv[convenience features]:
+InstantOn supports a subset of Open Liberty features. If a feature is enabled that InstantOn does not support, a failure occurs when you try to take a checkpoint of an application process. InstantOn supports the following Jakarta EE and MicroProfile xref:reference:feature/feature-overview.adoc#conv[convenience features] and all the features that they enable:
 
 - Jakarta EE Web Profile versions feature:webProfile-8.0[display=8.0] and later
 - MicroProfile versions feature:microProfile-4.1[display=4.1] and later

modules/ROOT/pages/introduction-monitoring-metrics.adoc

@@ -8,38 +8,43 @@
 //
 :page-layout: general-reference
 :page-type: general
-:page-description: With Open Liberty, two types of metrics are available to monitor your applications, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics.
+:page-description: With Open Liberty, three types of metrics are available to monitor your applications: OpenTelemetry metrics provided by MicroProfile Telemetry, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics.
 :seo-title: Monitoring with metrics - OpenLiberty.io
-:seo-description: With Open Liberty, two types of metrics are available to monitor your applications, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics.
+:seo-description: With Open Liberty, three types of metrics are available to monitor your applications: OpenTelemetry metrics provided by MicroProfile Telemetry, REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics..
 = Monitoring with metrics
 
-Two kinds of metrics are available to monitor your Open Liberty applications: REST endpoint-style metrics that are provided by MicroProfile Metrics, and Java Management Extensions (JMX) metrics. MicroProfile Metrics and JMX metrics can be used separately or in conjunction to improve the observability of your application systems.
+Three kinds of metrics are available to monitor your Open Liberty applications: OpenTelemetry metrics from MicroProfile Telemetry, REST endpoint-style metrics from MicroProfile Metrics, and Java Management Extensions (JMX) metrics. MicroProfile Metrics and JMX metrics can be used separately or in conjunction to improve the observability of your application systems.
 
+
+MicroProfile Telemetry 2.0 and later exports metrics to OTLP or another configured OpenTelemetry metrics exporter. You might prefer this option if you also use MicroProfile Telemetry to manage your logs and traces.
 MicroProfile Metrics can be accessed by monitoring tools, such as Prometheus, or by any client that can make REST requests.
 <<#jmx,JMX metrics>> are suitable for use by Java-based monitoring tools that can communicate with JMX servers, or by custom JMX clients.
 
-Open Liberty uses MicroProfile Metrics to expose metrics that describe the internal state of many Open Liberty components.
-Developers can also use the MicroProfile Metrics API to expose metrics from their applications.
-For more information about adding these metrics to your applications, see xref:microservice-observability-metrics.adoc#add[Adding metrics to your applications] and the link:/guides/microprofile-metrics.html[Providing metrics from a microservice] guide. For a list of all REST endpoint-style metrics that are available for Open Liberty, see the xref:metrics-list.adoc[Metrics reference list].
+[#mptelem]
+== Collect and export metrics with MicroProfile Telemetry
+When you enable the MicroProfile Telemetry feature version 2.0 and later, you can manage your logs, metrics, and traces in a standardized way with the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry].
 
 [#endpoint]
 == MicroProfile Metrics and the metrics endpoint
-The MicroProfile Metrics feature provides a `/metrics` REST interface that conforms to the MicroProfile Metrics specification. You can access MicroProfile Metrics with Open Liberty by feature:mpMetrics[display=enabling the MicroProfile Metrics feature]. Real-time values of all metrics are available by calling the `/metrics` endpoint, which provides formatted metric data that can be consumed as time-series data by external monitoring  tools. 
+Open Liberty uses MicroProfile Metrics to expose metrics that describe the internal state of many Open Liberty components. Developers can also use the MicroProfile Metrics API to expose metrics from their applications.
+For more information about adding these metrics to your applications, see xref:microservice-observability-metrics.adoc#add[Adding metrics to your applications] and the link:/guides/microprofile-metrics.html[Providing metrics from a microservice] guide. For a list of all REST endpoint-style metrics that are available for Open Liberty, see the xref:metrics-list.adoc[Metrics reference list].
+
+The MicroProfile Metrics feature provides a `/metrics` REST interface that conforms to the MicroProfile Metrics specification. You can access MicroProfile Metrics with Open Liberty by feature:mpMetrics[display=enabling the MicroProfile Metrics feature]. Real-time values of all metrics are available by calling the `/metrics` endpoint, which provides formatted metric data that can be consumed as time-series data by external monitoring  tools.
 
 When an application is running, you can view metric data from any browser by accessing the `/metrics` endpoint, for example, `\https://localhost:9443/metrics`, where `9443` is the port number for your application.
 You can narrow the scope of the metrics by using the `scope` query parameter with the `/metrics` endpoint to specify the metric registry scope. For example, to view the metric data for the `base` metric registry, use the `/metrics?scope=base` endpoint. This pattern is used to access all runtime-provided scopes  (`base`, `application`, and `vendor`) and any xref:microservice-observability-metrics.adoc#customscope[user-defined metric registry scopes]. For MicroProfile Metrics 4.0 and earlier, only runtime-provided scopes are available and path parameters are used to narrow down metric data. The endpoints are `/metrics/base`, `/metrics/application`, and `/metrics/vendor`.
 
-By default, MicroProfile Metrics provides metrics data in Prometheus format. Prometheus format is a representation of the metrics that is compatible with the https://prometheus.io/[Prometheus monitoring tool], which is an open source metrics scraper, data store, and basic visualization tool. In MicroProfile metrics 4.0 and earlier, JSON format is also available. 
+By default, MicroProfile Metrics provides metrics data in Prometheus format. Prometheus format is a representation of the metrics that is compatible with the https://prometheus.io/[Prometheus monitoring tool], which is an open source metrics scraper, data store, and basic visualization tool. In MicroProfile metrics 4.0 and earlier, JSON format is also available.
 
 The format that each response uses depends on the HTTP accept header of the corresponding request.
 Prometheus format is returned for requests with a `text/plain` accept header.
 In MicroProfile metrics 4.0 and earlier, JSON format is returned for requests with an `application/json` accept header.
 
-Metrics endpoints differ in syntax and output between MicroProfile Metrics 5.0 and MicroProfile Metrics 4.0 and earlier. MicroProfile Metrics 5.0 also xref:micrometer-metrics.adoc[uses embedded Micrometer metrics technology] to enable third-party monitoring systems. For more information, see xref:reference:diff/mp-50-60-diff.adoc#metrics[Differences between MicroProfile Metrics 5.0 and 4.0]
+Metrics endpoints differ in syntax and output between MicroProfile Metrics 5.0 and MicroProfile Metrics 4.0 and earlier. MicroProfile Metrics 5.0 also xref:micrometer-metrics.adoc[uses embedded Micrometer metrics technology] to enable third-party monitoring systems. For more information, see xref:reference:diff/mp-50-60-diff.adoc#metrics[Differences between MicroProfile Metrics 5.0 and 4.0].
 
-=== Metrics endpoints in MicroProfile Metrics 5.0 
+=== Metrics endpoints in MicroProfile Metrics 5.0
 
-MicroProfile Metrics 5.0 does not support JSON-formatted output. Furthermore, syntax for the endpoints URLs uses query string parameters for the scope and metric name values. 
+MicroProfile Metrics 5.0 does not support JSON-formatted output. Furthermore, syntax for the endpoints URLs uses query string parameters for the scope and metric name values.
 
 The following table displays the different endpoints that can be accessed with a `GET` request in MicroProfile Metrics 5.0 to provide metrics in Prometheus format.
 
@@ -64,7 +69,7 @@ The following table displays the different endpoints that can be accessed with a
 |Returns metrics that match the metric name for the specified scope.
 |===
 
-=== Metrics endpoints in MicroProfile Metrics 4.0 and earlier 
+=== Metrics endpoints in MicroProfile Metrics 4.0 and earlier
 
 The following table displays the different endpoints that can be accessed with a GET request in MicroProfile Metrics 4.0 and earlier to provide metrics in Prometheus or JSON format.
 

modules/ROOT/pages/jmx-metrics-list.adoc

@@ -21,6 +21,7 @@ The following sections list the JMX metrics that are available for different mon
 
 * <<jvm-stats,JVM monitoring>>
 * <<request-timing-stats,Request monitoring>>
+* <<http-stats, HTTP request monitoring>>
 * <<servlet-stats,Servlet monitoring>>
 * <<threadpool-stats,Thread pool monitoring>>
 * <<web-service-stats,JAX-WS monitoring>>
@@ -31,6 +32,8 @@ The following sections list the JMX metrics that are available for different mon
 * <<grpc-client-stats,gRPC client monitoring>>
 * <<sip-application,SIP application monitoring>>
 
+When you enable the feature:mpTelemetry-2.0[display=MicroProfile Telemetry] feature version 2.0 and later, you can manage your logs, metrics, and traces in a standardized way with the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry[Enable observability with MicroProfile Telemetry].
+
 [#jvm-stats]
 == JVM monitoring: JvmStats MXBean
 You can use the `JvmStats` MXBean to monitor the JVM in Open Liberty.
@@ -111,6 +114,64 @@ The object name of the MXBean for these attributes is `WebSphere:type=RequestTim
 
 |===
 
+[#http-stats]
+== HTTP request monitoring
+
+You can use the `HttpServerStats` MXBean to monitor HTTP requests that are made to the Open Liberty server. Performance data is available for each HTTP request made to the server and each unique combination of request method, response status, and HTTP route has its own MXBean.
+
+The following attributes are available for the `HttpServerStats` MXBean. The object name of the MXBean for these attributes is `WebSphere:type=HttpServerStats,name=*:`
+
+// Assisted by watsonx latest genai contribution llama-3-70b
+.HttpServerStats MXBean attributes
+[%header,cols="6,3,12"]
+|===
+| MXBean attribute | Units | Description
+| Duration
+| nanoseconds
+| The cumulative duration, in nanoseconds, of the requests made to this combination of request method, response status, and HTTP route
+
+| `Count`
+| n/a
+| The cumulative count of requests made to this combination of request method, response status, and HTTP route
+
+| `RequestMethod`
+| n/a
+| The request method used for the request
+
+| `ResponseStatus`
+| n/a
+| The response status of the request
+
+| `HttpRoute`
+| n/a
+| The HTTP route of the request
+
+| `Scheme`
+| n/a
+| The URL Scheme used for the request
+
+| `NetworkProtocolName`
+| n/a
+| The network protocol name used for the request
+
+| `NetworkProtocolVersion`
+| n/a
+| The network protocol version used for the request
+
+| `ServerName`
+| n/a
+| The server name the request was made to
+
+| `ServerPort`
+| n/a
+| The server port the request was made to
+
+| `ErrorType`
+| n/a
+| Error encountered if it exists
+|===
+
+
 [#servlet-stats]
 == Servlet monitoring: ServletStats MXBean
 You can use the `ServletStats` MXBean to monitor web applications in Open Liberty.