edits

#7655

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

@@ -10,20 +10,18 @@
 :page-type: general
 :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, 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-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
 
-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.
+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 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 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[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.
 
-[#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].
-
+  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.

modules/ROOT/pages/microprofile-telemetry.adoc

@@ -12,31 +12,31 @@
 :page-type: general
 = OpenTelemetry
 
-The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage this data in a standardized way by using the OpenTelemetry protocol.
+The OpenTelemetry project is a collection of open source, vendor-independent resources for collecting and managing application telemetry data. With Open Liberty and MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and traces in a standardized way by using the OpenTelemetry protocol.
 
-OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your applications and export it to backend services of your choice for visualization and monitoring. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as Jaeger, Zipkin, and Prometheus. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables.
+OpenTelemetry provides a link:https://opentelemetry.io/docs/collector/[collector] component that can receive telemetry data from your applications and export it to backend services of your choice for monitoring and analysis. By default, all OpenTelemetry data is exported to the Open Telemetry Protocol (OTLP). OTLP defines the encoding of telemetry data and the protocol that is used to exchange data between a client and server. Many backend services accept OTLP data without requiring conversion, but OpenTelemtry also provides a collection of service-specific exporters for popular open source and commercial services, such as https://www.elastic.co/observability/log-monitoring[Elastic], link:https://zipkin.io/[Zipkin], and link:https://prometheus.io/[Prometheus]. You can configure global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables.
 
-OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature, which enables a collector that you can configure with MicroProfile Config properties and other system properties or environment variables. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry1.1 and earlier enables only the collection of traces and only at the application level.
+OpenTelemetry is implemented in Open Liberty through the feature:mptelemtry[display=MicroProfile Telemetry] feature. When you enable the MicroProfile Telemetry feature 2.0 or later and specify the required configuration property, Open Liberty automatically collects and exports logs, traces, and metrics at the application or runtime level. For many common application scenarios, no changes are needed in your application code to collect this data. MicroProfile Telemetry1.1 and earlier enables only the collection of traces and only at the application level.
 
 [#global]
 == Collecting and exporting logs, metrics, and traces with OpenTelemetry
 
-To collect and export logs, metrics, and traces with OpenTelemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether your runtime hosts a single application or multiple applications, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred as it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option.
+To collect and export logs, metrics, and traces with OpenTelemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify the `otel.sdk.disabled=false` system property in one of the valid configuration sources. Depending on whether your runtime hosts a single application or multiple applications, you can specify this property at the runtime level or the application level. In most cases, runtime-level configuration is preferred because it includes both runtime-level telemetry and application-specific telemetry. The following table summarizes the benefits and use cases for each option.
 
 .OpenTelemetry configuration options
 [options="header"cols="4,2,6a,3a"]
 |===
-|Use case| Configuration level | Description | Configuration sources
+|Configuration level | Use case | Description | Configuration sources
 
-| One application per Liberty runtime
 | Runtime level
+| One application per Liberty runtime
 | Collects and emits telemetry from both the runtime and the application.
 | * `bootstrap.properties` file
 * `jvm.options` file
 * `server.env` file
 
-| Multiple applications in the same Liberty runtime
 | Application level
+| Multiple applications in the same Liberty runtime
 | Collects and emits telemetry for a single application and does not include runtime-level data. Provides fine-grained control over data collection for each application.
 | * `microprofile-config.properties` file
 * `appProperties` attribute for the config:application[] element in the `server.xml` file.
@@ -66,7 +66,7 @@ After you enable the MicroProfile Telemetry feature and set this system property
 
 === Enabling OpenTelemetry for multiple applications in the same Open Liberty runtime
 
-When your Liberty runtime hosts multiple applications, you can 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, 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.
 
 * 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.
 +
@@ -120,31 +120,32 @@ After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabl
 [#config]
 == OpenTelemetry settings and configuration
 
-When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is exported to the Open Telemetry Protocol (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties].
+When you enable OpenTelemetry for Open Liberty, by default, all telemetry data is to the link:https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md[Open Telemetry Protocol] (OTLP) at the `\http://localhost:4317` endpoint. You can configure alternative global or data-specific exporter settings by specifying MicroProfile Config properties and other system properties or environment variables. Open Liberty supports all link:https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties[OpenTelemtry Java configuration properties].
 
-For information about commonly-used configuration properties for global, logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry].
+For information about commonly-used configuration properties for logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry].
 
 [#traces]
 === Trace
 
 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 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#t[Code instrumentation for MicroProfile Telemetry tracing].
+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].
 
 [#logs]
 === Logs
 
-OpenTelemetry automatically collects any logs that are sent to the `java.util.logging` API. Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry automatically collects messages, but you can configure the sources that it collects from in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source].
+OpenTelemetry automatically collects any logs that are sent to the `java.util.logging` API. Any messages that are logged at a `java.util.logging.Level` log level of `INFO` and above are considered messages. Levels below `INFO` are considered trace. By default, OpenTelemetry logging automatically collects messages, but you can configure it to collect from other sources in your `server.xml` file. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#_collect_logs_from_a_specified_source[Collect logs from a specified source].
 
-For information about Liberty message event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list].
+For information about Liberty log event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list].
 
+////
 By default, the OpenTelemetry Simple logRecord Processor is enabled, so the records are sent immediately. However, if you want to send the records in batches, you can also configure the logging-specific Batch LogRecord Processor properties.
-
+////
 
 [#metrics]
 === Metrics
 
-For a list of metrics that are available for Open Liberty when you enable the MicroProfile Telemetry feature 2.0 or later, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also xref:custom-mptelemetry-metrics.adoc[define custom metrics in your application code].
+When you enable OpenTelemetry  for Open Liberty,  a default set of metrics is automatically collected and exported according to the configured OpenTelemetry settings. For more information about these metrics, see xref:mptelemetry-metrics-list.adoc[MicroProfile Telemetry metrics reference list]. You can also define additional xref:custom-mptelemetry-metrics.adoc[custom metrics] in your application code.
 
 
 == See also

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

@@ -32,7 +32,7 @@ Use metric data to effectively monitor the status of your microservice systems.
 
 You can obtain metrics from applications, the Open Liberty runtime, and the Java virtual machine (JVM). They can be gathered and stored in database tools, such as link:https://prometheus.io/[Prometheus], and displayed on dashboards, such as link:https://grafana.com/[Grafana].
 
-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].
+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[OpenTelemetry].
 
 
 == Filter metrics to gather only the data you need
@@ -62,7 +62,7 @@ To disable all monitoring components, add the following code to your `server.xml
 
 == MicroProfile Telemetry 2.0 and later metrics reference
 
-When the MicroProfile Telemetry feature 2.0 and later is enabled, Open Liberty can send metric data to compatible OpenTelemetry protocol (OTLP) receivers. For more information, see xref:microprofile-telemetry[Enable observability with MicroProfile Telemetry].
+When the MicroProfile Telemetry feature 2.0 and later is enabled, Open Liberty can send metric data to compatible OpenTelemetry protocol (OTLP) receivers.
 
 The table lists the metric types, descriptions and attributes that are available for Open Liberty. Where applicable, the associated monitoring component that you can use to filter the metric is also included.
 The **Features required** column of the table includes the feature or features that must be enabled to obtain that metric data.