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.span-limits.max-attribute-value-length`	-	Maximum length of each attribute value.
`arconia.otel.traces.span-limits.max-number-of-attributes`	`128`	Maximum number of attributes per span.
`arconia.otel.traces.span-limits.max-number-of-attributes-per-event`	`128`	Maximum number of attributes per event.
`arconia.otel.traces.span-limits.max-number-of-attributes-per-link`	`128`	Maximum number of attributes per link.
`arconia.otel.traces.span-limits.max-number-of-events`	`128`	Maximum number of events per span.
`arconia.otel.traces.span-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-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, so you can configure the support for OpenTelemetry Traces using environment variables as well.

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

OpenTelemetry Java System Properties

Arconia supports the OpenTelemetry Java System Properties in alignment with the OpenTelemetry Java SDK Autoconfigure module. So you can configure the support for OpenTelemetry Traces using system properties as well.

This support is especially useful if you’re migrating from the OpenTelemetry-own Spring Boot Starter to Arconia OpenTelemetry, and you want to minimize the changes in your configuration. Check our migration guide for more information.

When possible, we recommend using the Arconia-specific properties instead of the OpenTelemetry Java system properties since they offer a more consistent configuration experience familiar to Spring Boot users.

Programmatic Configuration

You can further customize the auto-configured SdkTracerProvider instance via the SdkTracerProviderBuilderCustomizer API.

@FunctionalInterface
public interface SdkTracerProviderBuilderCustomizer {

    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() {
    ...
  }

}

You can also disable the auto-configuration entirely by excluding the io.arconia.opentelemetry.autoconfigure.sdk.traces.OpenTelemetryTracingAutoConfiguration class from the Spring Boot auto-configuration:

spring:
  autoconfigure:
    exclude:
      - io.arconia.opentelemetry.autoconfigure.sdk.traces.OpenTelemetryTracingAutoConfiguration

Exporting Traces

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

Table 6. General Traces Exporter Configuration Properties
Property	Default	Description
`arconia.otel.traces.exporter.type`	`otlp`	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.

Enabling/Disabling the Bridge

The bridge logic is provided by the Micrometer Tracing project, and it’s bundled with the Arconia OpenTelemetry Spring Boot Starter.

If you want to disable the bridge, you’ll need to exclude the dependency from the starter.

dependencies {
  implementation("io.arconia:arconia-opentelemetry-spring-boot-starter") {
    exclude group: 'io.micrometer', module: 'micrometer-tracing-bridge-otel'
  }
}