OpenTelemetry Traces

Traces track requests as they flow through all the services and components of an application. This page describes how to configure the tracing support in OpenTelemetry.

Learn more about traces and baggage in the OpenTelemetry documentation.

Enabling/Disabling Traces

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

arconia:
  otel:
    traces:
      enabled: false

Configuration Properties

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

Sampling

How to sample traces.

Table 1. Sampling Configuration Properties
`arconia.otel.traces.sampling.strategy`
`128`
How to sample traces. Options: `always-on`, `always-off`, `trace-id-ratio`, `parent-based-always-on`, `parent-based-always-off`, `parent-based-trace-id-ratio`.
`management.tracing.sampling.probability`
`0.1`
The probability ratio for sampling a span. Used when the sampling strategy is `trace-id-ratio` or `parent-based-trace-id-ratio`.

Propagation

Arconia OpenTelemetry relies on Spring Boot Actuator for configuring propagation, based on Micrometer Tracing. For convenience, the configuration properties from Spring Boot Actuator are included here.

For more information, refer to the Micrometer Tracing and Spring Boot Actuator documentation.

Table 2. Propagation Configuration Properties
`management.tracing.propagation.type`
``
Tracing context propagation types produced and consumed by the application. Setting this property overrides the more fine-grained propagation type properties.
`management.tracing.propagation.produce`
`w3c`
Tracing context propagation types produced by the application.
`management.tracing.propagation.consume`
`w3c`, `b3`, `b3-multi`
Tracing context propagation types consumed by the application.

Baggage

Arconia OpenTelemetry relies on Spring Boot Actuator for configuring baggage management, based on Micrometer Tracing. For convenience, the configuration properties from Spring Boot Actuator are included here.

For more information, refer to the Micrometer Tracing and Spring Boot Actuator documentation.

Table 3. Baggage Configuration Properties
`management.tracing.baggage.enabled`
`true`
Whether to enable Micrometer Tracing baggage propagation.
`management.tracing.baggage.correlation.enabled`
`true`
Whether to enable correlation of the baggage context with logging contexts.
`management.tracing.baggage.correlation.fields`
`w3c`, `b3`, `b3-multi`
List of fields that should be correlated with the logging context. That means that these fields would end up as key-value pairs in e.g. MDC.
`management.tracing.baggage.remote-fields`
``
List of fields that are referenced the same in-process as it is on the wire. For example, the field "x-vcap-request-id" would be set as-is including the prefix.
`management.tracing.baggage.tag-fields`
``
List of fields that should automatically become tags.

Span Limits

Constraints for the data captured by spans.

Table 4. Span Limits Configuration Properties
Property	Default	Description
`arconia.otel.traces.limits.max-attribute-value-length`	-	Maximum length of each attribute value.
`arconia.otel.traces.limits.max-number-of-attributes`	`128`	Maximum number of attributes per span.
`arconia.otel.traces.limits.max-number-of-attributes-per-event`	`128`	Maximum number of attributes per event.
`arconia.otel.traces.limits.max-number-of-attributes-per-link`	`128`	Maximum number of attributes per link.
`arconia.otel.traces.limits.max-number-of-events`	`128`	Maximum number of events per span.
`arconia.otel.traces.limits.max-number-of-links`	`128`	Maximum number of links per span.

Span Processor

Configuration for the batch span processor.

Table 5. Span Processor Configuration Properties
Property	Default	Description
`arconia.otel.traces.processor.export-unsampled-spans`	`false`	Whether to export unsampled spans.
`arconia.otel.traces.processor.export-timeout`	`30s`	The maximum allowed time to export spans.
`arconia.otel.traces.processor.max-export-batch-size`	`512`	The maximum number of spans to export in a single batch.
`arconia.otel.traces.processor.max-queue-size`	`2048`	The maximum number of spans that can be queued before batching.
`arconia.otel.traces.processor.metrics`	`false`	Whether to generate metrics for the span processor.
`arconia.otel.traces.processor.schedule-delay`	`5s`	The interval between two consecutive exports.

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 Logs 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 SdkTracerProvider instance via the OpenTelemetryTracerProviderBuilderCustomizer API.

@FunctionalInterface
public interface OpenTelemetryTracerProviderBuilderCustomizer {

    void customize(SdkTracerProviderBuilder builder);

}

Disabling the Auto-Configuration

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

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

@Configuration(proxyBeanMethods = false)
public class MyTracingConfiguration {

  @Bean
  public SdkTracerProvider myTracerProvider() {
    ...
  }

}

Exporting Traces

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

If a value is not provided specifically for traces, the value configured for the general exporter is used.

Table 6. General Traces 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.traces.exporter.type`	``	The type of OpenTelemetry exporter to use for traces. Options: `console`, `otlp`, `none`.

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

OTLP

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

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

Table 7. OTLP Traces Exporter Configuration Properties
Property	Default	Description
`arconia.otel.traces.exporter.otlp.compression`	`gzip`	Compression type to use for OTLP requests. Options: `none`, `gzip`.
`arconia.otel.traces.exporter.otlp.connect-timeout`	`10s`	The maximum waiting time for the exporter to establish a connection to the endpoint.
`arconia.otel.traces.exporter.otlp.endpoint`	`http://localhost:4317` (gPRC) or `http://localhost:4318/v1/traces` (HTTP)	The endpoint to which telemetry data will be sent.
`arconia.otel.traces.exporter.otlp.headers`	-	Additional headers to include in each request to the endpoint.
`arconia.otel.traces.exporter.otlp.metrics`	`false`	Whether to generate metrics for the exporter itself.
`arconia.otel.traces.exporter.otlp.protocol`	`http-protobuf`	Transport protocol to use for OTLP requests. Options: `grpc`, `http-protobuf`.
`arconia.otel.traces.exporter.otlp.timeout`	`10s`	The maximum waiting time for the exporter to send each telemetry batch.

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

Micrometer Tracing Bridge

Spring libraries and other libraries from the Java ecosystem are instrumented using Micrometer Tracing (via the Micrometer Observation API) and rely on Micrometer for context propagation and baggage management. The Arconia OpenTelemetry Spring Boot Starter provides a bridge that allows you to convert Micrometer traces into OpenTelemetry Traces and export them via OTLP.

The bridge logic is provided by the Micrometer Tracing project, and it’s bundled with the Arconia OpenTelemetry Spring Boot Starter. Disabling the bridge is not a supported configuration option, since Micrometer Tracing is a core part of the OpenTelemetry support in Spring Boot.