OpenTelemetry

Helidon SE support for OpenTelemetry configuration and semantic conventions as described below is currently a preview feature. We intend to support it going forward, but we might change its external API and behavior in backward-incompatible ways across dot releases.

Overview

Helidon SE supports OpenTelemetry in several important ways:

Implements the neutral Helidon tracing API using OpenTelemetry
Allows users to assign OpenTelemetry settings as follows:
- Declaratively, using Helidon config under the top-level telemetry config key
- Programmatically, using the OpenTelemetry SDK API and the Helidon OpenTelemetry API
Conforms to the OpenTelemetry semantic conventions for automatically-created spans and metrics for HTTP requests
Allows publishing Helidon metrics to backend systems using OTLP.

OpenTelemetry models observability as a set of signals.

Each signal—for example metrics, tracing, and logging—is an origin of monitoring data, and each has configurable settings which control its behavior.

Helidon’s config support for OpenTelemetry has certain config attributes which apply to OpenTelemetry as a whole, others which pertain to individual signals, and still more which describe lower-level elements within a signal.

The Helidon OpenTelemetry configuration format, the Helidon OpenTelemetry API, and this documentation all follow this hierarchy:

Top-level telemetry
- Signals

This document describes how to configure each level in the hierarchy and covers general topics related to Helidon’s support of OpenTelemetry.

API

There are two APIs that might be useful to developers working with OpenTelemetry:

The Helidon OpenTelemetry API - useful for mapping configuration sources to Helidon builders and, ultimately, OpenTelemetry objects.
The OpenTelemetry API - useful for creating OpenTelemetry objects apart from Helidon configuration sources.

The types in the Helidon OpenTelemetry API correspond closely to the configuration structures described in later sections of this document. Application code can use Helidon OpenTelemetry builders to prepare and construct each of the configurable entities to ultimately prepare an OpenTelemetry instance set up according to the application’s needs.

That said, application code can equally well use the OpenTelemetry API and its builders to prepare the OpenTelemetry instance.

Applications could even use both APIs together, reading configuration to construct a Helidon builder and then adding to that builder OpenTelemetry objects created separately using the OpenTelemetry API.

The Helidon OpenTelemetry API Javadoc page lists the various types developers can use to prepare OpenTelemetry objects programmatically. As a starting point, the OpenTelemetryConfig interface and its Builder represents the top-level configuration for OpenTelemetry. Their Javadoc contains links to other types that compose the top-level object, and so on.

Later sections in this document also describe the configuration settings available.

The OpenTelemetry SDK documentation explains its API.

Many applications do not need to use either the Helidon OpenTelemetry API or the OpenTelemetry API directly. They can instead rely completely on declarative Helidon configuration of OpenTelemetry.

Global Instance

Typically, an application uses the same OpenTelemetry instance throughout its execution. OpenTelemetry offers a global OpenTelemetry instance to make it easy for application code to set and obtain the global instance.

Similarly, the Helidon tracing API has a global Tracer.

In most cases, an application that prepares OpenTelemetry programmatically should initialize both of those by including code as shown in the following example.

Setting the global OpenTelemetry and Tracer instances in Helidon:

import java.util.Map;
import io.helidon.telemetry.otelconfig.HelidonOpenTelemetry;

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.context.Scope;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

// Application code using the OpenTelemetry API or the Helidon OpenTelemetry API or both.
OpenTelemetry customOpenTelemetry = prepareOpenTelemetry();

// App code to build any tags to be applied to every span.
Map<String, String> tags = prepareTags();

HelidonOpenTelemetry.global(customOpenTelemetry, "your-service-name", tags);

Assigning the Global Instance

Using Helidon to set the global OpenTelemetry instance has these effects:

Assigns the instance as the OpenTelemetry global instance.
Creates a Helidon Tracer using the OpenTelemetry instance and makes that the Helidon global Tracer.

Helidon is deprecating its use of "global" Helidon objects in favor of retrieving the correct instance from the Helidon service registry. Applications should migrate toward using, for example, Services.get(Tracer.class) instead of Tracer.global().

Maven Coordinates

To enable various aspects of OpenTelemetry Support add one or more of the following dependencies to your project’s pom.xml (see Managing Dependencies).

Helidon Tracing provider:

pom.xml

<dependency>
  <groupId>io.helidon.tracing.providers</groupId>
  <artifactId>helidon-tracing-providers-opentelemetry</artifactId>
</dependency>

Helidon Config and programmatic builder support:

pom.xml

<dependency>
  <groupId>io.helidon.telemetry</groupId>
  <artifactId>helidon-telemetry-opentelemetry-config</artifactId>
</dependency>

Helidon WebServer OpenTelemetry Tracing semantics:

pom.xml

<dependency>
  <groupId>io.helidon.webserver.observe</groupId>
  <artifactId>helidon-webserver-observe-telemetry-tracing</artifactId>
  <scope>runtime</scope>
</dependency>

Helidon WebServer OpenTelemetry Metrics semantics:

pom.xml

<dependency>
  <groupId>io.helidon.webserver.observe</groupId>
  <artifactId>helidon-webserver-observe-telemetry-metrics</artifactId>
  <scope>runtime</scope>
</dependency>

WebClient Support

Helidon supports the OpenTelemetry semantic conventions for outgoing traffic which uses the Helidon WebClient. See the Helidon WebClient documentation.

Additional Dependencies

Most applications need to declare other runtime dependencies on OpenTelemetry artifacts because the configuration specifies—or the application code uses—particular OpenTelemetry types packaged in other artifacts.

For example, OpenTelemetry exporters are packaged individually or as related groups. See this section below for some specific dependencies to consider adding for particular exporters.

These exporters transmit telemetry data using a different protocol. (See this OpenTelemetry page.)

Key	Type	Default	Description
`enabled`	`Boolean`	`true`	Whether the OpenTelemetry support is enabled
`global`	`Boolean`	`true`	Whether the `io.opentelemetry.api.OpenTelemetry` instance created from this configuration should be made the global one
`propagators`	`List<String>`		OpenTelemetry `io.opentelemetry.context.propagation.TextMapPropagator` instances added explicitly by the app
`service`	`String`		Service name used in sending telemetry data to the collector
`signals`			Configuration for signals

Key	Type	Description
`longs`	`Map<String, Long>`	Long attributes
`strings`	`Map<String, String>`	String attributes
`doubles`	`Map<String, Double>`	Double attributes
`booleans`	`Map<String, Boolean>`	Boolean attributes

Key	Type	Description
`schedule-delay`	`Duration`	Delay between consecutive exports
`max-export-batch-size`	`Integer`	Maximum number of items batched for export together
`type`	`ProcessorType`	Processor type
`max-queue-size`	`Integer`	Maximum number of items retained before discarding excess unexported ones
`timeout`	`Duration`	Maximum time an export can run before being cancelled
`exporters`	`List<String>`	Name(s) of the exporter(s) this processor should use; specifying no names uses all configured exporters (or if no exporters are configured, the default OpenTelemetry exporter(s))

Key	Type	Default	Description
`connect-timeout`	`Duration`		Connection timeout
`headers`	`Map<String, String>`		Headers added to each export message
`endpoint`	`URI`		Endpoint of the collector to which the exporter should transmit
`memory-mode`	`MemoryMode`		Memory mode
`protocol`	`String`	`DEFAULT`	Exporter protocol type
`internal-telemetry-version`	`InternalTelemetryVersion`		Self-monitoring telemetry OpenTelemetry should collect
`certificate`	`Resource`		Trusted certificates
`client.key`	`Resource`		TLS client key
`client.certificate`	`Resource`		TLS certificate
`compression`	`CompressionType`		Compression the exporter uses
`retry-policy`	`RetryPolicyConfig`		Retry policy
`timeout`	`Duration`		Exporter timeout