edits

#7655

modules/ROOT/pages/microprofile-telemetry.adoc

@@ -12,28 +12,19 @@
 :page-type: general
 = OpenTelemetry
 
-The OpenTelemetry project is a collection of open source vendor-independent tools, APIs, and SDKs for creating and managing logs, metrics, and trace 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 this data 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 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 export it to backend services of your choice for visualization and monitoring. The Collector includes various exporters for different open source or commercial services, such as sending your traces to Jaeger or your metrics to Prometheus.
-
-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 1.1 and earlier enables only the collection of traces and only at the application level.
-
-When you enable OpenTelemetry for Open Liberty, by default, all telemetry 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 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.
 
 [#global]
 == Collecting and exporting logs, metrics, and traces with OpenTelemetry
 
-To use OpenTelemetry to collect and export logs, metrics, and traces 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 Open Liberty 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 as 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="3,3,6a,3a"]
+[options="header"cols="4,2,6a,3a"]
 |===
 |Use case| Configuration level | Description | Configuration sources
 
@@ -53,7 +44,7 @@ To use OpenTelemetry to collect and export logs, metrics, and traces in your Ope
 
 === Enabling OpenTelemetry for an Open Liberty runtime with a single application
 
-When your Liberty runtime hosts only one application, you can enable Open Telemetry 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, you can enable Open Telemetry at the runtime level to collect and export 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.
 +
@@ -65,13 +56,13 @@ When your Liberty runtime hosts only one application, you can enable Open Teleme
 </featureManager>
 ----
 
-* Set `otel.sdk.disabled=false` as a runtime-level property, for example, in the `bootstrap.properties` file:
+* Set `otel.sdk.disabled=false` as a runtime-level property, for example, in the xref:reference:config/server-configuration-overview.adoc#bootstrap-properties[bootstrap.properties] file:
 +
 ----
 otel.sdk.disabled=false
 ----
 
-After you enable the MicroProfile Telemetry feature and set this system property, your runtime is ready to start collecting and exporting logs, metrics, and traces from the application and the runtime. For more information, see the individual sections for logs, metrics, and traces.
+After you enable the MicroProfile Telemetry feature and set this system property, your runtime is ready to start collecting and exporting logs, metrics, and traces from the application and the runtime. For more information, see <<config,OpenTelemetry settings and configuration>>.
 
 === Enabling OpenTelemetry for multiple applications in the same Open Liberty runtime
 
@@ -89,10 +80,7 @@ When your Liberty runtime hosts multiple applications, you can enable OpenTeleme
 
 * Set `otel.sdk.disabled=false` as an application-level property in the `microprofile-config.properties` file of each application.
 +
-You can also set the `otel.service.name` property in each application to assign a service name to the telemetry data that is collected. This service name helps you identify the source of the data from each application when you send your data to monitoring and analytics tools.
-+
-The following examples show an application scenario where two applications on the same Open Liberty runtime are configured to collect and export telemetry data at the application level. The data from each application is assigned a unique service name to clarify which application the data comes from.
-
+The following examples show an application scenario where two applications on the same Open Liberty runtime are configured to collect and export telemetry data at the application level. These examples also set the `otel.service.name` property in each application to assign a service name to the telemetry data that is collected. This service name helps you identify the source of the data from each application when you send your data to monitoring and analytics tools.
 +
 Application 1 `microprofile-config.properties` file:
 +
@@ -110,9 +98,7 @@ otel.service.name=A2
 +
 This configuration creates all telemetry from Application 1 with the service name `A1`, and from Application 2 with the service name `A2`.
 
-* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime.
-+
-Any configuration in the system properties and server environment variables takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime.
+* You can also use a combination of runtime-level and application-level configuration, so that some settings apply to all applications on the runtime, while others are specific to each application. This strategy can save you from having to duplicate general configuration settings in multiple applications on the same runtime. Any runtime-level configuration takes precedence over application-level configuration. Therefore, you can enable OpenTelemetry and assign a service name individually for each application, but specify other settings at the runtime level to apply globally to all applications on the runtime.
 +
 For example, you might want to collect a unique set of telemetry data for each application in the runtime, but have all applications share the same OpenTelemetry exporter. You can set the OpenTelemetry exporter at the runtime-level in the `bootstrap.properties` file:
 +
@@ -129,23 +115,18 @@ otel.service.name=<serviceName>
 +
 This configuration enables an application-level telemetry with a unique service name for each application, while all applications in the runtime use the `myExporter` OpenTelemetry exporter.
 
-After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabled=false` property for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces. For more information, see the individual sections for logs, metrics, and traces.
+After you enable the MicroProfile Telemetry feature and set the `otel.sdk.disabled=false` property for each application on the runtime, your applications are ready to start collecting and exporting logs, metrics, and traces.
 
+[#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 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].
 
-For information about commonly-used configuration properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroPRofile Config properties: MicroPRofile Telemetry].
-
-For common configuration examples, see the feature:mptelemtry[display=MicroProfile Telemetry] feature page.
+For information about commonly-used configuration properties, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroPRofile Config properties: MicroPRofile Telemetry]. For common configuration examples, see the feature:mptelemtry[display=MicroProfile Telemetry] feature page.
 
 [#traces]
 == Trace
 
-One way to increase observability of an application is by emitting traces. Traces represent requests and consist of multiple spans. A span represents a single operation in a request. It includes a name, time-related data, log messages, and metadata about what happens during a transaction.
-
 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].
@@ -163,10 +144,9 @@ By default, the OpenTelemetry Simple logRecord Processor is enabled, so the reco
 [#metrics]
 == Metrics
 
-By default, OpenTelemetry exports metric data at an interval of 60 seconds. You can modify the export interval and other default settings by using MicroProfile config properties.
-
 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].
 
+By default, OpenTelemetry exports metric data at an interval of 60 seconds. You can modify the export interval and other default settings by using MicroProfile config properties.
 
 == See also