diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 73f5ebe2bd..9e078e6a3f 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -49,13 +49,11 @@ ** xref:distributed-session-caching.adoc[Distributed session caching] ** xref:configuring-infinispan-support.adoc[Configuring Infinispan as a JCache provider] * xref:observability.adoc[Observability] -// ** xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry] + ** xref:health-check-microservices.adoc[Health checks for microservices] ** 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 MicroProfile Metrics] *** xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics] - ** xref:health-check-microservices.adoc[Health checks for microservices] ** https://openliberty.io/guides/#observability[Guides: Observability] * xref:integration-testing.adoc[Testing] ** https://openliberty.io/guides/#test[Guides: Testing] diff --git a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc index 38bd93de7b..8fd1cd5ac3 100644 --- a/modules/ROOT/pages/custom-mptelemetry-metrics.adoc +++ b/modules/ROOT/pages/custom-mptelemetry-metrics.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2022 IBM Corporation and others. +// Copyright (c) 2022, 2025 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/ @@ -12,13 +12,13 @@ :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. +When you enable MicroProfile Telemetry 2.0 or later, Open Liberty automatically collects and exports a default set of metrics. Additionally, you can use the OpenTelemetry API to define custom metrics in your application code, if needed. For more information about collecting and emitting metrics with MicroProfile Telemetry, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. Before you can use OpenTelemetry to define custom metrics metrics, you must make 3rd party APIs visible in your runtime environment by editing your runtime configuration. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API]. -The following example defines a custom counter metric: +The following example defines a custom counter metric in the application: [source,java] ---- diff --git a/modules/ROOT/pages/instanton.adoc b/modules/ROOT/pages/instanton.adoc index b3dddf2823..1c57e435f3 100644 --- a/modules/ROOT/pages/instanton.adoc +++ b/modules/ROOT/pages/instanton.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2023 IBM Corporation and others. +// Copyright (c) 2025 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/ @@ -389,15 +389,20 @@ In addition to the features that are enabled in the MicroProfile and Jakarta con - feature:appAuthorization-2.1[] - feature:appSecurity-1.0[] - feature:audit-1.0[] +- feature:batch-1.0[] +- feature:batch-2.0[] +- feature:batch-2.1[] - feature:bells-1.0[] - feature:connectors-2.0[] - feature:connectors-2.1[] +- feature:connectorsInboundSecurity-2.0[] - feature:crac-1.4[] - feature:distributedMap-1.0[] - feature:federatedRegistry-1.0[] - feature:javaMail-1.6[] - feature:jaxws-2.2[] - feature:jca-1.7[] +- feature:jcaInboundSecurity-1.0[] - feature:jdbc-4.1[] - feature:jdbc-4.3[] - feature:jms-2.0[] diff --git a/modules/ROOT/pages/introduction-monitoring-metrics.adoc b/modules/ROOT/pages/introduction-monitoring-metrics.adoc index e448810de8..7b9c2fb9af 100644 --- a/modules/ROOT/pages/introduction-monitoring-metrics.adoc +++ b/modules/ROOT/pages/introduction-monitoring-metrics.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2020, 2023 IBM Corporation and others. +// Copyright (c) 2020, 2025 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/ @@ -16,15 +16,14 @@ 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. OpenTelemetry provides a standardized solution to manage metrics, logs, and traces. 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 the configured OpenTelemetry metrics exporter, which can send metrics to the backend service of your choice. You might prefer this option if you also use MicroProfile Telemetry to manage your logs and traces. The following information pertains to MicroProfile Metrics and JMX Metrics. For information about using OpenTelemetry and MicroProfile Telemetry to collect and export metrics, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. +MicroProfile Telemetry 2.0 and later exports metrics to the configured OpenTelemetry metrics exporter, which can send metrics to the backend service of your choice. You might prefer this option if you also use MicroProfile Telemetry to manage your logs and traces. The information in this topic pertains to MicroProfile Metrics and JMX Metrics. For information about instead using OpenTelemetry and MicroProfile Telemetry to collect and export metrics, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. 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. - the [#endpoint] == MicroProfile Metrics and the metrics endpoint -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. +When you enable the MicroProfile Metrics feature, 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. diff --git a/modules/ROOT/pages/jdbc-tracing.adoc b/modules/ROOT/pages/jdbc-tracing.adoc index 2676ddbd29..edbf647fd1 100644 --- a/modules/ROOT/pages/jdbc-tracing.adoc +++ b/modules/ROOT/pages/jdbc-tracing.adoc @@ -85,13 +85,14 @@ In this example, the custom `traceLevel` attribute for the DB2 JCC driver is set The following subsections contain JDBC driver specific configuration. * <<#DB2JCC,DB2 JCC>> + ** <<#DB2Custom,DB2 JCC customized tracing>> * <<#Derby,Derby>> * <<#InformixJDBC,Informix using JDBC>> * <<#InformixDB2JCC,Informix using DB2 JCC>> * <<#SQLServerJDBCdriver,Microsoft SQL Server JDBC driver>> * <<#SQLServerDataDirectdriver,Microsoft SQL Server DataDirect driver>> * <<#Oracle,Oracle>> - ** <<#OracleCustom, Oracle customized tracing>> + ** <<#OracleCustom,Oracle customized tracing>> * <<#PostgreSQL,PostgreSQL>> * <<#Sybase,Sybase>> * <<#Otherdatabases,Other databases>> @@ -113,6 +114,35 @@ The DB2 JCC does not support the `java.util.logging` library. This driver has it For more information about valid values for the `traceLevel` attribute, see https://www.ibm.com/support/pages/collecting-data-tracing-ibm-data-server-driver-jdbc-and-sqlj[Table 1. DB2 JDBC trace constants]. +[#DB2Custom] +=== DB2 JCC customized tracing + +By default, DB2 JCC driver tracing is combined with Liberty tracing because the Liberty-provided DB2 logwriter directs trace output to the same file. However, Liberty also offers the option to separate DB2 JCC trace from Liberty trace. You can use this option to provide a stand-alone DB2 JCC JDBC trace to DB2 support, if needed. + +You can set this customized tracing for each configured DataSource in your `server.xml` file, as shown in the following example: + +[source, xml] +---- + + + + + +---- + +The following attributes customize the configuration of the DB2 driver trace output: + +- `traceLevel` (required): This property specifies the level of trace. +- `traceDirectory` (required): This property specifies the directory where trace is written. +- `traceFile` (required): This property specifies the name of the trace output file. +- `traceFileAppend` (optional): This property specifies whether to append to (`true`) or overwrite (`false`) the trace output to the specified file. Default value is `false`. +- `traceOption` (optional) : When this property is set to `0`, the `traceFileSize` and `traceFileCount` properties are ignored, and a single trace file with no size limit is generated. To enable circular tracing, set this property to `1`. Default value is `0`. +- `traceFileSize` (optional) : This property specifies the maximum size of each trace file, for circular tracing (in bytes). Default value is `10485760` (10 MB). +- `traceFileCount` (optional) : This property specifies the maximum number of trace files for circular tracing. Default value is `2`. + +For more information about these properties and other configuration settings, see link:https://www.ibm.com/docs/en/db2/latest?topic=information-data-server-driver-jdbc-sqlj-configuration-properties[IBM Data Server Driver for JDBC and SQLJ configuration properties]. [#Derby] === Derby @@ -232,7 +262,7 @@ Add the following required properties to the `jvm.options` file to enable a new - `oracleLogFileName` : This property specifies the file name for custom logging. For example, `oracle.log`. - `oracleLogPackageName` : This property specifies the package to trace. For example, `oracle`, `oracle.jdbc`, or `oracle.net` -You can also customize the configured trace in the `jvm.options` file by using optional properties. +You can also customize the configured trace in the `jvm.options` file by using optional properties. [source, txt] ---- diff --git a/modules/ROOT/pages/log-trace-configuration.adoc b/modules/ROOT/pages/log-trace-configuration.adoc index dbfd064b72..fd459651c4 100644 --- a/modules/ROOT/pages/log-trace-configuration.adoc +++ b/modules/ROOT/pages/log-trace-configuration.adoc @@ -50,7 +50,7 @@ The following sections provide more information about configuring your Open Libe [#mptel] == Logging 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[Enable observability 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[Collect logs, metrics, and traces with OpenTelemetry]. [#configuaration] == Logging configuration diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index a39e4a2372..61db38b80b 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2024 IBM Corporation and others. +// Copyright (c) 2024, 2025 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/ @@ -49,7 +49,7 @@ If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false [#runtime] === Enabling OpenTelemetry for an Open Liberty runtime with a single application -When your Open Liberty runtime hosts only one application, you can enable OpenTelemetry at the runtime level to collect and export logs, metrics, and traces for both the runtime and the application. +When your Open Liberty runtime hosts only one application, as is typical in containerized environments, you can enable OpenTelemetry at the runtime level. This configuration collects and exports logs, metrics, and traces for both the runtime and the application. . Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of your `server.xml` file. @@ -64,7 +64,7 @@ After you enable the MicroProfile Telemetry feature and set this system property [#app] === Enabling OpenTelemetry for multiple applications in the same Open Liberty runtime -When your Liberty runtime hosts multiple applications, you might choose to enable OpenTelemetry to collect logs, metrics, and traces at the application level for each application. Although this option does not collect runtime-level telemetry, it gives you fine-grained control of the data you collect for each application. +When your Liberty runtime hosts multiple applications, which is typically associated with virtual machine environments, you might choose to enable OpenTelemetry at the application level for each application. Although this option does not collect runtime-level telemetry, it gives you fine-grained control of the data you collect for each application. . Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature version 2.0 or later in the `featureManager` element of the `server.xml` file of each application that you want to collect telemetry for. diff --git a/modules/ROOT/pages/microservice-observability-metrics.adoc b/modules/ROOT/pages/microservice-observability-metrics.adoc index 33f10988ec..0d5458687f 100644 --- a/modules/ROOT/pages/microservice-observability-metrics.adoc +++ b/modules/ROOT/pages/microservice-observability-metrics.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2019, 2023 IBM Corporation and others. +// Copyright (c) 2019, 2025 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/ @@ -13,9 +13,13 @@ :page-type: general = Microservice observability with metrics -Open Liberty uses MicroProfile Metrics to provide metrics that describe the internal state of many Open Liberty components. +Open Liberty can use MicroProfile Metrics to provide metrics that describe the internal state of many Open Liberty components. MicroProfile Metrics provides a `/metrics` endpoint from which you can access all metrics that are emitted by an Open Liberty runtime and deployed applications. +As an alternative to MicroProfile metrics, you can collect and export metrics with MicroPRofile Telemetry using the OpenTelemetry protocol. When you enable OpenTelemetry for Open Liberty, a default set of metrics is automatically collected and exported according to the configured OpenTelemetry exporter settings. The advantage of using MicroPRofile Telemetry is that it provides a single comprehensive solution for traces, metrics, and logging. For more information, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. + +== Viewing metrics from the MicroProfile Metrics endpoints + When MicroProfile Metrics is enabled and an application is running, you can view metric data from any browser by accessing the `/metrics` endpoint. An example of this endpoint is `\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 <>. diff --git a/modules/ROOT/pages/observability.adoc b/modules/ROOT/pages/observability.adoc index a9ca003580..4b3bfd5558 100644 --- a/modules/ROOT/pages/observability.adoc +++ b/modules/ROOT/pages/observability.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2019, 2023 IBM Corporation and others. +// Copyright (c) 2019, 2025 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/ @@ -6,43 +6,49 @@ // Contributors: // IBM Corporation // -:page-description: Building observability into applications externalizes the internal status of a system so operations teams can monitor systems more effectively. Open Liberty provides a robust framework for building observable applications and integrates with numerous third party monitoring tools. +:page-description: Building observability into applications externalizes the internal status of a system so operations teams can monitor systems more effectively. Open Liberty provides a robust framework for building observable applications and integrates with numerous third-party monitoring tools. :seo-title: Observability - OpenLiberty.io -:seo-description: Building observability into applications externalizes the internal status of a system so operations teams can monitor systems more effectively. Open Liberty provides a robust framework for building observable applications and integrates with numerous third party monitoring tools. +:seo-description: Building observability into applications externalizes the internal status of a system so operations teams can monitor systems more effectively. Open Liberty provides a robust framework for building observable applications and integrates with numerous third-party monitoring tools. :page-layout: general-reference :page-type: general = Observability -When applications are observable, operations teams can identify and understand the root causes of bugs, bottlenecks, and other inefficiencies. Open Liberty provides a robust framework for developing observable applications and integrates with numerous third-party monitoring tools. +Observability, the ability to understand the internal state of a system by examining its outputs, is a key aspect of maintaining high-performing, resilient microservices. When applications are observable, operations teams can quickly identify the root causes of bugs, bottlenecks, and other inefficiencies. -With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. +Open Liberty provides a robust framework for developing observable applications through health checks, metrics, logging, and tracing. -The following topics provide information to help you develop observable applications with Open Liberty. +== Health checks: Monitoring service availability -//// -xref:prepare-mptelemetry.adoc[Customize your application telemetry with the OpenTelemetry API]:: -Before you manually instrument your code to use MicroProfile Telemetry to collect metrics and traces, 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. -//// +A health check is a special REST API implementation that validates the status of a microservice and its dependencies. Health checks help prevent downtime, reduce errors, and ensure system reliability. They monitor the availability and performance of individual services, detecting issues before they impact users. Health checks are an important tool for managing cloud native applications because they can communicate the status of an application container to the host cloud platform. Health checks report whether an application is running, ready, or has successfully started up. The cloud platform monitor service can then use this information to stop or restart certain containers to keep the system running efficiently. -xref:custom-mptelemetry-metrics.adoc[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. +You can configure health checks for your Open Liberty applications with xref:health-check-microservices.adoc[MicroProfile Health]. With MicroProfile Health, microservices can self-check their health and publish their overall status to a defined endpoint. -xref:telemetry-trace.adoc[Code instrumentation for MicroProfile Telemetry tracing]:: -After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code. You can instrument your code automatically, manually, or by using the Java agent. +== Metrics: Measuring performance -//// -xref:mptelemetry-logging.adoc[Write logs with MicroProfile Telemetry logging]:: -You can use MicroProfile Telemetry to mange your logs, along with traces and metrics. When you enable the MicroProfile Telemetry feature version 2.0 or later, MicroProfile Telemetry automatically collects any logs that are sent to the `java.util.logging` API. -//// +Metrics are quantitative measurements that provide insights into the state and performance of your microservice. Operations teams use metrics to track key performance indicators (KPIs) such as response times, error rates, and throughput. By collecting and analyzing metrics, they can identify trends, spikes, and anomalies that might indicate potential issues or areas for optimization. Metrics provide real-time statistics that you can analyze with specialized monitoring tools, such as Prometheus and Grafana. -xref:health-check-microservices.adoc[Health checks for microservices]:: -A health check is a special REST API implementation that you can use to validate the status of a microservice and its dependencies. With MicroProfile Health, microservices can self-check their health and publish their overall status to a defined endpoint. +When you enable MicroProfile Telemetry 2.0 or later, Open Liberty automatically collects and exports a default set of metrics. For more information about these metrics, see the xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. Additionally, you can use the OpenTelemetry API to xref:custom-mptelemetry-metrics.adoc[define custom metrics] in your application code, if needed. Open Liberty also supports collecting metrics with MicroProfile Metrics. However, MicroProfile Telemetry provides a comprehensive solution for traces, metrics, and logging. -xref:microservice-observability-metrics.adoc[Microservice observability with MicroProfile metrics]:: -Open Liberty uses MicroProfile Metrics to provide metrics that describe the internal state of many Open Liberty components. MicroProfile Metrics provides a `/metrics` endpoint from which you can access all metrics that are emitted by an Open Liberty server and deployed applications. +== Logging: Understanding application behavior -xref:micrometer-metrics.adoc[Choose your own monitoring tools with MicroProfile Metrics]:: -The Open Liberty MicroProfile Metrics 5.0 feature uses embedded Micrometer metrics technology to transfer metric data to multiple third-party monitoring systems. Starting in MicroProfile Metrics 5.0, you can instrument your code in a standardized way to visualize metrics results in the monitoring system of your choice. +Logging is the process of recording events within the system, capturing detailed information about what happened, when, and why. It's essential for debugging, auditing, and understanding application behavior. Logs provide a wealth of information, including errors, warnings, and debug messages. Logs can provide context for issues that are discovered in metric data. Log messages are also included in the spans that make up distributed traces. +Open Liberty has a xref:log-trace-configuration.adoc[unified logging component] that handles messages that are written by applications and the runtime, and provides First Failure Data Capture (FFDC) capability. Logging data that is written by applications by using the `System.out`, `System.err`, or `java.util.logging.Logger` streams is combined into the Open Liberty runtime logs by default. + +== Tracing: Following requests + +While logs contain data about specific events in a system, traces represent the requests that trigger these events. A trace consists of multiple spans, each of which represents a single operation in a request, such as an HTTP request or a database call. A span includes a name, time-related data, log messages, and other metadata about what occurs during a transaction. When you implement tracing in your microservices, operations teams can better identify bottlenecks, debug complex issues, and optimize inter-service communication. + +OpenTelemetry, an open source framework, provides a standardized approach to collect, process, and export trace data. When you enable OpenTelemetry for Open Liberty, Jakarta RESTful Web Services and JAX-RS applications are instrumented for trace by default. Spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. These spans are automatically exported according to the configured OpenTelemetry exporter settings. + +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 OpenTelemetry API. Alternatively, you can attach the OpenTelemetry Java agent to any Java 8+ application. For more information about these options, see xref:telemetry-trace.adoc[Code instrumentation for MicroProfile Telemetry tracing]. + +== MicroProfile Telemetry: A unified solution for observability + +With MicroProfile Telemetry 2.0 and later, you can manage Open Liberty logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol. For more information, see xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. + +Implementing observability in your microservices involves a combination of metrics, logging, and tracing. With Open Liberty and OpenTelemetry, you can gain valuable insights into your application behavior so you can identify and resolve issues quickly. Observability is not a one-time task but an ongoing process that must be integrated into your development lifecycle. By making observability a priority, you can build more reliable, performant, and maintainable microservices. For hands-on tutorials on different observability configurations for Open Liberty, check out our link:/guides/#observability[Observability guides]. + +// assisted by watsonx latest with latest GenAI contribution: Granite-3-8b-instruct diff --git a/modules/ROOT/pages/rest-alternatives.adoc b/modules/ROOT/pages/rest-alternatives.adoc index ff55fe94f5..abf4d093d5 100644 --- a/modules/ROOT/pages/rest-alternatives.adoc +++ b/modules/ROOT/pages/rest-alternatives.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2020,2021 IBM Corporation and others. +// Copyright (c) 2020,20225 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/ @@ -13,21 +13,18 @@ :page-type: general = Alternatives to REST for client-server communications -Although REST is a widely adopted pattern for communications among microservices, Open Liberty supports alternative options that might be better suited for some application scenarios. These alternatives include GraphQl, gRPC, and WebSocket. +Although REST is a widely adopted pattern for communications among microservices, Open Liberty supports alternative options that might be better suited for some application scenarios. These alternatives include GraphQL, gRPC, and WebSocket. -Despite the ubiquity of REST-style communication among microservices, REST comes with tradeoffs in capability and performance that can make it a less than ideal solution for some use cases. Issues such as over-fetching and under-fetching of data, lack of real-time communication, and tight coupling between client and server can lead to performance and maintenance concerns for certain types of applications. To address these issues, developers can use alternative protocols and technologies that specifically address the shortcomings of REST. +REST is by far the most common architectural style for microservices, thanks to its simplicity, flexibility, and scalability. However, it comes with tradeoffs that can make it a less than ideal solution for some use cases. Issues such as over-fetching and under-fetching of data, lack of real-time communication, and tight coupling between client and server can lead to performance and maintenance concerns for certain types of applications. To address these issues, you can use alternative protocols and frameworks that specifically address the shortcomings of REST. -For example, GraphQL is an open source data query and manipulation language for APIs that directly addresses problems with over-fetching and under-fetching of data that might occur with REST APIs. Similarly, the WebSocket protocol enables real-time bidirectional communication between a server and one or more clients, which is not feasible in REST architecture. +* xref:microprofile-graphql.adoc[GraphQL]: This open source query language and runtime can simplify retrieving data from multiple sources, such as APIs, databases, and other services. It directly addresses problems with over-fetching and under-fetching of data that might occur with REST APIs. +* xref:web-socket.adoc[WebSocket]: This protocol enables real-time bidirectional communication between a server and one or more clients, which is not feasible in REST architecture. +* xref:grpc-services.adoc[gRPC]: This framework provides efficient data serialization and multiplexing capabilities for high-performance applications that require high throughput and low latency. It also enables efficient communication between services and applications in various languages and platforms. +Ultimately, the framework that you choose depends on the specific needs of your application, including factors like performance requirements, data complexity, and the technologies you're already using. -The following topics provide information about REST alternatives that you can implement with Open Liberty. +== See also -xref:microprofile-graphql.adoc[Build GraphQL applications with MicroProfile GraphQL]:: -MicroProfile GraphQL is an API for building services that exercise fine-grained control over the data that they request and receive. A GraphQL service can simplify data retrieval by collating data from multiple sources into a single object. - -xref:grpc-services.adoc[Provide and consume gRPC services on Open Liberty]:: -gRPC is an open source remote procedural call (RPC) framework that connects clients and services in language-agnostic way. You can provide and consume gRPC services from your web applications that run on Open Liberty. - -xref:web-socket.adoc[Send bidirectional messages between services with WebSocket]:: -The WebSocket protocol supports real-time bidirectional messaging between a client and server. The Open Liberty Jakarta WebSocket feature supports applications that use this protocol. +link:/guides/#rest_alternatives[Guides: REST alternatives] +// assisted by watsonx with latest GenAI contribution: Granite-3-8b-instruct diff --git a/modules/ROOT/pages/telemetry-trace.adoc b/modules/ROOT/pages/telemetry-trace.adoc index 3d05346afd..f9e0d60b7d 100644 --- a/modules/ROOT/pages/telemetry-trace.adoc +++ b/modules/ROOT/pages/telemetry-trace.adoc @@ -1,4 +1,4 @@ -// Copyright (c) 2024 IBM Corporation and others. +// Copyright (c) 2024, 2025 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/ @@ -14,16 +14,16 @@ After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code. You can instrument your code automatically, manually, or by using the Java agent. -* <<#auto, Automatic instrumentation>>, which automatically traces your JAX-RS or RESTful web services. -* <<#manual, Manual instrumentation>>, which enables you to start and end telemetry spans manually for applications that are not JAX-RS or RESTful web services. -* <<#agent, Agent instrumentation>>, which automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>. +* <<#auto, Automatic instrumentation>> automatically traces your JAX-RS or RESTful web services when you enable OpenTelemetry. +* <<#manual, Manual instrumentation>> enables you to start and end telemetry spans manually for applications that are not JAX-RS or RESTful web services. +* <<#agent, Agent instrumentation>> automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>. [#auto] == Automatic instrumentation With automatic instrumentation, you can observe traces without modifying the source code in your applications. All that you need to do is configure runtime as described in xref:microprofile-telemetry.adoc[Collect logs, metrics, and traces with OpenTelemetry]. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. -In Open Liberty version 23.0.0.11 and later, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. +When you use automatic instrumentation, spans are also automatically generated for incoming HTTP requests, including static files, servlets, and JSPs. [#manual] == Manual instrumentation diff --git a/modules/reference/pages/diff/mp-61-70-diff.adoc b/modules/reference/pages/diff/mp-61-70-diff.adoc index ac1f480b7e..01d4f47a04 100644 --- a/modules/reference/pages/diff/mp-61-70-diff.adoc +++ b/modules/reference/pages/diff/mp-61-70-diff.adoc @@ -18,7 +18,7 @@ = Differences between MicroProfile 7.0 and 6.1 -MicroProfile 7.0 is a major release. It introduces updated MicroProfile specifications, including MicroProfile Telemetry 2.0, MicroProfile Rest Client 4.0, MicroProfile OpenAPI 4.0, and MicroProfile Fault Tolerance 4.1. +MicroProfile 7.0 is a major release. It introduces updated MicroProfile specifications, including MicroProfile Telemetry 2.0, MicroProfile Rest Client 4.0, MicroProfile OpenAPI 4.0, and MicroProfile Fault Tolerance 4.1. This release introduces several important changes: @@ -234,5 +234,42 @@ MicroProfile Telemetry 2.0 provides runtime-level telemetry. To enable this feat If you do not use system properties or environment variables for configuration, runtime-level metrics and logs cannot be collected. Using other available MicroProfile Config properties cannot enable the collection of these metrics and logs. -For more information on OpenTelemetry, see xref:ROOT:microprofile-telemetry.adoc[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. +=== MicroProfile Telemetry 2.0 and Java SE 8 + +Unlike previous versions of MicroProfile Telemetry, version 2.0 supports Java SE 8 in certain configurations. + +MicroProfile Telemetry 2.0 (`mpTelemetry-2.0`) is included in the feature:microProfile-7.0[display=MicroProfile 7.0 umbrella feature] and xref:reference:platform/MicroProfile.adoc[platform], which do not support Java SE 8. However, MicroProfile Telemetry 2.0 is compatible with the following earlier versions of MicroProfile that do support Java SE 8: + +- feature:microProfile-5.0[display=MicroProfile 5.0] +- feature:microProfile-4.1[display=MicroProfile 4.1] +- feature:microProfile-1.4[display=MicroProfile 1.4] +Although `mpTelemetry-2.0` is not automatically enabled by these umbrella features, if you independently enable it alongside any of them, the configuration supports Java SE 8. + +For example, the following `featureManager` configuration in your `server.xml` file enables `mpTelemetry-2.0` in a Java SE 8 environment: + +[source.xml] +---- + + microProfile-5.0 + mpTelemetry-2.0 + ... + +---- + +Alternatively, if you are using xref:reference:feature/versionless-features.adoc[versionless features], you must likewise independently enable the versioned `mpTelemetry-2.0` feature, along with your chosen platform feature, if you want to use it with Java SE 8. The following example shows the `microProfile-5.0` platform feature and several example versionless features enabled together with `mpTelemetry-2.0`: + +[source.xml] +---- + + microProfile-5.0 + mpTelemetry-2.0 + mpHealth + mpMetrics + ... + +---- + +In this example, the versionless `mpHealth` and `mpMetrics` features are automatically resolved to compatible versions by the `microProfile-5.0` platform. The versioned `mpTelemetry-2.0` feature gets the benefit of Java SE 8 support that the platform provides. + +For more information on OpenTelemetry, see xref:ROOT:microprofile-telemetry.adoc[Collecting and exporting logs, metrics, and traces with OpenTelemetry]. diff --git a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc index 7098549d39..b7cff10381 100644 --- a/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc +++ b/modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc @@ -10,7 +10,7 @@ The following example demonstrates how to enable OpenTelemetry at the runtime le otel.sdk.disabled=false ---- -When you enable the MicroProfile Telemetry feature and set this property, your system is ready to collect and export logs, metrics, and traces. +When you enable the MicroProfile Telemetry feature and set this property, your system is ready to collect and export logs, metrics, and traces. By default, all OpenTelemetry data is exported by using the OpenTelemetry Protocol (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative exporter settings by specifying system properties or environment variables. For more information, see xref:ROOT:microprofile-telemetry.adoc#config[OpenTelemetry settings and configuration]. [#logs] === Collect logs from a specified source @@ -41,3 +41,41 @@ xref:ROOT:class-loader-library-config.adoc#3rd-party[Enable third-party APIs] fo ---- + +=== Use MicroProfile Telemetry 2.0 with Java SE 8 + +Unlike previous versions of MicroProfile Telemetry, version 2.0 supports Java SE 8 in certain configurations. + +MicroProfile Telemetry 2.0 (`mpTelemetry-2.0`) is included in the feature:microProfile-7.0[display=MicroProfile 7.0 umbrella feature] and xref:reference:platform/MicroProfile.adoc[platform], which do not support Java SE 8. However, MicroProfile Telemetry 2.0 is compatible with the following earlier versions of MicroProfile that do support Java SE 8: + +- feature:microProfile-5.0[display=MicroProfile 5.0] +- feature:microProfile-4.1[display=MicroProfile 4.1] +- feature:microProfile-1.4[display=MicroProfile 1.4] + +Although `mpTelemetry-2.0` is not automatically enabled by these umbrella features, if you independently enable it alongside any of them, the configuration supports Java SE 8. + +For example, the following `featureManager` configuration in your `server.xml` file enables `mpTelemetry-2.0` in a Java SE 8 environment: + +[source.xml] +---- + + microProfile-5.0 + mpTelemetry-2.0 + ... + +---- + +Alternatively, if you are using xref:reference:feature/versionless-features.adoc[versionless features], you must likewise independently enable the versioned `mpTelemetry-2.0` feature, along with your chosen platform feature, if you want to use it with Java SE 8. The following example shows the `microProfile-5.0` platform feature and several example versionless features enabled together with `mpTelemetry-2.0`: + +[source.xml] +---- + + microProfile-5.0 + mpTelemetry-2.0 + mpHealth + mpMetrics + ... + +---- + +In this example, the versionless `mpHealth` and `mpMetrics` features are automatically resolved to compatible versions by the `microProfile-5.0` platform. The versioned `mpTelemetry-2.0` feature gets the benefit of Java SE 8 support that the platform provides. diff --git a/modules/reference/pages/feature/openidConnectClient/examples.adoc b/modules/reference/pages/feature/openidConnectClient/examples.adoc index 88eea01d92..9ed1d60e87 100644 --- a/modules/reference/pages/feature/openidConnectClient/examples.adoc +++ b/modules/reference/pages/feature/openidConnectClient/examples.adoc @@ -109,8 +109,8 @@ The following `server.xml` file example shows two Open ID connect client configu [source,xml] ---- - - + + ... @@ -121,9 +121,9 @@ The following `server.xml` file example shows two Open ID connect client configu Open Liberty selects the `openidConnectClient` configuration to use for a JWT request according to the following algorithm. 1. If the authentication filter for a `openidConnectClient` configuration matches the request, choose that configuration. -2. If the issuer claim from the JWT matches the `issuer` attribute in only one `openidConnectClient` configuration element, choose that configuration. -3. If the issuer claim from the JWT matches the `issuer` attribute in multiple `openidConnectClient` configuration elements, choose the first configuration that matches. -4. If the issuer claim from the JWT does not match the `issuer` attribute in any `openidConnectClient` configuration elements, choose between all of the configuration elements in a nondeterministic manner. +2. If the issuer claim from the JWT matches the `issuerIdentifier` attribute in only one `openidConnectClient` configuration element, choose that configuration. +3. If the issuer claim from the JWT matches the `issuerIdentifier` attribute in multiple `openidConnectClient` configuration elements, choose the first configuration that matches. +4. If the issuer claim from the JWT does not match the `issuerIdentifier` attribute in any `openidConnectClient` configuration elements, choose between all of the configuration elements in a nondeterministic manner. Claim to subject mapping:: If you do not define claim-to-subject mapping, the following default rules apply.