From 6060272b9f57cca336758af0805d692856af5f01 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Wed, 8 Nov 2023 13:10:27 +0200 Subject: [PATCH] Address comments Signed-off-by: Dmitry Aleksandrov --- docs/se/guides/tracing.adoc | 28 ++++++++++++++++------------ docs/se/tracing.adoc | 34 ++++++++++++---------------------- 2 files changed, 28 insertions(+), 34 deletions(-) diff --git a/docs/se/guides/tracing.adoc b/docs/se/guides/tracing.adoc index dd2218846c0..5faa24a9c54 100644 --- a/docs/se/guides/tracing.adoc +++ b/docs/se/guides/tracing.adoc @@ -189,11 +189,12 @@ private void getDefaultMessageHandler(ServerRequest request, } } ---- -<1> Create a new `Span` using Global Tracer. -<2> Set Parent Span, if available in the `Request`. +<1> Create a new `Span` using the global tracer. +<2> Set the parent of the new span to the span from the `Request` if available. <3> Start the span. -<4> End the span when the response is sent. -<5> Record an exception in the span if happened. +<4> End the span normally after the response is sent. +<5> End the span with an exception if one was thrown. + [source,bash] .Build the application, skipping unit tests, then run it: @@ -250,11 +251,11 @@ image::guides/12_tracing_span_detail.png[Span Details] === Tracing Across Services Helidon automatically traces across services if the services use the same tracer, for example, the same instance of Jaeger. -This means a single trace can include spans from multiple services and hosts. Helidon uses a `Span.context()` to +This means a single trace can include spans from multiple services and hosts. Helidon uses a `SpanContext` to propagate tracing information across process boundaries. When you make client API calls, Helidon will -internally call OpenTelemetry APIs to propagate the Span Context. There is nothing you need to do in your application to make this work. +internally call OpenTelemetry APIs or OpenTracing APIs to propagate the Span Context. There is nothing you need to do in your application to make this work. -To demonstrate distributed tracing, you will need to create a second project, where the server listens on port 8081. +To demonstrate distributed tracing, you will need to create a second project, where the server listens to on port 8081. Create a new root directory to hold this new project, then do the following steps, similar to what you did at the start of this guide: @@ -294,7 +295,7 @@ cd helidon-quickstart-se-2 helidon-tracing-providers-jaeger <3> ---- -<1> Helidon Tracing dependencies. +<1> Helidon Tracing API dependencies. <2> Observability features for tracing. <3> Jaeger tracing provider. @@ -322,6 +323,8 @@ server: host: 0.0.0.0 ---- +NOTE: The settings above are for development and experimental purposes only. For production environment, please see the link:../tracing.adoc[Tracing documentation]. + [source,java] .Update the `Main` class; Add Tracer to the WebServer builder ---- @@ -352,8 +355,8 @@ private void getDefaultMessageHandler(ServerRequest request, try { sendResponse(response, "World"); - } finally { - span.finish(); + } catch (Throwable t) { + span.end(t); } } ---- @@ -474,8 +477,8 @@ public class GreetService implements HttpService { String result = requestBuilder // <4> .get(String.class); response.send(result); - } finally { - span.end(); // <5> + } catch (Throwandle t) { + span.end(t); // <5> } } @@ -684,5 +687,6 @@ Refer to the following references for additional information: - link:{microprofile-tracing-spec-url}[MicroProfile OpenTracing specification] - link:{microprofile-tracing-javadoc-url}[MicroProfile OpenTracing Javadoc] +* link:https://opentelemetry.io/docs/instrumentation/js/api/tracing/[OpenTelemetry API] - link:{javadoc-base-url}/index.html?overview-summary.html[Helidon Javadoc] diff --git a/docs/se/tracing.adoc b/docs/se/tracing.adoc index 3c65fb6a799..cc7d8746bc6 100644 --- a/docs/se/tracing.adoc +++ b/docs/se/tracing.adoc @@ -87,7 +87,7 @@ For OpenTelemetry: ---- io.helidon.tracing.providers - helidon-tracing-providers-jaeger + helidon-tracing-providers-opentelemetry ---- @@ -96,7 +96,7 @@ For OpenTracing: ---- io.helidon.tracing.providers - helidon-tracing-providers-jaeger + helidon-tracing-providers-opentracing ---- // end::tracing-dependency[] @@ -155,8 +155,8 @@ Span span = tracer.spanBuilder("name") <1> try (...){ <2> //do some work span.end(); -} catch (Exception e) { <3> - span.end(e); +} catch (Throwable t) { <3> + span.end(t); } ---- <1> Create span from tracer. @@ -224,12 +224,14 @@ tracing: [source,java] .Use the configuration in web server ---- -Tracer tracer = TracerBuilder.create(config.get("tracing")).build(); +Tracer tracer = TracerBuilder.create(config.get("tracing")).build(); <1> server.addFeature(ObserveFeature.builder() - .addObserver(TracingObserver.create(tracer)) + .addObserver(TracingObserver.create(tracer)) <2> .build()) ---- +<1> Create `Tracer` using `TracerBuilder` from configuration. +<2> Add the `Tracer` as an observability feature. ==== Path-based Configuration in Helidon WebServer @@ -264,26 +266,14 @@ tracing: [source,java] .Configuration with Web Server ---- -Tracer tracer = TracerBuilder.create(config.get("tracing")).build(); +Tracer tracer = TracerBuilder.create(config.get("tracing")).build(); <1> server.addFeature(ObserveFeature.builder() - .addObserver(TracingObserver.create(tracer)) - .build()) ----- - -[source,java] -.Configuration with Web Server using a builder ----- -Tracer tracer = WebTracingConfig.builder() - .addPathConfig(PathTracingConfig.builder() - .path("/metrics") - .tracingConfig(TracingConfig.DISABLED) - .build(); - -server.addFeature(ObserveFeature.builder() - .addObserver(TracingObserver.create(tracer)) + .addObserver(TracingObserver.create(tracer)) <2> .build()) ---- +<1> Create `Tracer` using `TracerBuilder` from configuration. +<2> Add the `Tracer` as an observability feature. ==== Renaming top level span using request properties