Tracing API reference

The core tracing API is in org.typelevel.otel4s.trace.

The main types form this construction and lifecycle chain:

For setup and task-oriented examples, see:

• Set up otel4s in a JVM application
• Create spans around effectful code
• Propagate trace context across service boundaries
• Use unmanaged spans when a span must end outside its scope
• Trace Resource and fs2.Stream code

TracerProvider[F]

TracerProvider[F] is the entry point for creating Tracer[F] instances.

The name identifies the instrumentation scope that emits spans. Use a stable library, module, or application name.

The companion object provides:

• TracerProvider[F] to summon an implicit provider
• TracerProvider.noop[F] to create a provider whose tracers are no-op

TracerBuilder[F]

TracerBuilder[F] adds instrumentation-scope metadata before creating a tracer.

Use TracerProvider[F].get when the tracer does not need a version or schema URL.

TracerBuilder.noop[F] creates a builder that returns a no-op tracer. It is also the builder returned by TracerProvider.noop[F].

import cats.effect.IO
import org.typelevel.otel4s.oteljava.OtelJava
import org.typelevel.otel4s.trace.Tracer

val program: IO[Unit] =
  OtelJava.autoConfigured[IO]().use { otel4s =>
    otel4s.tracerProvider
      .tracer("com.example.checkout")
      .withVersion("1.0.0")
      .get
      .flatMap { implicit tracer: Tracer[IO] =>
        Tracer[IO].span("checkout").use_
      }
  }

Tracer[F]

Tracer[F] creates spans, reads the current span, changes the active tracing scope, and propagates context through carriers.

Span access and creation

span and rootSpan accept individual attributes or an immutable collection of attributes. They are shortcuts for configuring and building a SpanBuilder.

Tracer.noop[F].currentSpanOrThrow returns its no-op span rather than raising an error.

Scope control

For the parent-selection rules, see Choosing parent spans and tracing scopes.

Carrier propagation

joinOrRoot reads an incoming carrier. propagate writes to an outgoing immutable carrier and returns the updated value. See Cross-service trace propagation for carrier and propagator details.

Effect lifting

liftTo[G] creates a Tracer[G] using an implicit cats.mtl.LiftKind[F, G]. The source and target effects require MonadCancelThrow.

The companion object provides:

• Tracer[F] to summon an implicit tracer
• Tracer.noop[F] to create a no-op tracer
• Tracer.Implicits.noop to supply a no-op implicit tracer

SpanBuilder[F]

SpanBuilder[F] stores span configuration. Calling build returns SpanOps[F]; it does not start the span.

The initial SpanBuilder.State is:

SpanBuilder.Parent.propagate follows the current tracing scope: a valid current span becomes the parent, no current span starts a root span, and noopScope keeps tracing disabled. When the span kind is None, the backend uses SpanKind.Internal. When the start timestamp is None, the backend uses Clock[F].realTime when the span starts. root and withParent both update the parent-selection setting. When both are called, the last call takes effect. Explicit timestamps must use the same epoch-based time source as Clock[F].realTime.

For lower-level state updates, SpanBuilder.Parent provides propagate, root, and explicit(context).

import cats.effect.IO
import org.typelevel.otel4s.Attribute
import org.typelevel.otel4s.trace.{SpanKind, Tracer}

def serverSpan(implicit tracer: Tracer[IO]): IO[Unit] =
  Tracer[IO]
    .spanBuilder("http.request")
    .withSpanKind(SpanKind.Server)
    .addAttribute(Attribute("http.route", "/users"))
    .build
    .surround(IO.unit)

SpanOps[F]

SpanOps[F] selects the lifecycle used to start and end a configured span.

use, surround, and resource use the builder's finalization strategy. The default strategy records errors and cancellation on abnormal termination.

startUnmanaged does not make the returned span current. Use Tracer[F].childScope(span.context) when later work should create children of it.

SpanOps.Res[F]

resource returns a managed SpanOps.Res[F] with these members:

The body of Resource.use does not automatically run in the managed span's scope. Apply trace to effects that should run in that scope. See Trace Resource and fs2.Stream code for the complete workflow.

Span[F]

Span[F] is the handle to a running span.

Attribute, event, link, and exception methods also accept immutable collections of attributes.

Only the first call to end determines the end timestamp. Spans passed to use or resource are ended by their managed lifecycle. Call end explicitly for spans created by startUnmanaged.

import cats.effect.IO
import org.typelevel.otel4s.Attribute
import org.typelevel.otel4s.trace.{StatusCode, Tracer}

def annotate(implicit tracer: Tracer[IO]): IO[Unit] =
  Tracer[IO].span("job.run").use { span =>
    span
      .addEvent("job.started")
      .flatMap(_ => span.addAttribute(Attribute("job.id", "42")))
      .flatMap(_ => span.setStatus(StatusCode.Ok))
  }

Supporting types

SpanContext

SpanContext contains the identifiers and propagation state associated with a span.

SpanContext.invalid is the standard invalid context. SpanContext.apply creates a context from trace and span identifiers, flags, state, and the remote flag.

SpanKind

StatusCode

SpanFinalizer.Strategy

SpanFinalizer.Strategy is a PartialFunction[Resource.ExitCase, SpanFinalizer].

The built-in strategies are:

• reportAbnormal, the default, which records an exception and error status for failure and sets an error status for cancellation
• empty, which does not apply a finalizer

Custom strategies can return finalizers created with SpanFinalizer.recordException, setStatus, addAttribute, addAttributes, updateName, addEvent, addLink, or multiple.

Related material

• Provide a no-op tracer
• Choosing parent spans and tracing scopes
• Tracing Resource and fs2.Stream scopes
• How otel4s context propagation works
• Cross-service trace propagation