Tracing

Maven Coordinates

To enable MicroProfile Tracing either add a dependency on the helidon-microprofile bundle or add the following dependency to your project’s pom.xml (see Managing Dependencies).

<dependency>
    <groupId>io.helidon.microprofile.tracing</groupId>
    <artifactId>helidon-microprofile-tracing</artifactId>
</dependency>

Copied

Configuring Tracing with Helidon MP

Tracing support is implemented for both for Helidon MP Server and for Jersey client. In addition, you need to add one of the tracer implementations:

You can configure a custom service name using the tracing.service configuration property. If this property is undefined, name is created from JAX-RS Application name, or Helidon MP is used if no application is defined.

All tracer specific configuration is expected in configuration under key tracing.

Example microprofile-config.properties with customized service name.

tracing.service=event-service

Copied

Configuration using Helidon Config

There is a set of common configuration options that this section describes. In addition each tracer implementation may have additional configuration options - please see the documentation of each of them.

Each implementation may provide defaults for these options.

All common configuration options:

key	description
service	Name of the service sending the tracing information. This is usually visible in the trace data to distinguish actors in a conversation (e.g. when multiple microservices are connected together)
protocol	Protocol of the tracing collector (e.g. `http`, `https`)
host	Host of the tracing collector (e.g. `localhost`)
port	Port of the tracing collector (e.g. `9411`)
path	Path of the tracing collector service that is used to send spans to
enabled	If set to false, tracing would be disabled
tags	String tags that are to be added to each span reported (object node of string-string pairs)
boolean-tags	Boolean tags that are to be added to each span reported (object node of string-boolean pairs)
int-tags	Int tags that are to be added to each span reported (object node of string-int pairs)

To disable Helidon tracing for web server and security:

tracing.components.web-server.enabled=false
tracing.components.security.enabled=false

Copied

To disables MP Tracing as by specification:

mp.opentracing.server.skip-pattern=.*

Copied

Creating custom spans

Helidon MP fully supports MicroProfile OpenTracing. You can add custom spans using @Traced annotation on methods of CDI beans.

Note for invoking methods on same class: If you invoke a method on the same class, @Traced annotation would be ignored, as it is not invoked through a CDI proxy and as such cannot be intercepted. To make sure @Traced is honored, use it on JAX-RS resource methods and on CDI bean methods used from other beans.

Trace propagation across services

Automated trace propagation is supported currently only with Jersey client.

Tracing propagation works automatically as long as you run within the scope of Helidon MP and use Helidon components to invoke external services.

Manual handling of traces in Jersey Client

There is an option to provide SpanContext programmatically (such as when writing a command line application that starts the span manually).

You can either configure the span context as the active span, or explicitly define it as client property.

Tracing propagation with Jersey client

import static io.helidon.tracing.jersey.client.ClientTracingFilter.CURRENT_SPAN_CONTEXT_PROPERTY_NAME;
import static io.helidon.tracing.jersey.client.ClientTracingFilter.TRACER_PROPERTY_NAME;

// ...

Response response = client.target(serviceEndpoint)
    .request()
    // tracer should be provided unless available as GlobalTracer
    .property(TRACER_PROPERTY_NAME, tracer)
    .property(CURRENT_SPAN_CONTEXT_PROPERTY_NAME, spanContext)
    .get();

Copied

Traced spans

The following table lists all spans traced by Helidon components:

component	span name	description
`web-server`	`HTTP Request`	The overall span of the Web Server from request intitiation until response Note that in `Zipkin` the name is replaced with `jax-rs` span name if `jax-rs` tracing is used.
`web-server`	`content-read`	Span for reading the request entity
`web-server`	`content-write`	Span for writing the response entity
`security`	`security`	Processing of request security
`security`	`security:atn`	Span for request authentication
`security`	`security:atz`	Span for request authorization
`security`	`security:response`	Processing of response security
`security`	`security:outbound`	Processing of outbound security
`jax-rs`	A generated name	Span for the resource method invocation, name is generated from class and method name
`jax-rs`	`jersey-client-call`	Span for outbound client call

Some of these spans log to the span. These log events can be (in most cases) configured:

span name	log name	configurable	enabled by default	description
`HTTP Request`	`handler.class`	YES	YES	Each handler has its class and event logged
`security`	`status`	YES	YES	Logs either "status: PROCEED" or "status: DENY"
`security:atn`	`security.user`	YES	NO	The username of the user if logged in
`security:atn`	`security.service`	YES	NO	The name of the service if logged in
`security:atn`	`status`	YES	YES	Logs the status of security response (such as `SUCCESS`)
`security:atz`	`status`	YES	YES	Logs the status of security response (such as `SUCCESS`)
`security:outbound`	`status`	YES	YES	Logs the status of security response (such as `SUCCESS`)

There are also tags that are set by Helidon components. These are not configurable.

span name	tag name	description
`HTTP Request`	`component`	name of the component - `helidon-webserver`, or `jaxrs` when using MP
`HTTP Request`	`http.method`	HTTP method of the request, such as `GET`, `POST`
`HTTP Request`	`http.status_code`	HTTP status code of the response
`HTTP Request`	`http.url`	The path of the request (for SE without protocol, host and port)
`HTTP Request`	`error`	If the request ends in error, this tag is set to `true`, usually accompanied by logs with details
`content-read`	`requested.type`	Type (class) of the requested entity (if entity is read)
`content-write`	`response.type`	Type (class) of the entity being sent (if enitty is sent)
`security`	`security.id`	ID of the security context created for this request (if security is used)
`jersey-client-call`	`http.method`	HTTP method of the client request
`jersey-client-call`	`http.status_code`	HTTP status code of client response
`jersey-client-call`	`http.url`	Full URL of the request (such as `http://localhost:8080/greet`)

Configuration using MP Config

Tracing configuration can be defined in microprofile-config.properties file.

Tracing configuration

tracing.components.web-server.spans.0.name="HTTP Request"
tracing.components.web-server.spans.0.logs.0.name="content-write"
tracing.components.web-server.spans.0.logs.0.enabled=false

Copied

Path based configuration in Helidon Web Server

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

Configuration of path can use any path string supported by the Web Server. 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")

Configuration properties

tracing.paths.0.path="/favicon.ico"
tracing.paths.0.enabled=false
tracing.paths.1.path="/metrics"
tracing.paths.1.enabled=false
tracing.paths.2.path="/health"
tracing.paths.2.enabled=false

Copied

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:

Configuration properties

tracing.components.web-server.spans.0.name="HTTP Request"
tracing.components.web-server.spans.0.new-name: "HTTP %1$s %2$s"

Copied

This is supported ONLY for the span named "HTTP Request" on component "web-server".

Parameters provided:

Method - HTTP method
Path - path of the request (such as '/greet')
Query - query of the request (may be null)