Tracer

Defines the low-level tracing model used by Effect.

A span records the lifetime of an operation, including its name, parent, attributes, links, annotations, sampling decision, kind, and completion status. The module also defines the tracer service, parent-span context, external span support, trace propagation settings, and the default in-memory span implementation.

21 exports Added in v2.0.0 Source

Constants

ParentSpanKey

Added in v4.0.0 Source

Defines the string key for the parent-span context service.

When to use

Use when you need the raw context key for parent span lookup in lower-level tracing code.

Signature

declare const ParentSpanKey: "effect/Tracer/ParentSpan"

Example

(Reading the parent span key)

import { Tracer } from "effect"

// The key used to identify parent spans in the context
Tracer.ParentSpanKey // => "effect/Tracer/ParentSpan"

TracerKey

Added in v4.0.0 Source

Defines the string key for the active tracer context reference.

When to use

Use when you need the raw context key for active tracer lookup in lower-level tracing code.

Signature

declare const TracerKey: "effect/Tracer"

Constructors

externalSpan

Added in v2.0.0 Source

Creates an ExternalSpan from trace and span identifiers, defaulting sampled to true and annotations to an empty context when they are not provided.

Signature

declare function externalSpan(options: {
  readonly annotations?: Context<never>;
  readonly sampled?: boolean;
  readonly spanId: string;
  readonly traceId: string;
}): ExternalSpan

Example

(Creating an external span)

import { Effect, Option, Tracer } from "effect"

// Create an external span from another tracing system
const span = Tracer.externalSpan({
  spanId: "span-abc-123",
  traceId: "trace-xyz-789",
  sampled: true
})

// Use the external span as a parent
const program = Effect.succeed("Hello").pipe(
  Effect.withSpan("child-operation", { parent: span })
)

const spans: Array<Tracer.NativeSpan> = []
const tracer = Tracer.make({
  span(options) {
    const span = new Tracer.NativeSpan(options)
    spans.push(span)
    return span
  }
})
const value = await Effect.runPromise(Effect.provideService(program, Tracer.Tracer, tracer))

value // => "Hello"
spans.map((span) => Option.getOrUndefined(span.parent)?.spanId) // => ["span-abc-123"]

make

Added in v2.0.0 Source

Creates a Tracer value from a tracer implementation object.

When to use

Use to create a custom tracing backend value that Effect can use when creating spans.

Details

make returns the supplied implementation object unchanged. The object must satisfy the Tracer contract, including a span method that returns a Span.

See

Span for the span values returned by tracer implementations

Signature

declare function make(options: Tracer): Tracer

Models

AnySpan type

Added in v2.0.0 Source

A span value that can participate in tracing, either an Effect-managed Span or an ExternalSpan propagated from another tracing system.

Signature

type AnySpan = Span | ExternalSpan

Example

(Accepting any span)

import { Effect, Tracer } from "effect"

// Function that accepts any span type
const getSpanIds = (span: Tracer.AnySpan) => Effect.succeed([span.spanId, span.traceId])

// Works with both Span and ExternalSpan
const externalSpan = Tracer.externalSpan({
  spanId: "span-123",
  traceId: "trace-456"
})

await Effect.runPromise(getSpanIds(externalSpan)) // => ["span-123", "trace-456"]

EffectPrimitive interface

Added in v4.0.0 Source

A low-level Effect primitive that can be evaluated by a tracer-specific context for the current fiber.

Signature

interface EffectPrimitive<X> {
  "~effect/Effect/evaluate"(this: EffectPrimitive<X>, fiber: Fiber<any, any>): X;
}

ExternalSpan interface

Added in v2.0.0 Source

Represents a span created outside Effect's tracer, carrying trace and span identifiers, sampling state, and annotations so it can be used as a parent or link in Effect tracing.

Signature

interface ExternalSpan {
  readonly _tag: "ExternalSpan";
  readonly annotations: Context<never>;
  readonly sampled: boolean;
  readonly spanId: string;
  readonly traceId: string;
}

Example

(Creating an external span value)

import { Context } from "effect"
import type { Tracer } from "effect"

// Create an external span from another tracing system
const externalSpan: Tracer.ExternalSpan = {
  _tag: "ExternalSpan",
  spanId: "span-abc-123",
  traceId: "trace-xyz-789",
  sampled: true,
  annotations: Context.empty()
}

externalSpan.spanId // => "span-abc-123"

NativeSpan

Added in v4.0.0 Source

Default in-memory Span implementation used by the native tracer. It generates span and trace identifiers, stores attributes, events, and links, and records Started or Ended status.

Details

The constructor initializes the span with Started status, inherits the parent trace id or generates a new one, and always generates a new span id. Attributes, events, links, and status are then mutated through Span methods.

See

Span for the interface implemented by native spans

Signature

declare class NativeSpan implements Span {
  constructor(options: {
    readonly annotations: Context<never>;
    readonly kind: SpanKind;
    readonly links: Array<SpanLink>;
    readonly name: string;
    readonly parent: Option<AnySpan>;
    readonly sampled: boolean;
    readonly startTime: bigint;
  });
  readonly _tag: "Span";
  readonly annotations: Context<never>;
  attributes: Map<string, unknown>;
  events: Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]>;
  readonly kind: SpanKind;
  readonly links: Array<SpanLink>;
  readonly name: string;
  readonly parent: Option<AnySpan>;
  readonly sampled: boolean;
  readonly spanId: string;
  readonly startTime: bigint;
  status: SpanStatus;
  readonly traceId: string;
  addLinks(links: readonly Array<SpanLink>): void;
  attribute(key: string, value: unknown): void;
  end(endTime: bigint, exit: Exit<unknown, unknown>): void;
  event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void;
}

Span interface

Added in v2.0.0 Source

A span created by an Effect tracer. It carries trace identity, parent, annotations, attributes, links, sampling and kind information, lifecycle status, and methods to end the span or add attributes, events, and links.

Signature

interface Span {
  readonly _tag: "Span";
  readonly annotations: Context<never>;
  readonly attributes: ReadonlyMap<string, unknown>;
  readonly kind: SpanKind;
  readonly links: readonly Array<SpanLink>;
  readonly name: string;
  readonly parent: Option<AnySpan>;
  readonly sampled: boolean;
  readonly spanId: string;
  readonly status: SpanStatus;
  readonly traceId: string;
  addLinks(links: readonly Array<SpanLink>): void;
  attribute(key: string, value: unknown): void;
  end(endTime: bigint, exit: Exit<unknown, unknown>): void;
  event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void;
}

Example

(Working with spans)

import { Context, Exit, Option } from "effect"
import type { Tracer } from "effect"

const attributes = new Map<string, unknown>()
const links: Array<Tracer.SpanLink> = []
const events: Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]> = []
let status: Tracer.SpanStatus = {
  _tag: "Started",
  startTime: 1_000_000_000n
}

const span: Tracer.Span = {
  _tag: "Span",
  name: "load-user",
  spanId: "span-1",
  traceId: "trace-1",
  parent: Option.none(),
  annotations: Context.empty(),
  get status() {
    return status
  },
  attributes,
  links,
  sampled: true,
  kind: "internal",
  end(endTime, exit) {
    status = { _tag: "Ended", startTime: status.startTime, endTime, exit }
  },
  attribute(key, value) {
    attributes.set(key, value)
  },
  event(name, startTime, eventAttributes = {}) {
    events.push([name, startTime, eventAttributes])
  },
  addLinks(newLinks) {
    links.push(...newLinks)
  }
}

span.attribute("user.id", "123")
span.event("loaded", 1_250_000_000n, { "cache.hit": true })
span.end(1_500_000_000n, Exit.succeed("user"))

span.name // => "load-user"
span.attributes.get("user.id") // => "123"
span.status._tag // => "Ended"
events // => [["loaded", 1_250_000_000n, { "cache.hit": true }]]

SpanKind type

Added in v3.1.0 Source

OpenTelemetry-style role describing the kind of operation represented by a span: internal work, server handling, client calls, producing, or consuming.

Signature

type SpanKind = "internal" | "server" | "client" | "producer" | "consumer"

Example

(Configuring span kinds)

import { Effect, Tracer } from "effect"

// Different span kinds for different operations
const program = Effect.succeed("handled").pipe(
  Effect.withSpan("handle-request", {
    kind: "server" as Tracer.SpanKind
  })
)

const spans: Array<Tracer.NativeSpan> = []
const tracer = Tracer.make({
  span(options) {
    const span = new Tracer.NativeSpan(options)
    spans.push(span)
    return span
  }
})
const value = await Effect.runPromise(Effect.provideService(program, Tracer.Tracer, tracer)) // => "handled"

spans[0]?.kind // => "server"

SpanLink interface

Added in v2.0.0 Source

A relationship from one span to another span, with attributes describing the relationship.

Signature

interface SpanLink {
  readonly attributes: Readonly<Record<string, unknown>>;
  readonly span: AnySpan;
}

Example

(Linking spans)

import { Effect, Tracer } from "effect"

// Create a span link to connect spans
const externalSpan = Tracer.externalSpan({
  spanId: "external-span-123",
  traceId: "trace-456"
})

const link: Tracer.SpanLink = {
  span: externalSpan,
  attributes: { "link.type": "follows-from", "service": "external-api" }
}

const program = Effect.succeed("result").pipe(
  Effect.withSpan("linked-operation", { links: [link] })
)

const spans: Array<Tracer.NativeSpan> = []
const tracer = Tracer.make({
  span(options) {
    const span = new Tracer.NativeSpan(options)
    spans.push(span)
    return span
  }
})
const value = await Effect.runPromise(Effect.provideService(program, Tracer.Tracer, tracer)) // => "result"

spans[0]?.links[0]?.span.spanId // => "external-span-123"
spans[0]?.links[0]?.attributes["link.type"] // => "follows-from"

SpanStatus type

Added in v2.0.0 Source

Lifecycle state of a span, where Started records the start time and Ended records the start time, end time, and exit value with which the span completed.

Signature

type SpanStatus = {
  _tag: "Started";
  startTime: bigint;
} | {
  _tag: "Ended";
  endTime: bigint;
  exit: Exit.Exit<unknown, unknown>;
  startTime: bigint;
}

Example

(Creating span statuses)

import { Exit } from "effect"
import type { Tracer } from "effect"

const startTime = 1_000_000_000n
const endTime = 1_500_000_000n

const startedStatus: Tracer.SpanStatus = {
  _tag: "Started",
  startTime
}

const endedStatus: Tracer.SpanStatus = {
  _tag: "Ended",
  startTime,
  endTime,
  exit: Exit.succeed("result")
}

startedStatus._tag // => "Started"
endedStatus.endTime - endedStatus.startTime // => 500_000_000n

Options

SpanOptions interface

Added in v3.1.0 Source

Options accepted by span-creating APIs, combining span metadata such as attributes, links, parent/root selection, kind, sampling, and trace level with stack trace capture settings.

Signature

interface SpanOptions extends SpanOptionsNoTrace, TraceOptions {}

Example

(Configuring span options)

import { Effect, Tracer } from "effect"

// Create an effect with span options
const options: Tracer.SpanOptions = {
  attributes: { "user.id": "123", "operation": "data-processing" },
  kind: "internal",
  root: false,
  captureStackTrace: true
}

const program = Effect.succeed("Hello World").pipe(
  Effect.withSpan("my-operation", options)
)

const spans: Array<Tracer.NativeSpan> = []
const tracer = Tracer.make({
  span(options) {
    const span = new Tracer.NativeSpan(options)
    spans.push(span)
    return span
  }
})
const value = await Effect.runPromise(Effect.provideService(program, Tracer.Tracer, tracer)) // => "Hello World"

spans[0]?.attributes.get("user.id") // => "123"
spans[0]?.status._tag // => "Ended"

SpanOptionsNoTrace interface

Added in v4.0.0 Source

Span creation options that do not control stack trace capture, including attributes, links, parent or root selection, annotations, span kind, sampling, and the trace level used for filtering.

Signature

interface SpanOptionsNoTrace {
  readonly annotations?: Context<never>;
  readonly attributes?: Record<string, unknown>;
  readonly kind?: SpanKind;
  readonly level?: LogLevel;
  readonly links?: readonly Array<SpanLink>;
  readonly parent?: AnySpan;
  readonly root?: boolean;
  readonly sampled?: boolean;
}

TraceOptions interface

Added in v4.0.0 Source

Options that control stack trace capture for tracing wrappers. captureStackTrace can disable capture or provide a lazy stack string.

Signature

interface TraceOptions {
  readonly captureStackTrace?: boolean | LazyArg<string | undefined>;
}

Services

CurrentTraceLevel

Added in v4.0.0 Source

Context reference for controlling the current trace level for dynamic filtering.

When to use

Use to set the default trace level for spans in a scope when span options do not provide level.

Details

The default value is "Info". Span creation uses options.level ?? CurrentTraceLevel before applying MinimumTraceLevel.

See

MinimumTraceLevel for the threshold that decides whether spans at that level are sampled

Signature

declare const CurrentTraceLevel: Context.Reference<LogLevel>

DisablePropagation

Added in v3.12.0 Source

Context reference for disabling trace propagation.

When to use

Use to prevent spans in a scope from propagating tracing context.

Details

When enabled on fiber or span annotations, new spans are created as non-propagating no-op spans and disabled spans are skipped when deriving a parent span.

Signature

declare const DisablePropagation: Reference<boolean>

Example

(Disabling span propagation)

import { Effect, Tracer } from "effect"

// Disable span propagation for a specific effect
const program = Tracer.DisablePropagation.pipe(
  Effect.provideService(Tracer.DisablePropagation, true)
)

await Effect.runPromise(program) // => true

MinimumTraceLevel

Added in v4.0.0 Source

Context reference for setting the minimum trace level threshold. Spans and their descendants below this level will have their sampling decision forced to false, preventing them from being exported.

When to use

Use to set the trace-level threshold that controls whether spans are sampled by default.

Details

The default value is "All". Span creation compares the span level from options.level ?? CurrentTraceLevel against this threshold.

Gotchas

Explicit options.sampled bypasses threshold computation.

See

CurrentTraceLevel for the default span level used when options do not specify one

Signature

declare const MinimumTraceLevel: Reference<LogLevel>

ParentSpan

Added in v2.0.0 Source

Context service containing the Span or ExternalSpan to use as the parent of newly-created child spans.

Signature

declare class ParentSpan extends Shape<"effect/Tracer/ParentSpan", AnySpan, this> {
  constructor(_: never);
}

Example

(Accessing the parent span)

import { Effect, Tracer } from "effect"

// Access the parent span from the context
const program = Effect.gen(function*() {
  const parentSpan = yield* Effect.service(Tracer.ParentSpan)
  return parentSpan.spanId
})

const parent = Tracer.externalSpan({ spanId: "span-123", traceId: "trace-456" })
await Effect.runPromise(Effect.provideService(program, Tracer.ParentSpan, parent)) // => "span-123"

Tracer

Added in v2.0.0 Source

Context reference for the active tracer service. By default it uses the native tracer, which creates NativeSpan instances.

Signature

declare const Tracer: Reference<Tracer>

Example

(Accessing the current tracer)

import { Effect, Tracer } from "effect"

// Access the current tracer from the context
const program = Effect.gen(function*() {
  const tracer = yield* Effect.service(Tracer.Tracer)
  // Or use the built-in tracer effect
  const tracerFromAccessor = yield* Effect.tracer
  return tracer === tracerFromAccessor
})

await Effect.runPromise(program) // => true

Tracer interface

Added in v2.0.0 Source

A tracing backend used by Effect to create spans. Custom tracers implement span to allocate a span from the supplied name, parent, annotations, links, start time, kind, root flag, and sampling decision.

Signature

interface Tracer {
  readonly context?: <X>(primitive: EffectPrimitive<X>, fiber: Fiber<any, any>) => X;
  span(this: Tracer, options: {
    readonly annotations: Context<never>;
    readonly kind: SpanKind;
    readonly links: Array<SpanLink>;
    readonly name: string;
    readonly parent: Option<AnySpan>;
    readonly root: boolean;
    readonly sampled: boolean;
    readonly startTime: bigint;
  }): Span;
}