Skip to main content

Tracing Overview

ActivePivot provides a tracing API built on top of Spring Cloud Sleuth which borrows Dapper's terminology. Spring Cloud Sleuth provides a tracing facade that can integrates with OpenZipkin Brave tracer, OpenTracing, or any other Custom tracer implementing the contract org.springframework.cloud.sleuth.Tracer. An example of how Brave tracer is bridged to the Sleuth's API can be found in the org.springframework.cloud.sleuth.brave.bridge module.

By default, ActivePivot enables tracing for the CSV source and every query execution, including distributed queries (i.e. all queries endpoint are traced).

Configuration​

The default tracer defined within ActivePivot is a NoopTracer. It can be overridden by simply importing the configuration class TracingConfig. This configuration class will look for a org.springframework.cloud.sleuth.Tracer tracer bean in your classpath and wire it into the core tracing API.

Note : The TracingConfig#TRACING_BEAN must be loaded before any of your application beans.

Tracing configuration can be accomplished simply by importing the following dependencies:

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-sleuth</artifactId>
  <version>${spring-sleuth.version}</version>
</dependency>
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-sleuth-zipkin</artifactId>
  <version>${spring-sleuth.version}</version>
</dependency>

Alternatively, users are encouraged to implement their own tracing configuration for a better control and customization.

The above dependencies use Spring Boot auto-configuration to automatically configure the tracing stack. The dependency spring-cloud-starter-sleuth automatically uses Brave as the tracing library and consequently import any necessary Beans required by the tracer (for mor details see BraveAutoConfiguration. Similarly, the dependency spring-cloud-sleuth-zipkin configures the necessary beans allowing to send span to a zipkin server (for more details see ZipkinAutoConfiguration).

Zipkin API is available at Swagger UI - Zipkin.

Additionally, the sandbox provides a configuration class BraveTracingConfig providing additional configuration for Brave tracer, such as tracing support for servlet, sampling policy and custom error tag. Note that this configuration relies on the following dependency:

<dependency>
  <groupId>io.zipkin.brave</groupId>
  <artifactId>brave-instrumentation-spring-webmvc</artifactId>
  <version>${zipkin.brave.version}</version>
</dependency>

Tracing Properties​

The TracingConfig configuration class will look in your class path for the file tracing.properties, which may include additional tracing configuration. A typical configuration of such file may be as follows:

spring.zipkin.baseUrl=http://127.0.0.1:9411
spring.zipkin.api-path=api/v2/spans
spring.zipkin.service.name=pivot
spring.zipkin.sender.type=web
spring.sleuth.traceId128=true
activeviam.apm.zipkin.span.level=specific

For spring based properties please refer to the Spring Cloud Sleuth Reference Documentation.

Tracing granularity can be configured within ActivePivot using the property activeviam.apm.zipkin.span.level. This configuration is used to define the tracing granularity for ForkJoinTasks, that is, whether to continue a span or to create a new one upon a new task. Please refer the SpanLevel for more details.

Sometimes spring sleuth default sampling rate is not sufficient to capture all traces.
This default is set at 10 spans per second. It could be increased with spring.sleuth.sampler.rate.

Logging Integration​

Spring Cloud Sleuth configures the logging context with variables including the service name (%{spring.zipkin.service.name} or %{spring.application.name} if the previous one was not set), span ID (%{spanId}) and the trace ID (%{traceId}). These help you connect logs with distributed traces and allow you to group execution traces in further troubleshoot service such as ElasticSearch.

The default sandbox logging configuration (using logback) is: 

<encoder>
    <pattern>%d{dd/MM/yyyy HH:mm:ss.SSS} %-51([%X{traceId:-}/%X{spanId:-}]) %-5level %-70(%logger{5} %method %line) - %msg%n</pattern>
</encoder>

Usage​

A complete usage guide is available in the Spring Cloud Sleuth usage documentation.

ActivePivot com.activeviam.tracing.tracer.ITracer interface provides additional syntactic method for creating and starting spans. Furthermore, the API provides the following two extra methods:

  • Span startNextSpan(Object ownerObject, TraceContext traceContext, Span parentSpan) : for starting span for ForkJoinTask based on the aforementioned SpanLevel
  • Span startNextSpanWithParentContext(TraceContext parentContext) : for starting span with a given parent context

Both methods return a Spring Span and their usage remain the same as any other tracing method.