Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC: changes for tracing and tracing guide #6113

Merged
merged 2 commits into from
Feb 9, 2023
Merged

DOC: changes for tracing and tracing guide #6113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e70aebc
changes for tracing
ljamen Feb 7, 2023
1ff9d48
Tim's review comments
ljamen Feb 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions docs/includes/tracing/tracer-jaeger.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////////

Copyright (c) 2019, 2022 Oracle and/or its affiliates.
Copyright (c) 2019, 2023 Oracle and/or its affiliates.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand All @@ -26,7 +26,7 @@ The Jaeger builder is loaded through `ServiceLoader` and configured. You could
also use the Jaeger builder directly, though this would create a source-code dependency
on the Jaeger tracer.

Since Helidon 3.0.0, we use Jaeger OpenTelemetry Tracing client to
Helidon 3.0 uses the Jaeger OpenTelemetry Tracing client to
integrate with Jaeger tracer.

include::{rootdir}/includes/dependencies.adoc[]
Expand All @@ -45,16 +45,20 @@ include::{rootdir}/includes/dependencies.adoc[]

== Configuring Jaeger

NOTE: Jaeger changed its client implementation, so some Jaeger settings exposed by earlier releases of Helidon are no longer available. Please note the currently-supported settings in the table below.

include::{rootdir}/config/io_helidon_tracing_jaeger_JaegerTracerBuilder.adoc[tag=config,levelOffset=1]

The following is an example of a Jaeger configuration, specified in the YAML format.
The following is an example of a Jaeger configuration, specified in the YAML format.

NOTE: The the Jaeger OpenTelemetry client uses port 14250, but you can override this value if needed. The default is defined by each tracing integration.
[source,yaml]
----
tracing:
service: "helidon-full-http"
protocol: "https"
host: "jaeger"
port: 14240
port: 14250
----

// end::jaeger-configuration[]
95 changes: 52 additions & 43 deletions docs/se/guides/tracing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////////

Copyright (c) 2019, 2022 Oracle and/or its affiliates.
Copyright (c) 2019, 2023 Oracle and/or its affiliates.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand All @@ -19,6 +19,7 @@
= Helidon SE Tracing Guide
:description: Helidon tracing
:keywords: helidon, tracing, microprofile, guide
:toc:
:rootdir: {docdir}/../..
:imagesdir: {rootdir}/images

Expand Down Expand Up @@ -161,32 +162,30 @@ WebServer server = WebServer.builder(createRouting(config))
<2> Build and register a `Tracer` object using the tracing configuration.

[source,java]
.Update the `GreetService` class; 1) Add a new import and 2) Replace the `getDefaultMessageHandler` method:
.Update the `GreetService` class; Replace the `getDefaultMessageHandler` method:
----
import io.opentracing.Span; // <1>
...
private void getDefaultMessageHandler(ServerRequest request,
ServerResponse response) {

var spanBuilder = request.tracer() // <2>
.buildSpan("getDefaultMessageHandler"); // <3>
request.spanContext().ifPresent(spanBuilder::asChildOf); // <4>
Span span = spanBuilder.start(); // <5>
var span = request.tracer() // <1>
.spanBuilder("getDefaultMessageHandler") // <2>
.update(spanBuilder -> request.spanContext().ifPresent(spanBuilder::parent)) // <3>
.start(); // <4>

try {
sendResponse(response, "World");
} finally {
span.finish(); // <6>
span.end(); // <5>
} catch (Throwable t) {
span.end(t); // <6>
}
}
----
<1> Add new import statement.
<2> Get the `Tracer` object from the request.
<3> Build a new span named `getDefaultMessageHandler`.
<4> Make the new span a child of the current span.
<5> Start the span. The current timestamp is used as the starting time for the span.
<6> Finish the span. The current timestamp is used as the ending time for the span.

<1> Get the `Tracer` object from the request.
<2> Build a new span named `getDefaultMessageHandler`.
<3> Make the new span a child of the request's span if it has one.
<4> Start the span. The current timestamp is used as the starting time for the span.
<5> End the span successfully. The current timestamp is used as the ending time for the span.
<6> End the span in the error case.

[source,bash]
.Build the application, skipping unit tests, then run it:
Expand Down Expand Up @@ -383,25 +382,30 @@ WebServer server = WebServer.builder(createRouting(config))
----

[source,java]
.Update the `GreetService` class; 1) Add new import and 2) Replace the `getDefaultMessageHandler` method:
.Update the `GreetService` class; Replace the `getDefaultMessageHandler` method:
----
import io.opentracing.Span;
//...
private void getDefaultMessageHandler(ServerRequest request,
ServerResponse response) {

var spanBuilder = request.tracer()
.buildSpan("getDefaultMessageHandler");
request.spanContext().ifPresent(spanBuilder::asChildOf);
Span span = spanBuilder.start();
var span = request.tracer() // <1>
.spanBuilder("getDefaultMessageHandler") // <2>
.update(spanBuilder -> request.spanContext().ifPresent(spanBuilder::parent)) // <3>
.start(); // <4>

try {
sendResponse(response, "World");
} finally {
span.finish();
span.end(); // <5>
} catch (Throwable t) {
span.end(t); // <6>
}
}
----
<1> Get the `Tracer` object from the request.
<2> Build a new span named `getDefaultMessageHandler`.
<3> Make the new span a child of the request's span if it has one.
<4> Start the span. The current timestamp is used as the starting time for the span.
<5> End the span successfully. The current timestamp is used as the ending time for the span.
<6> End the span in the error case.

[source,bash]
.Build the application, skipping unit tests, then run it:
Expand Down Expand Up @@ -459,7 +463,6 @@ import io.helidon.webserver.Routing;
import io.helidon.webserver.ServerRequest;
import io.helidon.webserver.ServerResponse;
import io.helidon.webserver.Service;
import io.opentracing.Span;
import java.util.Collections;
import java.util.concurrent.atomic.AtomicReference;
import jakarta.json.Json;
Expand Down Expand Up @@ -492,17 +495,19 @@ public class GreetService implements Service {
.put("/greeting", this::updateGreetingHandler);
}

private void getDefaultMessageHandler(ServerRequest request, ServerResponse response) {
private void getDefaultMessageHandler(ServerRequest request,
ljamen marked this conversation as resolved.
Show resolved Hide resolved
ServerResponse response) {

var spanBuilder = request.tracer()
.buildSpan("getDefaultMessageHandler");
request.spanContext().ifPresent(spanBuilder::asChildOf);
Span span = spanBuilder.start();
var span = request.tracer()
.spanBuilder("getDefaultMessageHandler")
.update(spanBuilder -> request.spanContext().ifPresent(spanBuilder::parent))
.start();

try {
sendResponse(response, "World");
} finally {
span.finish();
span.end();
} catch (Throwable t) {
span.end(t);
}
}

Expand All @@ -527,13 +532,13 @@ public class GreetService implements Service {
}

private void outboundMessageHandler(ServerRequest request, ServerResponse response) {
Invocation.Builder requestBuilder = webTarget.request();
Invocation.Builder requestBuilder = webTarget.request();

// <2>
var spanBuilder = request.tracer()
.buildSpan("outboundMessageHandler");
request.spanContext().ifPresent(spanBuilder::asChildOf);
Span span = spanBuilder.start();
var span = request.tracer()
.spanBuilder("outboundMessageHandler")
.update(spanBuilder -> request.spanContext().ifPresent(spanBuilder::parent))
.start();

try {
requestBuilder.property(
Expand All @@ -542,16 +547,20 @@ public class GreetService implements Service {
requestBuilder // <4>
.rx()
.get(String.class)
.thenAccept(response::send)
.thenAccept(str -> {
response.send(str);
span.end(); // <5>
})
.exceptionally(
throwable -> {
// process exception
response.status(Http.Status.INTERNAL_SERVER_ERROR_500);
response.send("Failed with: " + throwable);
span.end(throwable); // <5>
return null;
});
} finally {
span.finish(); // <5>
} catch (Throwable t) {
span.end(t); // <5>
}
}

Expand All @@ -564,7 +573,7 @@ public class GreetService implements Service {
<2> Create and start a span that is a child of the current span.
<3> Set a property with the `SpanContext`.
<4> Invoke the second service.
<5> Stop the span.
<5> End the span.

[source,bash]
.Build and run the application, then invoke the endpoint and check the response:
Expand Down
24 changes: 16 additions & 8 deletions docs/se/tracing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,20 +126,28 @@ GrpcServerConfiguration serverConfig = GrpcServerConfiguration.builder().port(0)
.build();
----

=== Creating custom spans
=== Creating Custom Spans

To create a custom span that is a child of the WebServer request:

[source,java]
----
Span span = request.tracer()
.buildSpan("my-operation")
.asChildOf(request.spanContext())
.start();
.spanBuilder("my-operation")
.update(spanBuilder -> request.spanContext().ifPresent(spanBuilder::parent))
.start();

try {
// Do some work and send a normal response.
span.end();
} catch (Throwable t) {
// Send an error response.
span.end(t);
}
----


=== Helidon Spans
== Helidon Spans

include::{rootdir}/includes/tracing/common-spans.adoc[]

Expand All @@ -149,7 +157,7 @@ The following configuration should be supported by all tracer implementations (i

include::{rootdir}/config/io_helidon_tracing_Tracer.adoc[tag=config,levelOffset=1]

=== Traced spans configuration
=== Traced Spans Configuration

Each component and its spans can be configured using Config.
The traced configuration has the following layers:
Expand Down Expand Up @@ -203,9 +211,9 @@ tracing:
routing.register(WebTracingConfig.create(config.get("tracing")));
----

==== Path based configuration in Helidon Web Server
==== Path-based configuration in Helidon Web Server

For Web Server we have a path based support for configuring tracing, in addition
For Web Server we have path-based support for configuring tracing, in addition
to the configuration described above.

Configuration of path can use any path string supported by the
Expand Down