Natchez Distributed Tracing for Scala

The Log Handler is a Natchez back-end designed to print traces to a logger in a structured JSON format.

Key characteristics:

• JSON Structure: Spans are emitted as JSON objects where span fields are represented as object properties.
• Hierarchy: A special children property is included in each JSON object to contain a list of its child spans, allowing for a nested representation of the trace.
• Tracing Support: While continued traces maintain correct parent span and trace IDs, full distributed tracing is not supported because this handler does not include a span collector.

Natchez provides support for various tracing back ends to export your telemetry data. If you are unsure which back end to choose, Jaeger is recommended as a starting point because it is easy to set up using Docker.

Supported back ends:
* Datadog
* Honeycomb
* Jaeger
* Lightstep
* Log
* Mock
* New Relic
* No-Op
* Odin
* OpenCensus
* OpenTelemetry

A Span is a managed resource that records timing information and metadata about a specific computation. Spans are organized into a tree structure: a Span can create child spans, allowing you to capture different phases of a larger computation.

Key characteristics:

• Hierarchical: Spans form a tree where child lifetimes are typically bounded by the parent's lifetime.
• Metadata: Each span contains a map of TraceValues (strings, booleans, and numbers) for user-defined information.
• Distributed: Spans can provide a Kernel (a hunk of data) that can be sent to remote computers (e.g., via HTTP headers) to link traces across different machines.

In modern Scala applications (especially those using Cats-Effect 3 or tagless-final style), you should use the Trace constraint rather than passing Span objects explicitly.

If your effect type F[_] has a Trace constraint (F[_]: Trace), you can perform tracing operations without direct reference to a Span instance. This allows you to:

• Add fields to the ambient span.
• Retrieve the current span's Kernel.
• Run a computation within a child span of the ambient span.

In tagless style applications, instead of passing a Span explicitly, you can use the Trace[F] constraint on your abstract effect F. This allows you to add fields to the ambient span, access its kernel, or run computations within a child span using Trace[F].span and Trace[F].put.

To use this, ensure your effect F has a Trace instance available in scope.

import cats.{ Applicative, Monad }
import cats.data.Kleisli
import cats.effect.MonadCancel
import cats.mtl.Local
import cats.syntax.all._
import natchez.{ Span, Trace }
import natchez.mtl._

// Example of a traced function using the Trace constraint
def wibble[F[_]: Monad: Trace](name: String, age: Int): F[Unit] =
  Trace[F].span("wibble") {
    for {
      _ <- Trace[F].put("name" -> name, "age" -> age)
      // ... actual method logic in F
    } yield ()
  }

Spans are constructed in three primary ways depending on their role in the trace:

Child Spans

Most spans are created from an existing Span or Trace instance using the span method.

• Explicit: Returns a Resource that you must .use.
• Ambient: Takes a continuation block to execute within the context of the child span.

Root Spans

Constructed via an EntryPoint when there is no parent span (e.g., when a new external web request is received).

Continued Spans

Constructed via an EntryPoint when the parent span exists on a different computer (e.g., when a new internal request is received via a distributed trace).

A Kernel is a back-end-specific hunk of data associated with a Span. It contains the necessary state to allow a trace to continue on a different computer or process. By passing a Kernel from one service to another, tracing becomes distributed.

Technically, a Kernel wraps a Map[String, String] (accessible via toHeaders), which is designed to be easily serialized into transport formats like HTTP headers. On the receiving end, the remote service parses these headers to reconstruct the span context and continue the trace.

Spans contain an internal map of string-keyed tags and TraceValues (strings, booleans, or numbers) called fields.

• Adding fields: Use the put method on either a Span (explicit) or Trace (ambient) instance.
• Standard Tags: You can use the Tags object to construct fields that follow emerging standards like OpenTracing or OpenTelemetry. Many back-ends recognize these.
• Custom Tags: You can use arbitrary strings as field tags for user-defined metadata.
• Note: Fields are write-only. You cannot inspect the fields of a span within your code.

By adding the natchez-mtl module, you can satisfy the Trace[F] constraint if you have MonadCancel[F, Throwable] and Local[F, Span[F]]. This approach is more general than the Kleisli method and allows for instantiating F as types like RWST.

// Requires natchez-mtl and Cats-MTL
def goLocal[F[_]](
  implicit ev0: MonadCancel[F, Throwable],
           ev1: Local[F, Span[F]]
): F[Unit] =
  wibble("bob", 42)