OpenTelemetry Metrics

Metrics are quantitative measurements of an application, captured and aggregated at runtime in regular time intervals. This page describes how to configure the metrics support in OpenTelemetry.

Learn more about metrics in the OpenTelemetry documentation.

Enabling/Disabling Metrics

Support for OpenTelemetry Metrics is enabled by default. You can disable it via configuration properties.

arconia:
  otel:
    metrics:
      enabled: false

Configuration Properties

You can configure the support for OpenTelemetry Metrics via configuration properties.

Table 1. Metrics Configuration Properties
Property	Default	Description
`arconia.otel.metrics.cardinality-limit`	`2000`	Maximum number of distinct points per metric.
`arconia.otel.metrics.exemplars.enabled`	`true`	Whether exemplars should be enabled.
`arconia.otel.metrics.exemplars.filter`	`trace-based`	Determines which measurements are eligible to become Exemplars. Options: `always-on`, `always-off`, `trace-based`.

OpenTelemetry Environment Variables

Arconia supports the OpenTelemetry Environment Variable Specification for configuring the OpenTelemetry integration. If both the OpenTelemetry Environment Variables and the Arconia configuration properties are set, the OpenTelemetry Environment Variables will take precedence.

This support is especially useful during deployment, where you can use the same set of standard environment variables to configure OpenTelemetry across different languages and frameworks.

You can disable this support by setting the arconia.otel.compatibility.environment-variable-specification configuration property to false.

Programmatic Configuration

You can further customize the auto-configured SdkMeterProvider instance via the OpenTelemetryMeterProviderBuilderCustomizer API.

@FunctionalInterface
public interface OpenTelemetryMeterProviderBuilderCustomizer {

    void customize(SdkMeterProviderBuilder builder);

}

Disabling the Auto-Configuration

The auto-configuration provided by Arconia for OpenTelemetry Metrics is enabled by default, but you can disable it as explained in the Enabling/Disabling Metrics section.

If you define a custom SdkMeterProvider bean, the auto-configuration will back off, and your custom bean will be used instead.

@Configuration(proxyBeanMethods = false)
public class MyMetricsConfiguration {

  @Bean
  public SdkMeterProvider myMeterProvider() {
    ...
  }

}

Exporting Metrics

By default, metrics are enabled and exported via OTLP, but you can change the type of exporter globally or specifically for metrics. If you set the exporter type to none, the corresponding signal will be disabled from exporting.

If a value is not provided specifically for metrics, the value configured for the general exporter is used, if available.

Table 2. General Metrics Exporter Configuration Properties
Property	Default	Description
`arconia.otel.exporter.type`	`otlp`	The type of OpenTelemetry exporter to use for observability signals. Options: `console`, `otlp`, `none`.
`arconia.otel.metrics.exporter.interval`	`60s`	The interval between two consecutive exports of metrics.
`arconia.otel.metrics.exporter.type`	``	The type of OpenTelemetry exporter to use for metrics. Options: `console`, `otlp`, `none`.
`arconia.otel.metrics.exporter.aggregation-temporality`	`cumulative`	The aggregation temporality to use for exporting metrics. Options: `cumulative`, `delta`, `low-memory`.
`arconia.otel.metrics.exporter.histogram-aggregation`	`explicit-bucket-histogram`	The aggregation strategy to use for exporting histograms. Options: `base2-exponential-bucket-histogram`, `explicit-bucket-histogram`.

For more information on exporting metrics to the console, refer to Console Exporter.

OTLP

When metrics are exported via OTLP (default behavior), you can configure the following properties.

If a value is not provided specifically for metrics, the value configured for the general OTLP export is used, if available. See OTLP.

Table 3. OTLP Metrics Exporter Configuration Properties
Property	Default	Description
`arconia.otel.metrics.exporter.otlp.compression`	`gzip`	Compression type to use for OTLP requests. Options: `none`, `gzip`.
`arconia.otel.metrics.exporter.otlp.connect-timeout`	`10s`	The maximum waiting time for the exporter to establish a connection to the endpoint.
`arconia.otel.metrics.exporter.otlp.endpoint`	`http://localhost:4317` (gPRC) or `http://localhost:4318/v1/metrics` (HTTP)	The endpoint to which telemetry data will be sent.
`arconia.otel.metrics.exporter.otlp.headers`	-	Additional headers to include in each request to the endpoint.
`arconia.otel.metrics.exporter.otlp.metrics`	`false`	Whether to generate metrics for the exporter itself.
`arconia.otel.metrics.exporter.otlp.protocol`	`http-protobuf`	Transport protocol to use for OTLP requests. Options: `grpc`, `http-protobuf`.
`arconia.otel.metrics.exporter.otlp.timeout`	`10s`	The maximum waiting time for the exporter to send each telemetry batch.
`arconia.otel.metrics.exporter.otlp.retry.max-attempts`	`5`	Maximum number of retries.
`arconia.otel.metrics.exporter.otlp.retry.backoff-config.first-backoff`	`1s`	Initial backoff time.
`arconia.otel.metrics.exporter.otlp.retry.backoff-config.max-backoff`	`5s`	Maximum backoff time.
`arconia.otel.metrics.exporter.otlp.retry.backoff-config.multiplier`	`1.5`	Backoff multiplier.

The default OTLP exporter uses HTTP/Protobuf. If you’d like to use gRPC, refer to OTLP gRPC.

Micrometer OTLP

Spring libraries and many other libraries from the Java ecosystem are instrumented using Micrometer Metrics. The Arconia OpenTelemetry Spring Boot Starter comes built-in with the Micrometer Metrics Registry OTLP provided by the Micrometer project, which exports Micrometer metrics directly to an OTLP endpoint without going through the OpenTelemetry API.

That means there will be two different exporters sending metrics to the same OTLP endpoint: the OpenTelemetry Metrics OTLP exporter (for metrics instrumented via OpenTelemetry API) and the Micrometer Metrics Registry OTLP (for metrics instrumented via Micrometer API).

If you’d rather export Micrometer metrics via the OpenTelemetry API instead of using a separate Micrometer-specific exporter, refer to the Micrometer Metrics Support section.

Enabling/Disabling

The Micrometer Metrics Registry OTLP can be disabled via configuration properties.

arconia.otel.exporter.otlp.micrometer.enabled: false

Alternatively, you can exclude the io.arconia:arconia-opentelemetry-micrometer-metrics-registry-otlp dependency from your project, which will disable the registry entirely.

Gradle
Maven

dependencies {
  implementation("io.arconia:arconia-opentelemetry-spring-boot-starter") {
    exclude group: "io.arconia", module: "arconia-opentelemetry-micrometer-metrics-registry-otlp"
  }
}

<dependency>
  <groupId>io.arconia</groupId>
  <artifactId>arconia-opentelemetry-spring-boot-starter</artifactId>
  <exclusions>
    <exclusion>
      <groupId>io.arconia</groupId>
      <artifactId>arconia-opentelemetry-micrometer-metrics-registry-otlp</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Configuration Properties

On top of the general metrics and OTLP configuration described previously, the Micrometer Metrics Registry OTLP provides additional configuration properties.

Table 4. Micrometer Metrics Registry OTLP Configuration Properties
Property	Default	Description
`arconia.otel.exporter.otlp.micrometer.base-time-unit`	`seconds`	Base time unit for Micrometer metrics.
`arconia.otel.exporter.otlp.micrometer.max-bucket-count`	`160`	Default maximum number of buckets to be used for exponential histograms, if configured. This has no effect on explicit bucket histograms.
`arconia.otel.exporter.otlp.micrometer.max-scale`	`20`	Max scale to use for exponential histograms, if configured.

Micrometer Metrics Support

Spring libraries and many other libraries from the Java ecosystem are instrumented using Micrometer Metrics. Arconia supports two ways to export Micrometer metrics to OpenTelemetry:

via the Micrometer Metrics Registry OTLP from the Micrometer project, which exports Micrometer metrics directly to an OTLP endpoint without going through the OpenTelemetry API;
via the Micrometer Metrics OpenTelemetry Bridge from the OpenTelemetry Java Instrumentation project.

The following table summarizes the differences between the two approaches:

Table 5. Differences between Micrometer Metrics Registry OTLP and Micrometer Metrics OpenTelemetry Bridge
Aspect	Micrometer Metrics Registry OTLP	Micrometer Metrics OpenTelemetry Bridge
Stable	✅	❌
OpenTelemetry API	❌	✅
Support non-OTLP exporters	❌	✅
Support exemplars	❌	✅
Support reading metrics	✅	❌
Maintained by the Micrometer team	✅	❌

By default, Arconia uses the Micrometer Metrics Registry OTLP. The main reason is that it’s stable and fully supported by the Micrometer project. However, if you need to export Micrometer metrics via the OpenTelemetry API, use a different exporter than OTLP, or need exemplar support, you can switch to the Micrometer Metrics OpenTelemetry Bridge instead. Refer to the Micrometer Metrics OpenTelemetry Bridge section for more details.

Micrometer Metrics OpenTelemetry Bridge (from OpenTelemetry Java Instrumentation)

Arconia optionally supports exporting Micrometer metrics via the Micrometer Metrics OpenTelemetry Bridge provided by the OpenTelemetry Java Instrumentation for Micrometer, which is based on the OpenTelemetry API and integrates fully with the OpenTelemetry SDK.

The Micrometer Metrics OpenTelemetry Bridge from the OpenTelemetry Java Instrumentation project is still experimental.

The OpenTelemetryMeterRegistry bean registered by this bridge doesn’t support reading metrics, but only bridging them to OpenTelemetry. For that reason, an additional SimpleMeterRegistry bean is registered for reading Micrometer metrics, an operation typically performed by the Spring Boot Actuator library.

Enabling/Disabling the Bridge

By default, the Arconia OpenTelemetry Spring Boot Starter comes built-in with the Micrometer Metrics Registry OTLP. You can choose to remove it and use the Micrometer Metrics OpenTelemetry Bridge instead. To achieve that, exclude the io.arconia:arconia-opentelemetry-micrometer-metrics-registry-otlp dependency from your project and include the io.arconia:arconia-opentelemetry-micrometer-metrics-bridge dependency instead.

Gradle
Maven

dependencies {
  implementation("io.arconia:arconia-opentelemetry-spring-boot-starter") {
    exclude group: "io.arconia", module: "arconia-opentelemetry-micrometer-metrics-registry-otlp"
  }
  implementation("io.arconia:arconia-opentelemetry-micrometer-metrics-bridge")
}

<dependency>
  <groupId>io.arconia</groupId>
  <artifactId>arconia-opentelemetry-spring-boot-starter</artifactId>
  <exclusions>
    <exclusion>
      <groupId>io.arconia</groupId>
      <artifactId>arconia-opentelemetry-micrometer-metrics-registry-otlp</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>io.arconia</groupId>
  <artifactId>arconia-opentelemetry-micrometer-metrics-bridge</artifactId>
</dependency>

If the Micrometer Metrics OpenTelemetry Bridge is included in the project, it will be auto-configured by default. You can disable it via configuration properties.

arconia.otel.metrics.micrometer-bridge.enabled: false

The Micrometer Metrics OpenTelemetry Bridge is mutually exclusive with the Micrometer Metrics Registry OTLP. If you have both dependencies in your project, it will be up to you to explicitly disable one of the two options via configuration properties or else neither will be auto-configured.

Configuration Properties

The Micrometer Metrics OpenTelemetry Bridge can be configured via configuration properties.

Table 6. Micrometer Metrics OpenTelemetry Bridge Configuration Properties
Property	Default	Description
`arconia.otel.metrics.micrometer-bridge.base-time-unit`	`seconds`	The base time unit for Micrometer metrics.
`arconia.otel.metrics.micrometer-bridge.histogram-gauges`	`true`	Whether to generate gauge-based Micrometer histograms.