> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing Overview

ActivePivot provides a tracing API built on top of [Spring Cloud Sleuth](https://spring.io/projects/spring-cloud-sleuth)
which borrows [Dapper's](https://research.google/pubs/pub36356/) terminology. Spring Cloud Sleuth provides a tracing facade
that can integrates with [OpenZipkin Brave](https://github.com/openzipkin/brave) tracer, [OpenTracing](https://opentracing.io/),
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).

## Tracing Setup

### Dependencies Versions

```xml theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
<spring-sleuth.version>                   3.1.3            </spring-sleuth.version>
```

```xml theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
<zipkin.brave.version>                    5.13.9           </zipkin.brave.version>
```

### Dependencies Setup

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

```xml theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
<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>
<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave-instrumentation-spring-webmvc</artifactId>
    <version>${zipkin.brave.version}</version>
</dependency>
```

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](https://github.com/spring-cloud/spring-cloud-sleuth/blob/3.1.x/spring-cloud-sleuth-autoconfigure/src/main/java/org/springframework/cloud/sleuth/autoconfig/brave/BraveAutoConfiguration.java)).

Similarly, the dependency `spring-cloud-sleuth-zipkin` configures the necessary beans allowing to send span to a zipkin server (for more details see
[ZipkinAutoConfiguration](https://github.com/spring-cloud/spring-cloud-sleuth/blob/3.1.x/spring-cloud-sleuth-autoconfigure/src/main/java/org/springframework/cloud/sleuth/autoconfig/zipkin2/ZipkinAutoConfiguration.java)).

The `brave-instrumentation-spring-webmvc` dependency automatically uses `TracingFilter` to extract trace state from incoming requests.
Then, it reports Zipkin how long each request takes, along with relevant tags like the http url (for more details see [brave-instrumentation-spring-webmvc](https://github.com/openzipkin/brave/blob/9f4f166f97a3645e7514c0db920eb02bb3666e7d/instrumentation/spring-webmvc/README.md))

> Zipkin API is available at [Swagger UI - Zipkin](https://zipkin.io/zipkin-api/).

### properties

To define the required properties for tracing, you may create a configuration file `tracing.properties`. A typical configuration of such file may be as follows:

```properties theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
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](https://docs.spring.io/spring-cloud-sleuth/docs/current/reference/html/).

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`. There are three possibilities :

* NONE : continues the parent span.
* SPECIFIC : mode creates new child span when some significant tasks are being invoked, specified in `Tracing#IMPORTANT_TASKS`.
* TASK :  mode creates new child span whenever a new ForkJoinTask is being called.

Please refer the \{@javadocLink: SpanLevel|com/activeviam/tracing/tracer/ITracer.SpanLevel.html} 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`.

Of course, you can add/remove properties to meet your needs.

### Configuration Class

You also need the configuration class `TracingConfig`, which you may include in your application configuration class.
This class will look in your classpath for the `tracing.properties` and will map the required properties to set up the tracing.

It will also look for a `org.springframework.cloud.sleuth.Tracer` tracer bean in your classpath and wire it into the core
tracing API.
The default tracer defined within ActivePivot is a `NoopTracer` which does no tracing.
By importing the configuration class `TracingConfig`, and by using the above brave dependency, a `BraveTracer` will automatically override the `NoopTracer`.

Users are encouraged to implement their own tracing configuration for a better control and customization

### Brave Additional Configuration

You can define additional configuration for the brave tracer.
For instance, in the sandbox project, we define a default trace sampling policy and enable tracing for servlet.

These configurations can be found in `BraveTracingConfig` class which is imported in the `SandboxConfig` class:

```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
@Configuration
@ConditionalOnClass({Tracer.class})
public class BraveTracingConfig {
  @Bean
  public Sampler defaultSampler() {
    return Sampler.ALWAYS_SAMPLE;
  }
  @Bean
  public ServletContextInitializer servletTracing() {
    return servletContext -> {
      // Enables tracing for servlet
      final DelegatingTracingFilter filter = new DelegatingTracingFilter();
      final String filterName = Conventions.getVariableName(filter);
      final FilterRegistration.Dynamic registration = servletContext.addFilter(filterName, filter);
      registration.addMappingForUrlPatterns(EnumSet.of(DispatcherType.REQUEST), true, "/*");
    };
  }
}
```

You can add more configuration, for example to define custom error handling, etc.

### Disable Tracing

If you decide to deactivate tracing, use these properties:

```properties theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
spring.sleuth.enabled=false
spring.zipkin.enabled=false
```

### 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:

```xml theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
<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](https://docs.spring.io/spring-cloud-sleuth/docs/current/reference/html/using.html#using).

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.