Skip to content

OtelTracer

Bridges Effect tracing into OpenTelemetry by installing an Effect Tracer that creates OpenTelemetry spans, records attributes, events, links, errors, and status, and keeps OpenTelemetry context active while traced effects run. Use this module when an application already has an OpenTelemetry TracerProvider, or when the Node and Web SDK layers should expose Effect spans to OTLP, console, or other OpenTelemetry-compatible exporters.

The layer constructors wire Effect's tracer service to either the global OpenTelemetry tracer provider or an explicitly provided OtelTracer. This module does not create exporters or span processors by itself, so spans are exported only when the provider has been configured by the application or by the Node/Web SDK layers. Parentage is taken from Effect spans first and can also attach to the active OpenTelemetry context, while makeExternalSpan and withSpanContext are the entry points for continuing an incoming remote trace. Preserve traceFlags and traceState when building external spans; otherwise sampling defaults to sampled and trace state cannot be propagated.

14 exports Added in v4.0.0 Source

Accessors

currentOtelSpan

Added in v4.0.0 Source

Gets the current OpenTelemetry span.

Details

This accessor works with both the official OpenTelemetry API, such as Tracer.layer and NodeSdk.layer, and the lightweight OTLP module, such as OtlpTracer.layer. When using OTLP, the returned span is a wrapper that conforms to the OpenTelemetry Span interface.

Signature

declare const currentOtelSpan: Effect.Effect<Otel.Span, Cause.NoSuchElementError>;

Constructors

make

Added in v4.0.0 Source

Creates an Effect Tracer implementation backed by the configured OpenTelemetry tracer.

Signature

declare const make: Effect.Effect<Tracer.Tracer, never, OtelTracer>;

makeExternalSpan

Added in v4.0.0 Source

Creates an Effect external span from an OpenTelemetry span context, preserving trace flags and trace state when provided.

Signature

declare function makeExternalSpan(options: {
  readonly spanId: string;
  readonly traceFlags?: number;
  readonly traceId: string;
  readonly traceState?: any;
}): ExternalSpan;

Layers

layer

Added in v4.0.0 Source

Layer that creates an OpenTelemetry tracer from a provider and resource, then installs it as the Effect tracer.

When to use

Use when you already provide an OtelTracerProvider and a Resource, and want Effect spans backed by a tracer derived from them.

See

Signature

declare const layer: Layer.Layer<OtelTracer, never, OtelTracerProvider | Resource>;

layerGlobal

Added in v4.0.0 Source

Layer that installs an Effect tracer backed by the global OpenTelemetry tracer provider.

Signature

declare const layerGlobal: Layer.Layer<OtelTracer, never, Resource>;

layerGlobalProvider

Added in v4.0.0 Source

Layer that provides the current global OpenTelemetry tracer provider.

Signature

declare const layerGlobalProvider: Layer.Layer<OtelTracerProvider>;

layerGlobalTracer

Added in v4.0.0 Source

Layer that creates an OpenTelemetry tracer from the global tracer provider and the current resource.

Signature

declare const layerGlobalTracer: Layer.Layer<OtelTracer, never, Resource>;

layerTracer

Added in v4.0.0 Source

Layer that creates an OpenTelemetry tracer from the provided tracer provider and resource metadata.

Signature

declare const layerTracer: Layer.Layer<OtelTracer, never, OtelTracerProvider | Resource>;

layerWithoutOtelTracer

Added in v4.0.0 Source

Layer that installs the Effect tracer using an OtelTracer already provided in the environment.

Signature

declare const layerWithoutOtelTracer: Layer.Layer<never, never, OtelTracer>;

Propagation

withSpanContext

Added in v4.0.0 Source

Sets an effect's parent span from the given OpenTelemetry SpanContext.

When to use

Use when you need an effect to continue a trace from a parent span context produced by OpenTelemetry instrumentation outside Effect.

Signature

declare const withSpanContext: {
  (
    spanContext: SpanContext,
  ): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, ParentSpan>>;
  <A, E, R>(self: Effect<A, E, R>, spanContext: SpanContext): Effect<A, E, Exclude<R, ParentSpan>>;
};

Services

OtelTraceFlags

Added in v4.0.0 Source

Context service containing OpenTelemetry trace flags used when constructing external span contexts.

Signature

declare class OtelTraceFlags extends Shape<
  "@effect/opentelemetry/Tracer/OtelTraceFlags",
  TraceFlags,
  this
> {
  constructor(_: never);
}

OtelTracer

Added in v4.0.0 Source

Context service containing the OpenTelemetry Tracer used to create spans for Effect tracing.

Signature

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

OtelTracerProvider

Added in v4.0.0 Source

Context service containing the OpenTelemetry TracerProvider used to obtain tracers.

Signature

declare class OtelTracerProvider extends Shape<
  "@effect/opentelemetry/Tracer/OtelTracerProvider",
  TracerProvider,
  this
> {
  constructor(_: never);
}

OtelTraceState

Added in v4.0.0 Source

Context service containing OpenTelemetry trace state used when constructing external span contexts.

Signature

declare class OtelTraceState extends Shape<
  "@effect/opentelemetry/Tracer/OtelTraceState",
  TraceState,
  this
> {
  constructor(_: never);
}