[4.x][Doc] - Fix telemetry docs (#8014)

* Fix telemetry docs
* Fix language style
* Add example link
* Fix Exporter name
---------

Signed-off-by: Dmitry Aleksandrov <[email protected]>

docs/mp/telemetry.adoc

@@ -32,7 +32,6 @@ include::{rootdir}/includes/mp.adoc[]
 - <<Usage, Usage>>
 - <<Configuration, Configuration>>
 - <<Examples, Examples>>
-- <<Additional Information, Additional Information>>
 - <<Reference, Reference>>
 
 == Overview
@@ -51,7 +50,7 @@ include::{rootdir}/includes/dependencies.adoc[]
 
 link:https://opentelemetry.io/[OpenTelemetry] comprises a collection of APIs, SDKs, integration tools, and other software components intended to facilitate the generation and control of telemetry data, including traces, metrics, and logs. In an environment where distributed tracing is enabled via OpenTelemetry (which combines OpenTracing and OpenCensus), this specification establishes the necessary behaviors for MicroProfile applications to participate seamlessly.
 
-MicroProfile Telemetry 1.0 allows for the exportation of the data it collects to Jaeger or Zipkin and to other systems using variety of exporter.
+MicroProfile Telemetry 1.0 allows for the exportation of the data it collects to Jaeger or Zipkin and to other systems using a variety of exporters.
 
 In a distributed tracing system, *traces* are used to capture a series of requests and are composed of multiple *spans* that represent individual operations within those requests. Each *span* includes a name, timestamps, and metadata that provide insights into the corresponding operation.
 
@@ -68,7 +67,7 @@ There are two ways to work with Telemetry, using:
 
 For Automatic Instrumentation, OpenTelemetry provides a JavaAgent. The Tracing API allows for the automatic participation in distributed tracing of Jakarta RESTful Web Services (both server and client) as well as MicroProfile REST Clients, without requiring any modifications to the code. This is achieved through automatic instrumentation.
 
-For Manual Instrumentation there is a set of annotations and access to OpenTelemetry API.
+For Manual Instrumentation, there is a set of annotations and access to OpenTelemetry API.
 
 `@WithSpan` - By adding this annotation to a method in any Jakarta CDI aware bean, a new Span will be created and any necessary connections to the current Trace context will be established. Additionally, the `SpanAttribute` annotation can be used to mark method parameters that should be included in the Trace.
 
@@ -92,14 +91,14 @@ class HelidonBean {
         // do something here
     }
 
-    @WithSpan("name", kind = SpanKind.SERVER, @SpanAttribute(value = "arg") String arg) <2>
-    void complexSpan() {
+    @WithSpan("name") <2>
+    void complexSpan(@SpanAttribute(value = "arg") String arg) {
         // do something here
     }
 }
 ----
 <1> Simple `@WithSpan` annotation usage.
-<2> Additional attributes can be set to the annotation.
+<2> Additional attributes can be set on a method.
 
 You can also inject OpenTelemetry `Tracer` using the regular `@Inject` annotation and use `SpanBuilder` to manually create, star, and stop Spans.
 
@@ -195,14 +194,14 @@ To configure OpenTelemetry, MicroProfile Config must be used, and the configurat
 - link:https://github.com/open-telemetry/opentelemetry-java/tree/v1.19.0/sdk-extensions/autoconfigure[OpenTelemetry SDK Autoconfigure] (excluding properties related to Metrics and Logging)
 - link:https://opentelemetry.io/docs/instrumentation/java/manual/[Manual Instrumentation]
 
-Please consult with the links above for all configurations properties usage.
+Please consult with the links above for all configurations' properties usage.
 
-The property should be declared in `microprofile-config.properties` file in order to be processed correctly.
+The property should be declared in `microprofile-config.properties` file to be processed correctly.
 
 
 === OpenTelemetry Java Agent
 
-The OpenTelemetry Java Agent may influence the work of MicroProfile Telemetry, on how the objects are created and configured. Helidon will do "best effort" detect the use of the agent. But, if there is a decision to run the Helidon app with the agent, a configuration property should be set:
+The OpenTelemetry Java Agent may influence the work of MicroProfile Telemetry, on how the objects are created and configured. Helidon will do "best effort" to detect the use of the agent. But if there is a decision to run the Helidon app with the agent, a configuration property should be set:
 
 `otel.agent.present=true`
 
@@ -214,7 +213,7 @@ This guide demonstrates how to incorporate MicroProfile Telemetry into Helidon a
 
 === Set Up Jaeger
 
-For the examples Jaeger will be used for gathering of the tracing information.
+For example, Jaeger will be used for gathering of the tracing information.
 
 .Run Jaeger in a docker container.
 [source, bash]
@@ -232,7 +231,7 @@ docker run -d --name jaeger \
   -p 14268:14268 \
   -p 14269:14269 \
   -p 9411:9411 \
-  jaegertracing/all-in-one:1.41
+  jaegertracing/all-in-one:1.50
 ----
 
 All the tracing information gathered from the examples runs is accessible from the browser in the Jaeger UI under link:http://localhost:16686/[]
@@ -273,7 +272,7 @@ Here we enable MicroProfile Telemetry, set tracer to "jaeger" and give a name, w
 [NOTE]
 ====
 
-For this example, you will use Jaeger to manage data tracing. If you prefer to use Zipkin, please set `otel.traces.exporter` property to "zipkin". For more information using about Zipkin, see link:https://zipkin.io/[]. Also a corresponding Maven dependency for the exporter should be added:
+For this example, you will use Jaeger to manage data tracing. If you prefer to use Zipkin, please set `otel.traces.exporter` property to "zipkin". For more information using about Zipkin, see link:https://zipkin.io/[]. Also, a corresponding Maven dependency for the exporter should be added:
 ----
 <dependency>
     <groupId>io.opentelemetry</groupId>
@@ -370,7 +369,7 @@ public String outbound() {
 <2> Wrap method using `WithSpan`.
 <3> Call the secondary service.
 
-The secondary service is very simple, it has only one method, which is also annotated with `@WithSpan`.
+The secondary service is basic; it has only one method, which is also annotated with `@WithSpan`.
 
 .Secondary service
 [source, java]
@@ -398,9 +397,7 @@ Launch the Jaeger UI at link:http://localhost:16686/[] to see the expected outpu
 
 image::telemetry/telemetry-outbound-jaeger.png[Secondary service outbound call]
 
-
-== Additional Information
-
+This example is available at the link:https://github.com/helidon-io/helidon/tree/main/examples/microprofile/telemetry[Helidon official GitHub repository].
 
 == Reference
 

examples/microprofile/telemetry/README.md

@@ -25,7 +25,7 @@ docker run -d --name jaeger \
   -p 14268:14268 \
   -p 14269:14269 \
   -p 9411:9411 \
-  jaegertracing/all-in-one:1.43
+  jaegertracing/all-in-one:1.50
 ```
 
 If you have Jaeger all-in-one installed, use this command:

microprofile/telemetry/src/main/java/io/helidon/microprofile/telemetry/OpenTelemetryProducer.java

@@ -51,6 +51,9 @@ class OpenTelemetryProducer {
     private static final String OTEL_METRICS_EXPORTER = "otel.metrics.exporter";
     private static final String OTEL_LOGS_EXPORTER = "otel.logs.exporter";
     private static final String SERVICE_NAME_PROPERTY = "otel.service.name";
+    private static final String EXPORTER_NAME_PROPERTY = "otel.exporter.name";
+    private String exporterName = HELIDON_SERVICE_NAME; // Default if not set
+
     private LazyValue<OpenTelemetry> openTelemetry;
     private Map<String, String> telemetryProperties;
 
@@ -69,6 +72,8 @@ private void init() {
 
         telemetryProperties  = Collections.unmodifiableMap(getTelemetryProperties());
 
+        mpConfig.getOptionalValue(EXPORTER_NAME_PROPERTY, String.class).ifPresent(e -> exporterName = e);
+
         //Initialize OpenTelemetry in a lazy way.
         if (!isTelemetryDisabled()) {
             openTelemetry = LazyValue.create(() -> {
@@ -128,7 +133,7 @@ OpenTelemetry openTelemetry() {
      */
     @Produces
     Tracer tracer(OpenTelemetry openTelemetry) {
-        return openTelemetry.getTracer(HELIDON_SERVICE_NAME);
+        return openTelemetry.getTracer(exporterName);
     }
 
     /**

microprofile/telemetry/src/main/java/io/helidon/microprofile/telemetry/WithSpanInterceptor.java

@@ -51,7 +51,7 @@ class WithSpanInterceptor {
      *
      * @param context Invocation Context
      * @return Invocation proceed.
-     * @throws Exception
+     * @throws Exception when something is wrong
      */
     @AroundInvoke
     public Object interceptSpan(InvocationContext context) throws Exception {