Design

Trace 4 Cats partially implements OpenTelemetry tracing, just enough that traces can be exported to Jaeger or the OpenTelemetry collector.

Trace Injection

Based heavily on Natchez but exposes the specific Trace4Cats functionality of setting the span kind and status. A Trace typeclass is used to propagate a span context throughout the callstack.

See the example below for more information, usage, and interoperability with Natchez.

Interfaces

The following interfaces allow different backends to be plugged in and may adjust how traces are sampled.

SpanExporter and SpanCompleter

SpanExporters are used to forward a batch of spans to as certain location in a certain format. Multiple implementations may be combined using the provided Monoid instance.

SpanCompleters are used when a spans is finished. They will usually delegate to a SpanExporter of the same format. Multiple implementations may be combined using the provided Monoid instance.

SpanCompleters should generally buffer spans in a circular buffer so that completing a span should be non-blocking for the hosting application. SpanExporters may be blocking, however a buffering wrapper implementation is available, which is used in the Collectors to provide non-blocking behaviour when accepting new spans.

The following implementations are provided out of the box:

• Jaeger agent via Thrift over UDP and Protobufs over GRPC
• OpenTelemetry collector via Protobufs over GRPC and JSON over HTTP
• Log using Log4Cats
• Trace4Cats Avro over TCP, UDP or Kafka
• Stackdriver Trace over HTTP or GRPC
• Datadog over HTTP
• NewRelic over HTTP

SpanSampler

Used to decide whether or not a span should be sampled. For more information on sampling see the associated documentation

The following implementations are provided out of the box:

• Always
• Never
• Probabilistic
• Rate

AttributeValue

An ADT for representing different types of span attributes, currently supports the following types as single values or as lists.

• String
• Boolean
• Double
• Long

Unlike many other tracing libraries, AttributeValues are lazily evaluated, so if a span is not sampled the value will not be computed. This is especially useful when a value requires some computation before it can be displayed, such as the size of a collection.

ToHeaders

Convert a span context to and from message or http headers.

The following implementations are provided out of the box:

• W3C Trace Context
• B3
• B3 Single Header
• Envoy

When using ToHeaders.all the span context will be encoded using all of these header types and decoded using each encoding as a fallback, allowing for maximum interoperability between tracing systems.