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

edits for dev prereqs

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

@@ -18,7 +18,7 @@ For more information about collecting and emitting metrics with MicroProfile Tel
 
 For more information about OpenTelemetry metrics, see the link:https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.39.0/io/opentelemetry/api/metrics/package-summary.html[OpenTelemetry metrics API documentation].
 
-Before you can use MicroProfile Telemetry to define custom metrics metrics, you must enable MicroProfile Telemetry in your development environment by editing your runtime configuration. You must also add the OpenTelemetry API and annotations as a dependency on your build path. For more information, see link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry].
+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. You must also add the OpenTelemetry API and annotations as a dependency on your build path. 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:
 

modules/ROOT/pages/observability.adoc

@@ -20,7 +20,7 @@ With MicroProfile Telemetry 2.0 and later, you can manage logs, metrics, and tra
 The following topics provide information to help you develop observable applications with Open Liberty.
 
 ////
-xref:prepare-mptelemetry.adoc[Prepare your development environment for MicroProfile Telemetry]::
+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.
 ////
 

modules/ROOT/pages/prepare-mptelemetry.adoc

@@ -10,7 +10,7 @@
 :seo-description:
 :page-layout: general-reference
 :page-type: general
-= Prepare your development environment for MicroProfile Telemetry
+= 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.
 

modules/ROOT/pages/telemetry-trace.adoc

@@ -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 link:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Prepare your development environment for MicroProfile Telemetry].
+However, before you manually instrument your code, you must make 3rd party APIs visible in your runtime 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:/docs/latest/reference/feature/mpTelemetry-2.0.html#dev[Customize your application telemetry with the OpenTelemetry API].
 
 After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API.
 

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

@@ -12,10 +12,28 @@ 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.
 
+[#logs]
+=== 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.
+
+[source,xml]
+----
+<mpTelemetry source="message, trace, ffdc"/>
+----
+
+* The `mpTelemetry` configuration element is optional. If you do not specify it or the `source` attribute, the default configuration source is `message`.
+
+* If the source attribute is empty (`source=“”`), no sources are collected, and nothing is routed to the configured OpenTelemetry logs exporter.
+
+* The attributes and values are case insensitive.
+
 [#dev]
-=== Prepare your development environment for OpenTelemetry
+=== Customize your application telemetry with the OpenTelemetry API
+
+Although OpenTelemetry automatically collects a default set of logs, metrics, and traces, if you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], you must make the OpenTelemetry API and annotations available in your development environment.
 
-If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to collect traces] or xref:ROOT:custom-mptelemetry-metrics.adoc[define custom metrics], complete the following prerequisites to enable MicroProfile Telemetry in your development environment:
+Complete the following prerequisites before you configure custom OpenTelemetry traces or metrics in your application code:
 
 * xref:ROOT:class-loader-library-config.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file:
 +
@@ -44,19 +62,4 @@ If you need to xref:ROOT:telemetry-trace.adoc[manually instrument your code to c
     </dependency>
 ----
 
-
-[#logs]
-=== 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.
-
-[source,xml]
-----
-<mpTelemetry source="message, trace, ffdc"/>
-----
-
-* The `mpTelemetry` configuration element is optional. If you do not specify it or the `source` attribute, the default configuration source is `message`.
-
-* If the source attribute is empty (`source=“”`), no sources are collected, and nothing is routed to the configured OpenTelemetry logs exporter.
-
-* The attributes and values are case insensitive.
+Once you complete these prerequisites, you can use the OpenTelemetry API and annotations in your development environment to configure custom application telemetry.