-
-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Description
Description
Add a dedicated @sentry/effect SDK that provides first-class Sentry integration for Effect
applications, covering tracing, logging, and metrics (also error capture in a future releases)
Why a standalone SDK instead of an integration?
The original idea (#17126) was to add an effectIntegration to the Node SDK, potentially leveraging @effect/opentelemetry. After
investigation, we determined this approach doesn't work well:
@effect/opentelemetrysets up its own OpenTelemetry (OTel) tracer. this conflicts with Sentry's existing OTel setup and would result in
duplicate or conflicting instrumentation.- Effect already has built-in tracing, metrics, and logging. Effect's type-safe Tracer, Logger,
and Metric modules need dedicated bridging, not a generic OTel passthrough. - Effect uses Layers for composition - the idiomatic way to integrate with Effect is by providing Sentry-backed Layer
implementations, not through a traditional SDK integration pattern. - Dual platform support needed - Effect runs both server-side and in the browser. On the server, users may still want Sentry's
OTel-based instrumentation for third-party libraries (e.g.,pg), while in the browser there's no OTel. A standalone package can
cleanly handle both via conditional exports.
A standalone @sentry/effect package lets users simply add a Sentry layer to their Effect programs - the idiomatic Effect way.
Design decisions
Sentry.init() vs Sentry.effectLayer()
We pass Sentry config directly to effectLayer() so it manages the full lifecycle (init, flush, shutdown) via Effect finalizers. This
is the idiomatic Effect pattern - the Layer owns the resource lifecycle.
import * as Sentry from '@sentry/effect';
HttpLive.pipe(
Layer.provide(
Sentry.effectLayer({
dsn: '...',
tracesSampleRate: 1.0,
enableLogs: true,
enableMetrics: true,
})
),
Layer.launch,
NodeRuntime.runMain,
);Coexistence with OTel integrations
For the very beginning we focus on a Effect only experience. For the future we can think of how it would look like when users want to set up Effect with OTel. A very early prototype of the Effect SDK already showed that we might have duplicated spans, which we need to think of to prevent (or document).
E.g.: We do have a Postgres integration that instruments the pg library. If a user wants to use both the Effect SDK and the Postgres integration, they might end up with duplicated spans, as Effect is also adding spans (just slightly different ones). We need to think of a way to prevent this.
Logging and Metrics
When enableLogs: true is set in the effectLayer() options, Effect log calls (Effect.log, Effect.logWarning, Effect.logError,
etc.) are automatically forwarded to Sentry's structured logging with appropriate level mapping.
When enableMetrics: true is set, Effect metrics (Counter, Gauge, Histogram, Summary, Frequency) are periodically flushed to Sentry.
Both are opt-in to keep the default setup lightweight.
Effect v4 ErrorReporter
Effect v4 introduces an ErrorReporter primitive that allows hooking into Effect's error reporting pipeline. A Sentry ErrorReporter
implementation is not included in the first draft and will be added as a follow-up. Reference: Effect-TS/effect-smol#1409
Proposal
Sentry.effectLayer(options)
A single factory function that creates a composed Effect Layer providing all Sentry functionality. Accepts all standard Sentry SDK
options plus enableLogs and enableMetrics.
Three bridging layers
Another when we add
ErrorReporter
SentryEffectTracerLayer(always active) - Maps Effect spans to Sentry spans with parent-child relationships, status tracking,
attribute propagation, and automaticop/origindetection.SentryEffectLogger(opt-in viaenableLogs) - Forwards Effect log calls to Sentry's structured logging with level mapping.SentryEffectMetricsLayer(opt-in viaenableMetrics) - Periodically flushes Effect metrics to Sentry.
Dual-platform support
As with Astro, Effect can run in the frontend and in the backend (Node, Deno, Bun. Therefore it would be beneficial is both platforms are supported.