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.
Accessors
currentOtelSpan
Signature
declare const currentOtelSpan: Effect.Effect<Otel.Span, Cause.NoSuchElementError>;Constructors
Creates an Effect Tracer implementation backed by the configured OpenTelemetry tracer.
Signature
declare const make: Effect.Effect<Tracer.Tracer, never, OtelTracer>;makeExternalSpan
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 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
layerTracerfor creating only the OpenTelemetry tracer servicelayerGlobalfor installing the Effect tracer from the global providerlayerWithoutOtelTracerfor installing an already-providedOtelTracer
Signature
declare const layer: Layer.Layer<OtelTracer, never, OtelTracerProvider | Resource>;layerGlobal
Layer that installs an Effect tracer backed by the global OpenTelemetry tracer provider.
Signature
declare const layerGlobal: Layer.Layer<OtelTracer, never, Resource>;layerGlobalProvider
Layer that provides the current global OpenTelemetry tracer provider.
Signature
declare const layerGlobalProvider: Layer.Layer<OtelTracerProvider>;layerGlobalTracer
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
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
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
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
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
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
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
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);
}
Gets the current OpenTelemetry span.
Details
This accessor works with both the official OpenTelemetry API, such as
Tracer.layerandNodeSdk.layer, and the lightweight OTLP module, such asOtlpTracer.layer. When using OTLP, the returned span is a wrapper that conforms to the OpenTelemetrySpaninterface.