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.

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 : The TracingConfig#TRACING_BEAN must be loaded before any of your application beans.

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.

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.