se.tracing.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2019, 2024 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.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= Tracing
:description: Helidon SE Tracing Support
:feature-name: Helidon Tracing
:keywords: helidon, tracing
:rootdir: {docdir}/..
include::{rootdir}/includes/se.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
** <>
** <>
- <>
== Overview
Distributed tracing is a critical feature of microservice based applications, since it traces workflow both
within a service and across multiple services. This provides insight to sequence and timing data for specific blocks of work,
which helps you identify performance and operational issues.
Helidon includes support for distributed tracing through its own API, backed by either
through the https://opentelemetry.io/docs/instrumentation/js/api/tracing/[OpenTelemetry API], or by
https://opentracing.io[OpenTracing API]. Tracing is integrated with WebServer and Security.
include::{rootdir}/includes/dependencies.adoc[]
// tag::tracing-dependency[]
[source,xml]
----
io.helidon.tracing
helidon-tracing
io.helidon.webserver.observe
helidon-webserver-observe-tracing
----
<1> Helidon tracing dependency.
<2> Observability dependencies for tracing.
For further processing of the tracing data, different providers are used.
For Jaeger:
[source,xml]
----
io.helidon.tracing.providers
helidon-tracing-providers-jaeger
----
For Zipkin:
[source,xml]
----
io.helidon.tracing.providers
helidon-tracing-providers-zipkin
----
For OpenTelemetry:
[source,xml]
----
io.helidon.tracing.providers
helidon-tracing-providers-opentelemetry
----
For OpenTracing:
[source,xml]
----
io.helidon.tracing.providers
helidon-tracing-providers-opentracing
----
// end::tracing-dependency[]
== Usage
This section explains a few concepts that you need to understand before you get started with tracing.
* In the context of this document, a _service_ is synonymous with an application.
* A _span_ is the basic unit of work done within a single service, on a single host.
Every span has a name, starting timestamp, and duration.
For example, the work done by a REST endpoint is a span.
A span is associated to a single service, but its descendants can belong to different services and hosts.
* A _trace_ contains a collection of spans from one or more services, running on one or more hosts. For example,
if you trace a service endpoint that calls another service, then the trace would contain spans from both services.
Within a trace, spans are organized as a directed acyclic graph (DAG) and
can belong to multiple services, running on multiple hosts.
* _Baggage_ is a collection of key-value pairs associated with a span.
* _Span context_ captures data about a span not related to its duration, such as the tracer ID, the span ID, and baggage.
Support for specific tracers is abstracted. Your application can depend on
the Helidon abstraction layer and provide a specific tracer implementation as a Java
`ServiceLoader` service.
Helidon provides such an implementation for:
- OpenTracing tracers, either using the `GlobalTracer`, provider resolver approach, or explicitly using Zipkin tracer
- OpenTelemetry tracers, either using the global OpenTelemetry instance, or explicitly using Jaeger tracer
=== Setup WebServer
[source,java]
.Configuring `Tracer`
----
include::{sourcedir}/se/TracingSnippets.java[tag=snippet_1, indent=0]
----
<1> Create a `Tracer`.
<2> Add an observability feature using the created `Tracer`.
=== Creating Custom Spans
To create a custom span from tracer:
[source,java]
----
include::{sourcedir}/se/TracingSnippets.java[tag=snippet_2, indent=0]
----
<1> Create span from tracer.
<2> Do some work and end span.
<3> End span with exception.
=== Handling Baggage
Your application can set and read baggage associated with a
link:{tracing-javadoc-base-url}/io/helidon/tracing/Span.html[`Span`].
The `Span.baggage()` method returns a
link:{tracing-javadoc-base-url}/io/helidon/tracing/WritableBaggage.html[`WritableBaggage`] instance.
Further, Helidon also provides read-only access to baggage linked to
a link:{tracing-javadoc-base-url}/io/helidon/tracing/SpanContext.html[`SpanContext`].
For example, HTTP headers can convey trace ID, span ID, and baggage information and Helidon puts such information into a `SpanContext`.
Your code can create a `SpanContext` from other sources as well. The `SpanContext.baggage()` method returns a read-only link:{tracing-javadoc-base-url}/io/helidon/tracing/Baggage.html[`Baggage`] instance.
The JavaDoc for the types describes how to get and set baggage entries, get all the baggage keys, and check whether a baggage key exists in the baggage.
include::{rootdir}/includes/tracing/common-callbacks.adoc[tags=defs;detailed,leveloffset=+1]
== Helidon Spans
include::{rootdir}/includes/tracing/common-spans.adoc[]
== Configuration
The following configuration should be supported by all tracer implementations (if feasible)
include::{rootdir}/config/io_helidon_tracing_Tracer.adoc[tag=config,levelOffset=1]
=== Traced Spans Configuration
Each component and its spans can be configured using Config.
The traced configuration has the following layers:
- `TracingConfig` - the overall configuration of traced components of Helidon
- `ComponentTracingConfig` - a component of Helidon that traces spans (such as `web-server`, `security`, `jax-rs`)
- `SpanTracingConfig` - a single traced span within a component (such as `security:atn`)
- `SpanLogTracingConfig` - a single log event on a span (such as `security.user` in span `security:atn`)
The components using tracing configuration use the
`TracingConfigUtil`. This uses the `io.helidon.common.Context` to retrieve
current configuration.
==== Configuration Using Builder
Builder approach, example that disables a single span log event:
[source,java]
.Configure tracing using a builder
----
include::{sourcedir}/se/TracingSnippets.java[tag=snippet_3, indent=0]
----
==== Configuration using Helidon Config
Tracing configuration can be defined in a config file.
[source, yaml]
.Tracing configuration
----
tracing:
components:
web-server:
spans:
- name: "HTTP Request"
logs:
- name: "content-write"
enabled: false
----
[source,java]
.Use the configuration in web server
----
include::{sourcedir}/se/TracingSnippets.java[tag=snippet_4, indent=0]
----
<1> Create `Tracer` using `TracerBuilder` from configuration.
<2> Add the `Tracer` as an observability feature.
==== Path-based Configuration in Helidon WebServer
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
WebServer. The configuration itself has the same possibilities
as traced configuration described above. The path-specific configuration
will be merged with global configuration (path is the "newer" configuration, global is the "older")
[source,yaml]
.Configuration in YAML
----
tracing:
paths:
- path: "/favicon.ico"
enabled: false
- path: "/metrics"
enabled: false
- path: "/health"
enabled: false
- path: "/greet"
components:
web-server:
spans:
- name: "content-read"
new-name: "read"
enabled: false
----
==== Renaming top level span using request properties
To have a nicer overview in search pane of a tracer, you can customize the top-level span name using configuration.
Example:
[source,yaml]
.Configuration in YAML
----
tracing:
components:
web-server:
spans:
- name: "HTTP Request"
new-name: "HTTP %1$s %2$s"
----
This is supported ONLY for the span named "HTTP Request" on component "web-server".
Parameters provided:
1. Method - HTTP method
2. Path - path of the request (such as '/greet')
3. Query - query of the request (may be null)
== Additional Information
=== WebClient Span Propagation
Span propagation is supported with Helidon WebClient.
Tracing propagation is automatic as long as the current span context is available in Helidon Context
(which is automatic when running within a WebServer request).
[source,xml]
----
io.helidon.webclient
helidon-webclient
io.helidon.webclient
helidon-webclient-tracing
----
[source,java]
.Tracing propagation with Helidon WebClient
----
include::{sourcedir}/se/TracingSnippets.java[tag=snippet_5, indent=0]
----
=== Jaeger Tracing [[jaeger-tracing]]
include::{rootdir}/includes/tracing/tracer-jaeger.adoc[tag=jaeger-dependency]
include::{rootdir}/includes/tracing/tracer-jaeger.adoc[tag=jaeger-configuration]
=== Jaeger Tracing Metrics [[jaeger-tracing-metrics]]
As the <> section describes, you can use Jaeger tracing in your Helidon application.
=== Zipkin Tracing [[zipkin-tracing]]
include::{rootdir}/includes/tracing/tracer-zipkin.adoc[tag=zipkin-dependency]
include::{rootdir}/includes/tracing/tracer-zipkin.adoc[tag=zipkin-configuration]
== Reference
* link:https://opentracing.io/[Opentracing Project]
* link:https://opentelemetry.io/docs/instrumentation/js/api/tracing/[OpenTelemetry API]
* link:https://opentelemetry.io/docs/instrumentation/js/api/tracing/[OpenTelemetry API]