58 - Observability: Spans, Annotations, and the OTel Layer

Previous · Next

Observability in Effect is part of the runtime, not a separate library to thread through function signatures. The fiber carries a tracer, a log handler, and an annotation context as ambient state.

Effect.log* emits structured records; Effect.withSpan opens a span; Effect.annotateLogs and Effect.annotateCurrentSpan attach context. In development the default Logger writes to the console; in production a single NodeSdk.layer from @effect/opentelemetry ships everything to OpenTelemetry.

The program code does not change.

What you’ll work through

index.test.ts contains four beats: attaching structured context with Effect.annotateLogs, opening a named span with Effect.withSpan, combining Effect.fn with spans for automatic per-call labelling, and swapping in the OTel layer so the same program ships to a real observability backend.

By the end your business code should be agnostic to the observability backend — logs, spans, and annotations flow through the runtime, not through function signatures.

What the Runtime Tracks

1
 Effect runtime (per fiber)
2
 ─────────────────────────
3
   Logger        ◄── Effect.log, Effect.logInfo, …
4
   Annotations  ◄── Effect.annotateLogs (logs)
5
                ◄── Effect.annotateCurrentSpan (spans)
6
   Tracer        ◄── Effect.withSpan (open) / span.end (close)
7
                ◄── child spans nest automatically

Each is configurable via a Layer. Replace the default Logger; provide a tracer; the rest of the program is unchanged.

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<void, never, never>
4
//      ▼
5
const program = Effect.gen(function* () {
6
  yield* Effect.logInfo("checkout started")
7
  yield* Effect.logWarning("retrying upstream", { attempt: 2 })
8
})

1
import { Effect } from "effect"
2

3
const handle = (requestId: string) =>
4
  Effect.gen(function* () {
5
    yield* Effect.logInfo("received")
6
    yield* Effect.logInfo("done")
7
  }).pipe(Effect.annotateLogs({ requestId }))

1
import { Effect } from "effect"
2

3
const fetchUser = (id: string) =>
4
  Effect.gen(function* () {
5
    yield* Effect.annotateCurrentSpan("user.id", id)
6
    return { id, name: "Ada" }
7
  }).pipe(Effect.withSpan("Users.fetch", { attributes: { component: "users" } }))
8

9
const checkout = (id: string) =>
10
  Effect.gen(function* () {
11
    const user = yield* fetchUser(id)
12
    return user
13
  }).pipe(Effect.withSpan("checkout"))
14

15
// Trace tree when run:
16
//   checkout
17
//     └── Users.fetch  (user.id="user-1")

1
import { Effect } from "effect"
2

3
const fetchUser = Effect.fn("Users.fetch")(function* (id: string) {
4
  yield* Effect.annotateCurrentSpan("user.id", id)
5
  return { id, name: "Ada" }
6
})

1
import { Effect } from "effect"
2

3
const checkout = (orderId: string) =>
4
  Effect.gen(function* () {
5
    yield* Effect.log("checkout.start")
6
    yield* validateOrder(orderId)
7
    yield* chargeCard(orderId)
8
    yield* shipOrder(orderId)
9
  }).pipe(
10
    Effect.withSpan("Checkout.run"),                 // one span around the whole flow
11
    Effect.annotateLogs({ orderId, component: "checkout" }), // every log inside carries these
12
  )

Wiring OpenTelemetry

Configures the tracer, metric reader, and log processor with one Layer. Mirrors the example in repos/effect/packages/opentelemetry/examples/otlp-exporter.ts.

1
import { NodeSdk } from "@effect/opentelemetry"
2
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"
3
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"
4
import { Effect } from "effect"
5

6
const TracingLive = NodeSdk.layer(() => ({
7
  resource: { serviceName: "checkout" },
8
  spanProcessor: new BatchSpanProcessor(
9
    new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" }),
10
  ),
11
}))
12

13
Effect.runFork(program.pipe(Effect.provide(TracingLive)))

Details

NodeSdk.layer accepts a thunk so the SDK is constructed lazily, the layer is the only place that imports @opentelemetry/*. For local development swap OTLPTraceExporter for ConsoleSpanExporter and BatchSpanProcessor for SimpleSpanProcessor; everything else stays the same.

When to Use

Any service that ships to production. The same layer also wires metric readers (metricReader) and structured log exporters (logRecordProcessor) when those fields are populated, one composition root for all three signals.

A Composite Example

Annotates a request scope, opens nested spans, and threads the trace context through a service-driven workflow.

1
import { Effect } from "effect"
2

3
const fetchUser = Effect.fn("Users.fetch")(function* (id: string) {
4
  yield* Effect.annotateCurrentSpan("user.id", id)
5
  return { id, name: "Ada" }
6
})
7

8
const sendReceipt = Effect.fn("Receipts.send")(function* (userId: string) {
9
  yield* Effect.logInfo("queued receipt")
10
  return userId
11
})
12

13
//      ┌─── Effect<void, never, never>
14
//      ▼
15
const handleCheckout = (requestId: string, userId: string) =>
16
  Effect.gen(function* () {
17
    const user = yield* fetchUser(userId)
18
    yield* sendReceipt(user.id)
19
  }).pipe(
20
    Effect.annotateLogs({ requestId }),
21
    Effect.withSpan("checkout", { attributes: { "request.id": requestId } }),
22
  )

The trace tree looks like checkout → Users.fetch → Receipts.send. Every log inside the scope carries requestId.

None of this requires passing a logger or tracer through the function arguments.

Common Pitfalls

1, console.log in Effect code. It bypasses the runtime’s logger entirely, levels, annotations, and span correlation are lost. Use Effect.log*.

2, Interpolating context into messages. logInfo(\user ${id} logged in`)is unindexable. Pass{ userId }as a structured argument or useannotateLogs`.

3, Anonymous workflows in traces. A span named "<anonymous>" is useless. Use Effect.fn("Component.action") or Effect.withSpan with an explicit name.

4, Forgetting the production layer. Without Effect.provide(TracingLive) the SDK is never initialised; spans are created but never exported. The layer is the only production-vs-development knob.

See Also

• Previous, 57-http-client-patterns: where spans first earn their keep.
• Related, 27-effect-fn: the constructor Effect.fn ties spans to function names.
• Reference, repos/effect/packages/opentelemetry/examples/ for runnable exporter setups, and repos/effect/packages/opentelemetry/src/NodeSdk.ts for the full Configuration shape.

Run the tests: pnpm test 58-observability

The full test suite

The index.test.ts for this lesson, verbatim from steps/58-observability/.

1
import { describe, expect, it } from "vite-plus/test"
2
import { Effect, Metric } from "effect"
3

4
describe("observability runtime services", () => {
5
  it("adds structured log annotations and a tracing span", async () => {
6
    const program = Effect.log("checkout complete").pipe(
7
      Effect.annotateLogs({ orderId: "o-1" }),
8
      Effect.withSpan("Checkout.complete", { attributes: { orderId: "o-1" } }),
9
    )
10
    await Effect.runPromise(program)
11
  })
12

13
  it("records metrics through the runtime", async () => {
14
    const counter = Metric.counter("tutorial.requests").pipe(Metric.withConstantInput(1))
15
    const value = await Effect.runPromise(Effect.track(Effect.void, counter).pipe(Effect.andThen(Metric.value(counter))))
16
    expect(value.count).toBeGreaterThanOrEqual(1)
17
  })
18
})