npm / @effect/opentelemetry
@effect/opentelemetry
What changed in @effect/opentelemetry 0.59 to 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-14.
11 breaking4 new APIs and options4 behavior and defaults21 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@effect/opentelemetry 427 changes
Breaking changes 9
OtlpTracer and OtelTracer leave successful spans, and spans failing without a reportable error, with status Unset instead of Ok. Queries and dashboards filtering on Ok should also match Unset.
NodeSdk is no longer re-exported from the package root; import it from this subpath to avoid requiring the optional Node SDK peer when importing the package.
WebSdk is no longer re-exported from the package root; import it from this subpath to avoid requiring the optional Web SDK peer when importing the package.
Node.js 22.19.0 is now the minimum required version for @effect/opentelemetry, up from 18.
Non-object failures no longer capture an internal stack frame; the stack is the message plus the span frame when available, affecting exported exception.stacktrace and Cause.pretty output.
Cumulative min and max are omitted from delta histogram points after the first export; first-export and cumulative extrema are unchanged.
HTTP span names, response error status, server addresses and ports align with OpenTelemetry conventions; header capture is opt-in and homogeneous primitive arrays export as array attributes.
Interrupt-only spans now use Unset and an effect.fiber.interrupted attribute instead of Ok, an Interrupted description, and the span.label and status.interrupted attributes.
The package uses the shared Effect v4 version and must be bumped to a matching v4 version alongside effect.
New APIs and options 1
OTLP exporters can be configured with standard OpenTelemetry environment variables.
Behavior and default changes 4
Reads OTEL_RESOURCE_ATTRIBUTES with Config.Record, allowing a structured config value as well as the environment variable format.
OpenTelemetry log records now receive the span context from the current Effect span, allowing backends to link logs to their traces.
Spans without an Effect parent can inherit active OpenTelemetry spans created outside Effect.
The integration's APIs are marked unstable, so they may receive new features and breaking changes in minor releases.
Fixes and other changes 13
OtelTracer no longer overwrites a status set directly on the span when it succeeds or fails without a reportable error.
Keeps log record bodies typed as OpenTelemetry AnyValue when @opentelemetry/api 1.10 widens AttributeValue to unknown.
Percent-decodes OTEL_RESOURCE_ATTRIBUTES keys and values, discarding the variable with a warning when its encoding is invalid.
Calls and fiber activity that arrive after a span has ended no longer modify it, trigger SDK warnings, export it twice, or send DevTools events.
Successfully bound metric readers are shut down if a later reader fails to bind, preventing exports from leaking after the failed scope closes.
Parsing now keeps attribute values that contain = and skips entries with an empty key.
Exporters now drop delta state for series that are no longer registered, preventing stale series state from being retained.
The active parent span object is preserved when starting Effect spans, preventing SDKs such as Sentry from dropping child spans.
Histogram exporters retain all finite boundaries and overflow observations in OTLP, and emit a single +Inf bucket in Prometheus.
Parent trace and span IDs are preserved when an active OpenTelemetry span context exposes them through getters, such as dd-trace.
OTLP and @effect/opentelemetry logs, traces, and resources are aligned with OpenTelemetry conventions.
Modules and directly importable exports now have explicit stability tags; stable follows strict semver, while unstable APIs may receive breaking changes in minor releases.
@effect/opentelemetryaligns logs and spans with the OpenTelemetry specification.
@effect/opentelemetry 0.642 changes
Fixes and other changes 2
Fixes duplicate service.name and service.version attributes when they are set in OTEL_RESOURCE_ATTRIBUTES.
Preserves OpenTelemetry trace propagation through unnamed Effect.fn and disabled spans by using the nearest propagated parent; Tracer.currentOtelSpan skips these spans.
@effect/opentelemetry 0.631 changes
Fixes and other changes 1
Logs are now added to the first propagated span when Effect.fn adds a fake span for a stack frame.
@effect/opentelemetry 0.617 changes
Breaking changes 2
Changed from an optional to a required peer dependency, fixing module resolution errors when importing from the main entry point.
Now requires an OtlpSerialization layer to be provided for the desired encoding format.
New APIs and options 3
Provides an explicit layer for JSON encoding.
Provides a layer for Protobuf encoding.
Introduces a service for choosing JSON or Protobuf encoding for OTLP exporters.
Fixes and other changes 2
Changed from an optional to a required peer dependency, fixing module resolution errors when importing from the main entry point.
Correctly handles the 2-argument overload with attributes instead of treating the attributes object as a TimeInput.
@effect/opentelemetry 0.593 changes
Fixes and other changes 3
Fixes currentOtelSpan to work with both the official OpenTelemetry SDK and the lightweight OTLP module, returning an OpenTelemetry Span interface wrapper when using OTLP.
The peer dependency range for @opentelemetry/sdk-logs was widened, allowing a broader range of versions.
Bigints are converted to strings for OpenTelemetry attributes.