OpenTelemetry Support in Helidon SE

Overview

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.

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.

Note

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.

Managing the Global `OpenTelemetry` 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);

Copied

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).

Using the OpenTelemetry implementation of the Helidon Tracing API

Helidon offers an implementation of its neutral tracing API that uses OpenTelemetry. Add the following dependency to use OpenTelemetry for tracing.

Dependency to use the Helidon OpenTelemetry implementation of Helidon tracing

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

Copied

Adding OpenTelemetry Configuration and Builder Support

To allow deployers and end users to set up Helidon configuration to control OpenTelemetry behavior, add the following dependency.

Dependency to add Helidon OpenTelemetry config and programmatic builder support

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

Copied

To use the Helidon OpenTelemetry API in your application code, remove this line or change it to <scope>compile</scope>.

Enabling Automatic Spans for HTTP Requests

Helidon’s tracing observability support automatically creates a new tracing span for each HTTP request if your project includes the following dependency.

Dependency for automatic HTTP request tracing

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

Copied

By default, when Helidon SE creates spans automatically for HTTP requests, it uses a set of rules—semantic conventions—for choosing the span name and adding tags to each span.

OpenTelemetry prescribes its own semantic conventions. If you add the following dependency, Helidon follows the OpenTelemetry semantic conventions for spans instead of its own.

Dependency for Helidon support of the OpenTelemetry tracing semantic conventions

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

Copied

Enabling Automatic Metrics for Incoming HTTP Requests

Helidon’s metrics observability support automatically registers and updates one or more meters (depending on configuration) and updates them accordingly as HTTP requests arrive.

Dependency for automatic HTTP request measurements

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

Copied

OpenTelemetry prescribes its own semantic conventions for metrics—their names and tha attributes (tags) they have. If you add the following dependency, Helidon registers and updates meters according to the OpenTelemetry metrics semantic conventions.

Dependency for Helidon support of the OpenTelemetry metrics semantic conventions for incoming HTTP requests

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

Copied

Enabling OpenTelemetry for Outgoing Helidon Webclient Traffic

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

Specifying Additional OpenTelemetry 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.)

Configuration

You can control almost all of OpenTelemetry’s overall, tracing, metrics, and logger runtime behavior using Helidon configuration settings. Helidon constructs an OpenTelemetry object using the configuration. The resulting OpenTelemetry instance reflects these settings from the Helidon configuration:

Settings that pertain to overall OpenTelemetry behavior, apart from a particular signal.
An OpenTelemetry tracer provider based on tracing configuration in signals.tracing.
An OpenTelemetry meter provider based on metrics configuration in signals.metrics.
An OpenTelemetry logger provider based on logger configuration in signals.logging.

Controlling Overall OpenTelemetry Behavior

Several settings control the operation of OpenTelemetry as a whole, as shown in the next table.

Configuration options

Key	Kind	Type	Default Value	Description
`enabled`	`VALUE`	`Boolean`	`true`	Whether the OpenTelemetry support is enabled
`global`	`VALUE`	`Boolean`	`true`	Whether the `io.opentelemetry.api.OpenTelemetry` instance created from this configuration should be made the global one
`propagators`	`LIST`	`i.h.t.o.O.CustomMethods`		OpenTelemetry `io.opentelemetry.context.propagation.TextMapPropagator` instances added explicitly by the app
`service`	`VALUE`	`String`		Service name used in sending telemetry data to the collector
`signals.logging`	`VALUE`	`i.h.t.o.OpenTelemetryLoggingConfig`		OpenTelemetry logging settings
`signals.metrics`	`VALUE`	`i.h.t.o.OpenTelemetryMetricsConfig`		OpenTelemetry metrics settings
`signals.tracing`	`VALUE`	`i.h.t.o.OpenTelemetryTracingConfig`		OpenTelemetry tracing settings

Notes:

OpenTelemetry uses default propagators of tracecontext and baggage. (See the otel.propagators property in this OpenTelemetry guide.)
Setting global to true has the effect described in the section about global instances.

Common Configuration Across Signals

This section describes settings that apply to multiple signal types.

Assigning Attributes

Configured attributes are key/value pairs that OpenTelemetry attaches to each transmission of a signal. OpenTelemetry supports attributes of type String, long, double, and boolean. The Helidon configuration structure groups attributes by type so Helidon can indicate precisely to OpenTelemetry what type you intend for each attribute.

You can add attributes to the configuration for any of the signals under the signal’s attributes section.

Configuration options

Key	Kind	Type	Description
`booleans`	`MAP`	`Boolean`	Boolean attributes
`doubles`	`MAP`	`Double`	Double attributes
`longs`	`MAP`	`Long`	Long attributes
`strings`	`MAP`	`String`	String attributes

The following example shows attribute settings for the tracing signal.

Example attribute settings

telemetry:
  service: my-helidon-service
  tracing:
    attributes:
      strings:
        attr1: 12
        attr5: "any old thing"
        attr7: something
      longs:
        attr2: 12
      doubles:
        attr3: 24.5
        attr6: 12
      booleans:
        attr4: true

Copied

Configuring Exporters and Processors/Readers

OpenTelemetry transmits the telemetry data it gathers to a backend system—such as Grafana, Signoz, Prometheus, Jaeger, or others—where you can view and query the data. OpenTelemetry goes through these distinct steps to gather and send data:

OpenTelemetry tracing and log record processors and metrics readers gather and process data observations.
OpenTelemetry exporters associated with each processor or reader then transmit_ the data to one or more targets. Targets are typically backend systems but can be local ones for debugging. Each processor or reader uses one or more exporters to transmit telemetry data.

The processor settings determine when and how often each uses its exporters to deliver data. Each exporter’s settings prescribe where it should send the data, how to connect to a backend, etc.

Configuring Processors (and readers)

An OpenTelemetry span or log record processor or metric reader is one of the following types:

simple - The processor sends each telemetry observation to its exporters for transmission as soon as it receives the observation.
batch - The processor groups observations into batches and sends a batch at a time to its exporters for transmission.

In the table below only the type and exporters setting apply to simple processors; the other settings are for batch processors.

Configuration options

Key	Kind	Type	Description
`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))
`max-export-batch-size`	`VALUE`	`Integer`	Maximum number of items batched for export together
`max-queue-size`	`VALUE`	`Integer`	Maximum number of items retained before discarding excess unexported ones
`schedule-delay`	`VALUE`	`Duration`	Delay between consecutive exports
`timeout`	`VALUE`	`Duration`	Maximum time an export can run before being cancelled
`type`	`VALUE`	`i.h.t.o.ProcessorType`	Processor type

Configuring Exporters

Exporter objects in OpenTelemetry are specific to both how they transmit telemetry data and what signal they work with. Even so, many exporter settings are very similar across different signals. This section describes the behavior and configuration that is common among exporters. Refer to the sections below that describe each signal to see what additional exporter settings, if any, each signal adds.

Helidon configuration supports several of the most popular exporters, discussed below.

Setting Up OTLP Exporters

Most users choose an Otlp exporter which has two variations—one using gRPC and one using HTTP with protocol buffers—as indicated by the protocol setting.

Configuration options

Common Configuration for OTLP exporters

Key	Kind	Type	Default Value	Description
`certificate`	`VALUE`	`i.h.c.c.Resource`		Trusted certificates
`client.certificate`	`VALUE`	`i.h.c.c.Resource`		TLS certificate
`client.key`	`VALUE`	`i.h.c.c.Resource`		TLS client key
`compression`	`VALUE`	`i.h.t.o.CompressionType`		Compression the exporter uses
`connect-timeout`	`VALUE`	`Duration`		Connection timeout
`endpoint`	`VALUE`	`URI`		Endpoint of the collector to which the exporter should transmit
`headers`	`MAP`	`String`		Headers added to each export message
`internal-telemetry-version`	`VALUE`	`i.o.s.c.InternalTelemetryVersion`		Self-monitoring telemetry OpenTelemetry should collect
`memory-mode`	`VALUE`	`i.o.s.c.e.MemoryMode`		Memory mode
`protocol`	`VALUE`	`i.h.t.o.O.CustomMethods`	`DEFAULT`	Exporter protocol type
`retry-policy`	`VALUE`	`i.h.t.o.O.CustomMethods`		Retry policy
`timeout`	`VALUE`	`Duration`		Exporter timeout

OpenTelemetry OTLP exporter defaults

Setting	OpenTelemetry default
`compression`	`none`
`endpoint`	`grpc` protocol: http://localhost:4317	`http/proto` protocol: http://localhost:4318
`protocol`	`grpc`
`retry-policy`	none
`timeout`	10 seconds

OTLP Retry Policy

You can control how each exporter retries if a transmission to a backend fails.

Configuration options

Key	Kind	Type	Description
`initial-backoff`	`VALUE`	`Duration`	Initial backoff time
`max-attempts`	`VALUE`	`Integer`	Maximum number of retry attempts
`max-backoff`	`VALUE`	`Duration`	Maximum backoff time
`max-backoff-multiplier`	`VALUE`	`Double`	Maximum backoff multiplier

OpenTelemetry also supports a Zipkin exporter which it has recently deprecated.

Zipkin Exporter

Configuration options

Configuration for Zipkin exporters

Key	Kind	Type	Description
`compression`	`VALUE`	`i.h.t.o.CompressionType`	Compression type
`encoder`	`VALUE`	`z.c.SpanBytesEncoder`	Encoder type
`endpoint`	`VALUE`	`URI`	Collector endpoint to which this exporter should transmit
`timeout`	`VALUE`	`Duration`	Exporter timeout

The OpenTelemetry documentation describes the defaults; see the "Properties for Zipkin span exporters" section there.

OpenTelemetry defaults for Zipkin exporters

Setting	OpenTelemetry default value
`compression`	`none`
`encoder`	`JSON_V2`
`endpoint`	http://localhost:9411/api/v2/spans
`timeout`	10 seconds

OpenTelemetry provides other exporters, often used for debugging:

console
Writes telemetry data at the INFO level using the java.util.logging.Logger for io.opentelemetry.exporter.logging.Logging{signal}Expoerter
logging-otlp
Writes telemetry data in JSON format to the logger for the particular OpenTelemetry implementation class (e.g., OtlpJsonLoggingMetricExporter).

The console and logging-otlp have no configuration that is common across all signals.

Note

You need to add dependencies to your project for the exporters your application uses, even ones supported by Helidon config.

The table below describes the exporter types that Helidon configuration supports and what dependency your project needs to support them.

If you need to use an exporter that is not in the table:

Add a dependency on the OpenTelemetry artifact that contains that exporter type.
Add application code that prepares the exporter instance.
Prepare the Helidon OpenTelemetry builders programmatically and add your exporter instance to the builder.

In the table below, the Maven artifacts are all in the io.opentelemetry group.

Exporter type	OpenTelemetry Java Type	Artifact ID to add - `see`also the OpenTelemetry documentation
`otlp` (see `protocol` setting below)	`OtlpGrpc{signal}Exporter`	`opentelemetry-exporter-otlp`
`otlp` (see `protocol` setting below)	`OtlpHttp{signal}Exporter`	`opentelemetry-exporter-otlp`
`zipkin`	`ZipkinSpanExporter`	`opentelemetry-exporter-zipkin`
`console`	`Logging{signal}Exporter`	`opentelemetry-exporter-logging`
`logging_otlp`	`OtlpJsonLogging{signal}Exporter`		`SystemOutLogRecordExporeter`

Associating Each Processor and Reader with its Exporters

In configuration, you link processors and readers with the exporters you want each to use as follows:

For clarity, name each exporter if you have more than one.
Optionally specify for each processor or reader the names of the exporters it should use.
If you omit the exporter names for a processor or reader, Helidon associates it with all configured exporters. If you configure no exporters explicitly, Helidon associates the OpenTelemetry default exporter with the processor or reader.

The following examples show increasingly-complicated scenarios using tracing as the signal:

Default
Minimal configuration
Maximum flexibility

For many applications the default and minimal scenarios work well.

Default

This scenario includes no configuration at all for either processors or exporters.

OpenTelemetry uses its default processor (batch) with its default exporter (otlp using grpc). |

telemetry:
  service: "inventory"
  tracing:
    sampler: "always_off"

Copied

Minimal configuration

The user configures at most one processor and at most one exporter.

The single processor uses the single exporter.

No exporter name is declared or referenced.

telemetry:
  service: "inventory"
  tracing:
    sampler: "always_off"
    exporters:
      - type: zipkin
        compression: gzip
    processors:
      - type: batch
        max-queue-size: 50

Copied

Maximum flexibility

The user configures possibly multiple processors and possibly multiple named exporters. Each processor’s configuration lists the names of the exporters it should use; no names means all exporters.

The first processor (type batch) uses both exporters because it does not specify any exporter names. The second processor uses only the alternate-otlp exporter.|

telemetry:
  service: "inventory"
  tracing:
    sampler: "always_off"
    exporters:
      - type: zipkin
        compression: gzip
        name: "compressed-zipkin"
      - endpoint: "http://collect.com:4317"
        name: "alternate-otlp""
    processors:
      - type: batch
        max-queue-size: 50
      - type: simple
        exporters: ["alternate-otlp"]

Copied

Controlling OpenTelemetry Tracing Behavior

The settings under signals.tracing prepare an OpenTelemetry TracerProvider. When your application uses the Helidon tracing API to obtain a Tracer, Helidon uses the TracerProvider prepared from this config to create the tracer.

The next table describes the OpenTelemetry tracing settings.

Configuration options

Key	Kind	Type	Description
`attributes`	`VALUE`	`i.h.t.o.O.CustomMethods`	Name/value pairs passed to OpenTelemetry
`exporters`	`MAP`	`i.h.t.o.O.CustomMethods`	Span exporters
`processors`	`LIST`	`i.h.t.o.O.CustomMethods`	Settings for span processors
`sampler`	`VALUE`	`i.h.t.o.O.CustomMethods`	Tracing sampler
`span-limits`	`VALUE`	`i.h.t.o.O.CustomMethods`	Tracing span limits

OpenTelemetry applies the defaults described in the next table.

Default tracing settings applied by OpenTelemetry

Setting	OpenTelemetry default (and OpenTelemetry doc link)
`exporters`	`otlp` with `grpc` protocol - see "Properties: exporters, `otel.traces.exporter` property"
`processors`	`batch` with defaults - see "Properties for batch span processor(s)"
`sampler`	`parentbased_always_on` - see "Properties for sampler"
`span-limits`	See tracing "Properties for span limits"

Refer to the earlier sections about configuring attributes and configuring processors and exporters.

Sections below describe how to set up the tracing signal configuration:

Configuring the Span Sampler

OpenTelemetry offers different ways of sampling data—deciding which tracing spans tp capture and send to the backend. The OpenTelemetry documentation describes sampling in more detail.

Helidon configuration supports the sampler implementations that reside in the opentelemetry-sdk as listed in the table below. Other samplers are in other components. If you need to use one of those:

Add the relevant OpenTelemetry dependency to your project.
Instantiate the span sample you need.
Prepare the sampler and the OpenTelemetry-related builders programmatically and use your sampler to assign the sampler the OpenTelemetryTracer.Builder should use.

Configuration options

Key	Kind	Type	Default Value	Description
`param`	`VALUE`	`Double`		Sampler parameter
`type`	`VALUE`	`i.h.t.o.SamplerType`	`DEFAULT`	Sampler type

Configuring Span Limits

OpenTelemetry allows you to constrain certain aspects of the data it gathers in tracing spans. By assigning the settings in the table below, you can apply the span limits you want.

Configuration options

Key	Kind	Type	Description
`max-attribute-value-length`	`VALUE`	`Integer`	Maximum attribute value length
`max-attributes`	`VALUE`	`Integer`	Maximum number of attributes
`max-attributes-per-event`	`VALUE`	`Integer`	Maximum number of attributes per event
`max-attributes-per-link`	`VALUE`	`Integer`	Maximum number of attributes per link
`max-events`	`VALUE`	`Integer`	Maximum number of events
`max-links`	`VALUE`	`Integer`	Maximum number of links

The OpenTelemetry documentation describes the defaults; see the "Properties for span limits" section there.

OpenTelemetry defaults for span limits

Setting	OpenTelemetry Default
`max-attribute-value-length`	no limit
`max-attributes`	128
`max-attributes-per-event`	128
`max-events`	128
`max-links`	128

Controlling OpenTelemetry Metrics Behavior

The settings under signals.metrics prepare an OpenTelemetry MeterProvider. If your code uses the OpenTelemetry API to obtain an OpenTelemetry meter, meter provider, or meter builder, OpenTelemetry uses the MeterProvider prepared from this configuration.

The sections below describe Helidon config settings that correspond very directly to OpenTelemetry builders for the relevant OpenTelemetry type. Refer to the relevant OpenTelemetry documentation or Javadoc to understand the effect each setting has.

See the earlier sections about configuring attributes and configuring processors and exporters. A later section below describes some additional attributes on metrics exporters.

The next table describes the OpenTelemetry metrics settings.

Configuration options

Key	Kind	Type	Description
`attributes`	`VALUE`	`i.h.t.o.O.CustomMethods`	Name/value pairs passed to OpenTelemetry
`exporters`	`MAP`	`i.h.t.o.O.CustomMethods`	Metric exporter configurations, configurable using `io.helidon.telemetry.otelconfig.MetricExporterConfig`
`readers`	`LIST`	`i.h.t.o.O.CustomMethods`	Settings for metric readers
`views`	`LIST`	`i.h.t.o.O.CustomMethods`	Metric view information, configurable using `io.helidon.telemetry.otelconfig.ViewRegistrationConfig`

OpenTelemetry applies the defaults described in the next table.

Default metric settings applied by OpenTelemetry

Setting	OpenTelemetry default (and OpenTelemetry doc link)
`exporters`	`otlp` with `grpc` protocol - see that web page’s "Properties: exporters, `otel.metrics.exporter` property"] section.
`readers`	`PeriodicMetricReader` with an interval of one minute

Sections below describe how to set up the configuration that is specific to the metrics signal:

The following example illustrates some of the ways you can configure OpenTelemetry metrics behavior. It is neither complete nor typical.

Example OpenTelemetry Metrics Configuration

telemetry:
  service: "test-telemetry"
  signals:
    metrics:                                          
      exporters:
        - name: exp-1                                 
          type: otlp
          endpoint: "http://host:1234"
          temporality-preference: cumulative          
          default-histogram-aggregation:              
            type: base2-exponential-bucket-histogram
            max-buckets: 152
            max-scale: 19
        - name: exp-2                                 
          type: otlp
          protocol: grpc
          temporality-preference: delta               
          default-histogram-aggregation:              
            type: explicit-bucket-histogram
            bucket-boundaries: [3,5,7]
      readers:
        - type: periodic                              
          exporter: exp-1
          interval: PT6S
      views:
        - name: sum-view                              
          aggregation:
            type: sum
          description: "Sum view"
          instrument-selector:
            name: counter-selector
            type: counter
            meter-name: my-counter

Copied

Introduces the metrics configuration.
Introduces the first metric exporter (with name exp-1).
Indicates to accumulate measurement values since the previous transmission.
Prescribes to aggregate histograms for transmission using the OpenTelemetry BASE2_EXPONENTIAL_BUCKET_HISTOGRAM technique with the specified maximum number of buckets and maximum scale.
Introduces the second metric exporter (with name exp-2).
Indicates to transmit deltas since the last transmission.
Prescribes to aggregate histograms using a histogram with the given explicit bucket boundary values.
Declares a single metric reader of the OpenTelemetry PERIODIC types gathering data each 6 seconds.
Declares a single view to influence influence the transmission of the my-counter counter data.

Metric Exporters

The configuration for metrics exporters has several additional settings beyond those described earlier for exporters in general.

Configuration options

Key	Kind	Type	Default Value	Description
`certificate`	`VALUE`	`i.h.c.c.Resource`		Trusted certificates
`client.certificate`	`VALUE`	`i.h.c.c.Resource`		TLS certificate
`client.key`	`VALUE`	`i.h.c.c.Resource`		TLS client key
`compression`	`VALUE`	`i.h.t.o.CompressionType`		Compression the exporter uses
`connect-timeout`	`VALUE`	`Duration`		Connection timeout
`default-histogram-aggregation`	`VALUE`	`i.h.t.o.M.CustomMethods`		Preferred default histogram aggregation technique, configurable as `io.helidon.telemetry.otelconfig.MetricDefaultHistogramAggregationConfig`
`endpoint`	`VALUE`	`URI`		Endpoint of the collector to which the exporter should transmit
`headers`	`MAP`	`String`		Headers added to each export message
`internal-telemetry-version`	`VALUE`	`i.o.s.c.InternalTelemetryVersion`		Self-monitoring telemetry OpenTelemetry should collect
`memory-mode`	`VALUE`	`i.o.s.c.e.MemoryMode`		Memory mode
`protocol`	`VALUE`	`i.h.t.o.O.CustomMethods`	`DEFAULT`	Exporter protocol type
`retry-policy`	`VALUE`	`i.h.t.o.O.CustomMethods`		Retry policy
`temporality-preference`	`VALUE`	`i.h.t.o.M.CustomMethods`		Preferred output aggregation technique (how transmitted values reflect the values recorded locally), configurable as a `io.helidon.telemetry.otelconfig.MetricTemporalityPreferenceType` value: `CUMULATIVE, DELTA, LOWMEMORY`
`timeout`	`VALUE`	`Duration`		Exporter timeout
`type`	`VALUE`	`i.h.t.o.MetricExporterType`	`OTLP`	Metric exporter type

Metric Aggregation

OpenTelemetry allows control over how each exporter aggregates histogram data prior to transmission to a backend.

Configuration options

Key	Kind	Type	Description
`type`	`VALUE`	`i.h.t.o.MetricDefaultHistogramAggregationType`	Type of aggregation default

You can configure the explicit bucket boundaries for EXPLICIT_BUCKET_HISTOGRAM aggregation.

Configuration options

Key	Kind	Type	Description
`bucket-boundaries`	`LIST`	`Double`	Explicit bucket boundaries

You can configure the exponential histogram aggregation behavior.

Configuration options

Key	Kind	Type	Description
`max-buckets`	`VALUE`	`Integer`	Maximum number of buckets
`max-scale`	`VALUE`	`Integer`	Maximum scale

Metric Readers

An OpenTelemetry metric reader collects metric data in the server and then uses the associated metric exporter to send that data to the endpoint configured.

Configuration options

Key	Kind	Type	Default Value	Description
`exporter`	`VALUE`	`String`		Name of the configured metric exporter to use for this metric reader
`type`	`VALUE`	`i.h.t.o.MetricReaderType`	`PERIODIC`	Metric reader type

The periodic reader supports the following settings.

Configuration options

Key	Kind	Type	Default Value	Description
`exporter`	`VALUE`	`String`		Name of the configured metric exporter to use for this metric reader
`interval`	`VALUE`	`Duration`		Metric reader read interval
`type`	`VALUE`	`i.h.t.o.MetricReaderType`	`PERIODIC`	Metric reader type

Metric Views

OpenTelemetry metric views allow you to influence how meters are aggregated for reporting to backend systems.

Configuration options

Key	Kind	Type	Description
`aggregation`	`VALUE`	`i.h.t.o.V.CustomMethods`	Aggregation for the metric view, configurable as an `io.helidon.telemetry.otelconfig.AggregationType`: `DROP, DEFAULT, SUM, LAST_VALUE, EXPLICIT_BUCKET_HISTOGRAM, BASE2_EXPONENTIAL_BUCKET_HISTOGRAM`
`attribute-filter`	`VALUE`	`i.h.t.o.V.CustomMethods`	Attribute name filter, configurable as a string compiled as a regular expression using `java.util.regex.Pattern`
`cardinality-limit`	`VALUE`	`Integer`	Cardinality limit
`description`	`VALUE`	`String`	Metric view description
`instrument-selector`	`VALUE`	`i.h.t.o.V.CustomMethods`	Instrument selector, configurable using `io.helidon.telemetry.otelconfig.InstrumentSelectorConfig`
`name`	`VALUE`	`String`	Metrics view name

The instrument selector controls which meters this view reflects.

Configuration options

Key	Kind	Type	Description
`meter-name`	`VALUE`	`String`	Meter name
`meter-schema-url`	`VALUE`	`String`	Meter schema URL
`meter-version`	`VALUE`	`String`	Meter version
`name`	`VALUE`	`String`	Instrument name
`type`	`VALUE`	`i.o.s.m.InstrumentType`	Instrument type
`unit`	`VALUE`	`String`	Instrument unit

Controlling OpenTelemetry Logger Behavior

The settings under signal.logging prepare an OpenTelemetry `LoggerProvider.

The sections below describe Helidon config settings that correspond directly to OpenTelemetry builders for the relevant OpenTelemetry type. Refer to the relevant OpenTelemetry documentation or Javadoc to understand the effect each setting has.

The next table describes the OpenTelemetry logging settings.

Configuration options

Key	Kind	Type	Description
`attributes`	`VALUE`	`i.h.t.o.O.CustomMethods`	Name/value pairs passed to OpenTelemetry
`enabled`	`VALUE`	`Boolean`	Whether the OpenTelemetry logger should be enabled
`exporters`	`MAP`	`i.h.t.o.O.CustomMethods`	Log record exporters
`log-limits`	`VALUE`	`i.h.t.o.O.CustomMethods`	Log limits to apply to log transmission
`minimum-severity`	`VALUE`	`i.o.a.l.Severity`	Minimum severity level of log records to process
`processors`	`LIST`	`i.h.t.o.O.CustomMethods`	Settings for logging processors
`trace-based`	`VALUE`	`Boolean`	Whether to include only log records from traces which are sampled

OpenTelemetry uses the following defaults:

Default logging settings applied by OpenTelemetry

Setting	OpenTelemetry default
`exporters`	none
`minimum-severity`	undefined severity number
`processors`	no-op processor
`trace-based`	`false`

Refer to the earlier sections about configuring attributes and configuring processors and exporters.

Sections below explain how to set up the configuration that is specific to the logging signal:

Configuring Log Limits

Configuring Log Limits

For defaults, Helidon defers to the OpenTelemetry defaults, listed below.

Configuration options

Key	Kind	Type	Description
`max-attribute-value-length`	`VALUE`	`Integer`	Maximum length of an attribute value
`max-number-of-attributes`	`VALUE`	`Integer`	Maximum number of attributes allowed

OpenTelemetry applies the following defaults:

Default log limit settings applied by OpenTelemetry

Setting	OpenTelemetry default
`max-attribute-value-length`	`Integer.MAX_VALUE`
`max-number-of-attributes`	128
`exporters`	`otlp` with `grpc` protocol - see that web page’s "Properties: exporters, `otel.logger.exporter` property" section.
`log-limits`	`max-
`processors`	`otlp` - see that web page’s "Properties: logs" section.

The following example illustrates some of the ways you can configure OpenTelemetry logger behavior. It is neither complete nor typical.

Example OpenTelemetry Logger Configuration

telemetry:
  service: test-tel-logging
  global: false
  signals:
    logging:                              
      minimum-severity: TRACE             
      log-limits:                         
        max-attribute-value-length: 20
        max-number-of-attributes: 14
      processors:                         
        - type: batch
          schedule-delay: PT10S
          max-queue-size: 15
          max-export-batch-size: 5
          timeout: PT30S
        - type: simple
      exporters:                          
        - name: exp-1
          endpoint: "http://host:1234"

Copied

Introduces the logger configuration.
Sets the minimum log level severity to of log messages to send to the backend system.
Configures limits related to attributes that accompany log messages.
Prescribes the logger processors.
Prescribes the logger exporters.

Logger Exporters and Processors

You associate each logger processor with a logger exporter using the exporter’s name. See the earlier section for more information.

Additional Information

Helidon Documentation

Helidon Tracing

Contents

Overview

API

Managing the Global OpenTelemetry Instance

Assigning the Global Instance

Maven Coordinates

Using the OpenTelemetry implementation of the Helidon Tracing API

Adding OpenTelemetry Configuration and Builder Support

Enabling Automatic Spans for HTTP Requests

Enabling Automatic Metrics for Incoming HTTP Requests

Enabling OpenTelemetry for Outgoing Helidon Webclient Traffic

Specifying Additional OpenTelemetry Dependencies

Configuration

Controlling Overall OpenTelemetry Behavior

Configuration options

Common Configuration Across Signals

Assigning Attributes

Configuration options

Configuring Exporters and Processors/Readers

Configuring Processors (and readers)

Configuration options

Configuring Exporters

Setting Up OTLP Exporters

Configuration options

OTLP Retry Policy

Configuration options

Zipkin Exporter

Configuration options

Associating Each Processor and Reader with its Exporters

Default

Minimal configuration

Maximum flexibility

Controlling OpenTelemetry Tracing Behavior

Configuration options

Configuring the Span Sampler

Configuration options

Configuring Span Limits

Configuration options

Controlling OpenTelemetry Metrics Behavior

Configuration options

Metric Exporters

Configuration options

Metric Aggregation

Configuration options

Configuration options

Configuration options

Metric Readers

Configuration options

Configuration options

Metric Views

Configuration options

Configuration options

Controlling OpenTelemetry Logger Behavior

Configuration options

Configuring Log Limits

Configuration options

Logger Exporters and Processors

Additional Information

Helidon Documentation

OpenTelemetry Documentation

Managing the Global `OpenTelemetry` Instance