otel4s

otel4s integrates with various Typelevel and functional Scala libraries to provide observability (tracing and metrics) across different layers of your application.

Available Integrations:

• Web & HTTP:

  • http4s-otel4s-middleware: Middleware for http4s to integrate tracing and metrics seamlessly.
  • tapir: Supports server traces via otel4s.
  • sttp: sttp 4.x provides metered and traced backends.

• Database:

  • otel4s-doobie: Integration for doobie providing traces of database queries (supports HikariCP).

• Messaging & Streaming:

  • fs2-queues-otel4s: Provides traces and metrics for fs2-queues messaging systems.
  • fs2-kafka-otel4s: Provides consumer and producer traces for fs2-kafka.
  • fs2-grpc: The fs2-grpc-otel4s-trace module provides server and client tracing capability.

• Experimental Features:

  • otel4s-experimental: Includes instrumented cats.effect.std.Queue, runtime metrics, and @span annotations.
  • otel4s-opentelemetry-java: An experimental distribution of the OpenTelemetry Java agent with instrumentation for Cats Effect and otel4s.

When you need to bypass the automatic context discovery and specify a parent manually, you have two primary options depending on the scope of the change:

1. childScope(parent): Use this when you want multiple spans created within a block to all inherit the same explicit SpanContext. It changes the tracing context for the entire duration of the block.
2. withParent(parent): Use this when you want to attach only one specific span to an explicit parent without affecting the tracing context for any other spans in the surrounding scope.

Use childScope for grouping related operations under a known parent, and withParent for one-off attachments (e.g., attaching a specific span to an outer span even if other spans were created in between).

// Using childScope to group multiple spans under one parent
def continueMany(parent: SpanContext)(implicit tracer: Tracer[IO]): IO[Unit] =
  Tracer[IO].childScope(parent) {
    for {
      _ <- Tracer[IO].span("step-1").use_
      _ <- Tracer[IO].span("step-2").use_
    } yield ()
  }

// Using withParent to attach a single span to a specific parent
def attachOneToOuter(implicit tracer: Tracer[IO]): IO[Unit] =
  Tracer[IO].span("span").use { outer =>
    Tracer[IO].span("span-2").use_ >>
      Tracer[IO].spanBuilder("span-3").withParent(outer.context).build.use_
  }

When using the otel4s-oteljava backend, you must choose how to access the SDK based on who owns the SDK lifecycle:

OtelJava.autoConfigured

Use this when your application is responsible for creating the SDK. It creates an isolated, non-global SDK instance using OpenTelemetry Java autoconfiguration.

Common scenarios:

• Your application starts the SDK itself.
• You configure exporters and SDK settings via environment variables or JVM properties.
• You do not need to reuse an SDK already created by another library, framework, or agent.

Warning: If a global SDK already exists in the process, using autoConfigured creates an isolated instance which may make telemetry behavior harder to reason about.

OtelJava.global

Use this when the SDK is already configured elsewhere and otel4s needs to join that existing setup. It reads the current process-wide OpenTelemetry instance.

Common scenarios:

• An agent (like the OpenTelemetry Java agent) configures the global SDK.
• A framework or bootstrap layer initializes OpenTelemetry before your otel4s code runs.
• You need otel4s and Java libraries to observe the same process-wide SDK state.

In otel4s metrics testing, MetricExpectation does not check points individually in isolation. Instead, it evaluates a PointSetExpectation against the entire collection of points for a metric. This allows you to assert presence, absence, cardinality, and collection-wide invariants.

All typed metric expectations provide several shorthand methods for composing PointSetExpectations:

• points(...): For raw PointSetExpectation composition.
• containsPoints(...): Shorthand for PointSetExpectation.contains(...) (requires distinct matching points, but allows extras).
• exactlyPoints(...): Shorthand for PointSetExpectation.exactly(...) (requires exactly the expected points and no extras).
• pointCount(...): Shorthand for PointSetExpectation.count(...) (checks total count).
• withoutPointsMatching(...): Shorthand for PointSetExpectation.none(...) (asserts no points match the criteria).
• pointsWhere(...): Shorthand for PointSetExpectation.predicate(...) (allows custom collection-wide assertions).

// Example of using shorthand methods on a MetricExpectation
MetricExpectation
  .sum[Long]("service.requests")
  .containsPoints(
    PointExpectation.numeric(1L).attributesSubset(Attribute("region", "eu")),
    PointExpectation.numeric(1L).attributesSubset(Attribute("region", "us"))
  )

Structural matching allows you to define the shape of your traces using trees and forests.

Tree Expectations (TraceExpectation)

Used to describe a single subtree:

• TraceExpectation.leaf(...): A span with no expected children.
• TraceExpectation.ordered(...): A subtree whose direct children must appear in a specific order.
• TraceExpectation.unordered(...): A subtree whose direct children may appear in any order.

Forest Expectations (TraceForestExpectation)

Used to describe the full set of exported spans:

• TraceForestExpectation.ordered(...): Requires root spans to appear in a specific order.
• TraceForestExpectation.unordered(...): Ignores the order of root spans.
• TraceForestExpectation.empty: Requires no finished root spans.

Note: Both ordered and unordered modes still require the exact number of direct children or roots.

// A leaf span
TraceExpectation.leaf(SpanExpectation.name("db.query"))

// An ordered subtree
TraceExpectation.ordered(
  SpanExpectation.name("request").noParentSpanContext,
  TraceExpectation.leaf(SpanExpectation.name("decode")),
  TraceExpectation.leaf(SpanExpectation.name("persist"))
)