Merge pull request #7703 from OpenLiberty/7655-observ-rewrite

edits

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

@@ -14,7 +14,7 @@
 
 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 collecting and emitting metrics with MicroProfile Telemetry, see xref:microprofile-telemetry.adoc[OpenTelemetry].
 
 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].
 

modules/ROOT/pages/microprofile-telemetry.adoc

@@ -1,4 +1,4 @@
-// Copyright (c) 2022 IBM Corporation and others.
+// Copyright (c) 2024 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,7 +14,7 @@
 
 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 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 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 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. 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.
 
@@ -34,6 +34,8 @@ To collect and export logs, metrics, and traces with OpenTelemetry in your Open
 | * `bootstrap.properties` file
 * `jvm.options` file
 * `server.env` file
++
+If you choose to use the `server.env` file, specify the `OTEL_SDK_DISABLED=false` enviroment variable instead of the configuration property.
 
 | Application level
 | Multiple applications in the same Liberty runtime
@@ -120,20 +122,19 @@ 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 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].
+By default, all OpenTelemetry data is exported 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 logs, metrics, and trace settings, see xref:reference:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry].
 
 [#traces]
-=== Trace
+=== Trace defaults
 
 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[Code instrumentation for MicroProfile Telemetry tracing].
 
 [#logs]
-=== Logs
-
+=== Logs defaults
 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 log event fields for OpenTelemetry, see xref:mptel-log-events-list.adoc[MicroProfile Telemetry log events reference list].
@@ -143,11 +144,12 @@ By default, the OpenTelemetry Simple logRecord Processor is enabled, so the reco
 ////
 
 [#metrics]
-=== Metrics
+=== Metrics defaults
 
 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
 
-https://opentelemetry.io/[OpenTelemetry project]
+* xref:telemetry-troubleshooting.adoc[Troubleshooting OpenTelemetry]
+* https://opentelemetry.io/[OpenTelemetry project]

modules/ROOT/pages/microprofile.adoc

@@ -122,7 +122,7 @@ For more information, see xref:microservice-observability-metrics.adoc[Microserv
 === Enable distributed tracing of your microservices
 link:https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-telemetry-1.0/plan%E2%80%A8%E2%80%A822.0.0.10-bet[MicroProfile Telemetry] is based on the https://opentelemetry.io/[OpenTelemetry project], which is a collection of open source vendor-agnostic tools, APIs, and SDKs for creating and managing trace data.
 
-In Open Liberty, MicroProfile Telemetry is supported by the feature:mpTelemetry[display=MicroProfile Telemetry] feature. You can export the data that this feature collects to tracing systems such as Jaeger or Zipkin. For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry].
+In Open Liberty, MicroProfile Telemetry is supported by the feature:mpTelemetry[display=MicroProfile Telemetry] feature. You can export the data that this feature collects to tracing systems such as Jaeger or Zipkin. For more information, see xref:microprofile-telemetry.adoc[OpenTelemetry].
 
 MicroProfile Telemetry replaces MicroProfile OpenTracing. For information about migrating your applications from MicroProfile OpenTracing to MicroProfile Telemetry, see xref:reference:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0].
 

modules/ROOT/pages/mptel-log-events-list.adoc

@@ -14,7 +14,7 @@
 
 MicroProfile Telemetry can collect logging events from the server runtime and applications. You can use these events to gather and analyze data that can help to better understand the behavior of applications.
 
-For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry].
+For more information, see xref:microprofile-telemetry.adoc[OpenTelemetry].
 
 MicroProfile Telemetry can collect the following types of events:
 

modules/ROOT/pages/mptelemetry-logging.adoc

@@ -16,4 +16,4 @@ You can use MicroProfile Telemetry to mange your logs, along with traces and met
 
 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, MicroProfile Telemetry 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].
 
-For more information about configuring MicroProfile Telemetry to collect and emit logs, metrics, and trace, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry].
+For more information about configuring MicroProfile Telemetry to collect and emit logs, metrics, and trace, see xref:microprofile-telemetry.adoc[OpenTelemetry].

modules/ROOT/pages/observability.adoc

@@ -15,7 +15,7 @@
 
 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.
 
-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[Enable observability with MicroProfile Telemetry].
+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[OpenTelemetry].
 
 The following topics provide information to help you develop observable applications with Open Liberty.
 

modules/ROOT/pages/telemetry-trace.adoc

@@ -21,7 +21,7 @@ After you enable MicroProfile Telemetry and configure a trace server, you can in
 [#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#traces[Configuring Open Liberty to use MicroProfile Telemetry to collect traces]. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications.
+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[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.
 
@@ -30,7 +30,7 @@ In Open Liberty version 23.0.0.11 and later, spans are automatically generated f
 
 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 https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API].
 
-However, before you manually instrument your code, 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].
+However, before you manually instrument your code, 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 link:{url-prefix}/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry].
 
 After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API.
 

modules/ROOT/pages/telemetry-troubleshooting.adoc

@@ -1,4 +1,4 @@
-// Copyright (c) 2022 IBM Corporation and others.
+// Copyright (c) 2024 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,7 +12,37 @@
 :page-type: general
 = Troubleshooting OpenTelemetry
 
-The following information can help you determine the cause of common problems and error messages that are associated with OpenTelemetry logs, metrics, and tracing.
+The following information can help you determine the cause of common problems and error messages that are associated with OpenTelemetry logs, metrics, and tracing. To debug issues with your OpenTelemetry logs, metrics, or traces, you can configure this data to export to the console.
+
+
+== Exporting logs, metrics, or traces to the console for debugging purposes
+
+By default, all OpenTelemetry data is exported to the `otlp` exporter. For debugging purposes, you can temporarily change the export destination to the `console.log` file by setting the `otel.<_signal_>.exporter=console` property at the application or the runtime level.
+
+For example, to send all application and runtime traces to the `console.log` file, you might set the following property in the `bootstrap.properties` file:
+
+[source,properties]
+----
+otel.traces.exporter=console
+----
+
+Similarly, to send all application and runtime logs to the `console.log` file, set the following property in the `bootstrap.properties` file:
+
+[source,properties]
+----
+otel.logs.exporter=console
+----
+
+To send all application and runtime metrics to the `console.log` file, set the following property in the `bootstrap.properties` file:
+
+[source,properties]
+----
+otel.metrics.exporter=console
+----
+
+
+If you enabled OpenTelemetry at the application level, and you want to send only the logs, metrics, or traces for a particular application to the console, set the corresponding property in the `microprofile-config.properties` file for the application.
+
 
 Previous spans are incorrectly shown as current or parent spans::
 

modules/reference/pages/diff/mp-50-60-diff.adoc

@@ -130,7 +130,7 @@ In MicroProfile 6.0, MicroProfile Telemetry 1.0 replaces MicroProfile OpenTracin
 
 === Configuration changes
 
-In addition to replacing the `mpOpenTracing-3.0` feature with the `mpTelemtry-1.0` feature in your `server.xml` file, you must provide configuration to allow the MicroProfile Telemetry feature to connect to your distributed trace service. For more information, see xref:ROOT:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry].
+In addition to replacing the `mpOpenTracing-3.0` feature with the `mpTelemtry-1.0` feature in your `server.xml` file, you must provide configuration to allow the MicroProfile Telemetry feature to connect to your distributed trace service. For more information, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry].
 
 You do not need to package a client for your particular tracing service. MicroProfile Telemetry includes exporters for Zipkin, the OpenTelemetry Protocol (OTLP) (which is used by Jaeger since v1.35), and the older Jaeger protocol. If you need to export to a different service, you can provide a custom exporter by using the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/1.19.0/io/opentelemetry/sdk/autoconfigure/spi/traces/ConfigurableSpanExporterProvider.html[ConfigurableSpanExporterProvider service provider interface (SPI)].
 
@@ -188,7 +188,7 @@ Update your application dependencies to remove the OpenTracing API and add the O
 </dependency>
 ----
 
-Just like the MicroProfile OpenTracing 3.0 feature (`mpOpenTracing-3.0`), the MicroProfile Telemetry 1.0 feature (`mpTelemetry-1.0`) feature requires that you xref:ROOT:microprofile-telemetry.adoc#manual[enable third-party APIs] to use the API classes in your application.
+Just like the MicroProfile OpenTracing 3.0 feature (`mpOpenTracing-3.0`), the MicroProfile Telemetry 1.0 feature (`mpTelemetry-1.0`) feature requires that you enable third-party APIs to use the API classes in your application.
 
 The shim converts most calls to the OpenTracing API into calls to the OpenTelemetry API, but it doesn't make the OpenTracing `Tracer` class available for injection.
 To enable injection of the OpenTracing `Tracer` class, you also need to add a CDI Producer Method that uses the shim to provide instances of the class for injection. If CDI discovery is enabled, you can add the following class to your application:

modules/reference/pages/feature/mpTelemetry-2.0/examples.adoc

@@ -45,12 +45,8 @@ If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to c
 ----
 
 
-[#logs-settings]
-=== Log settings
-The following examples show common optional settings to configure the collection and export of OpenTelemetry log data.
-
 [#logs]
-==== Collect logs from a specified source
+=== Collect logs from a specified source
 
 To enable the MicroProfile Telemetry feature to collect logs from different sources in the Open Liberty runtime environment, configure the `source` attribute for the `mpTelemetry` element with a comma-separated list of comma-separated log sources.
 
@@ -66,8 +62,7 @@ To enable the MicroProfile Telemetry feature to collect logs from different sour
 * The attributes and values are case insensitive.
 
 
-[#blrp]
-==== Configure the OpenTelemetry Batch LogRecord Processor
+
 
 
 

modules/reference/pages/feature/mpTelemetry/description.adoc

@@ -1,3 +1,3 @@
 For information about migrating from MicroProfile Open Tracing to MicroProfile Open Telemetry, see xref:diff/mp-50-60-diff.adoc#telemetry[Differences between MicroProfile Telemetry 1.0 and MicroProfile OpenTracing 3.0].
 
-For information about configuring MicroProfile Telemetry, see xref:ROOT:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry].
+For information about configuring MicroProfile Telemetry, see xref:ROOT:microprofile-telemetry.adoc[OpenTelemetry].