Skip to content

docs: Add effect v4 support #17472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JPeer264 merged 5 commits into from
May 4, 2026
Merged

docs: Add effect v4 support #17472

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c85299d
docs: Add effect v4 support
JPeer264 Apr 24, 2026
3b965af
Update index.mdx
JPeer264 Apr 24, 2026
57dfd62
Update index.mdx
JPeer264 Apr 24, 2026
f3e8267
Update index.mdx
JPeer264 Apr 24, 2026
0941979
fixup! docs: Add effect v4 support
JPeer264 May 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 121 additions & 20 deletions docs/platforms/javascript/guides/effect/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ Please reach out on [GitHub](https://github.com/getsentry/sentry-javascript/issu

</Alert>

This guide will show you how to integrate Sentry into your [Effect](https://effect.website/) project using the `@sentry/effect` SDK.

`@sentry/effect` supports **Effect v3** and **Effect v4**. The integration automatically detects which version you have installed, but the `Tracer` and `Logger` layer APIs differ between major versions. Make sure to follow the correct code snippets for your version below.

<PlatformContent includePath="getting-started-prerequisites" />

<StepConnector selector="h2" showNumbers={true}>
Expand Down Expand Up @@ -54,21 +58,26 @@ pnpm add @sentry/effect

## Configure

### Initialize Sentry on the Server-Side
The SDK provides an `effectLayer` that initializes Sentry. You can compose it with additional Effect layers to enable tracing, logging, and metrics. The `effectLayer`, `SentryEffectTracer`, `SentryEffectLogger`, and `SentryEffectMetricsLayer` exports are the same for Effect v3 and v4. The only difference between versions is how you compose layers for tracing and logging, which is covered in the snippets below.

### Effect v3

<SplitLayout>
<SplitSection>
<SplitSectionText>

Import and initialize the Sentry SDK in your application's entry point (for example, `main.ts`) using the SDK's `effectLayer`.
<AvailableSince version="10.44.0" />

Depending on the features you've selected, merge the `effectLayer` with the corresponding feature layers.
- Node: Provide `SentryLive` before launching your HTTP layer (for example, with `NodeRuntime`).
- Browser: Provide `SentryLive` to your app layer.

In both cases, use `Layer.setTracer` to configure tracing and `Logger.replace` to configure logging.

</SplitSectionText>
<SplitSectionCode>

```typescript {filename:main.ts}
import * as Sentry from "@sentry/effect/server";
```typescript {tabTitle: Server} {filename: main.ts}
import * as Sentry from "@sentry/effect";
import { NodeRuntime } from "@effect/platform-node";
// ___PRODUCT_OPTION_START___ logs
import * as Logger from "effect/Logger";
Expand Down Expand Up @@ -116,29 +125,123 @@ const MainLive = HttpLive.pipe(Layer.provide(SentryLive));
MainLive.pipe(Layer.launch, NodeRuntime.runMain);
```

```typescript {tabTitle: Client} {filename: main.ts}
import * as Sentry from "@sentry/effect";
// ___PRODUCT_OPTION_START___ logs
import { Logger } from "effect";
// ___PRODUCT_OPTION_END___ logs
import { Layer } from "effect";

const SentryLive = Layer.mergeAll(
Sentry.effectLayer({
dsn: "___PUBLIC_DSN___",
// ___PRODUCT_OPTION_START___ performance

// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for tracing.
// We recommend adjusting this value in production.
// Learn more at
// https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
tracesSampleRate: 1.0,
integrations: [Sentry.browserTracingIntegration()],
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs

// Enable logs to be sent to Sentry
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
}),
// ___PRODUCT_OPTION_START___ performance

// Enable Effect tracing for the browser
Layer.setTracer(Sentry.SentryEffectTracer),
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs

// Forward Effect logs to Sentry
Logger.replace(Logger.defaultLogger, Sentry.SentryEffectLogger)
// ___PRODUCT_OPTION_END___ logs
);

const MainLive = YourAppLayer.pipe(Layer.provide(SentryLive));
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

### Initialize Sentry on the Client-Side
### Effect v4

<SplitLayout>
<SplitSection>
<SplitSectionText>

Import and initialize the Sentry SDK in your application's entry point (for example, `index.ts`) using the SDK's `effectLayer`.
<AvailableSince version="10.50.0" />

Depending on the features you've selected, merge the `effectLayer` with the corresponding feature layers.
Effect v4 changes how you install the default `Tracer` and `Logger` services. Use `Layer.succeed(Tracer.Tracer, …)` plus `Logger.layer([…])`.

</SplitSectionText>
<SplitSectionCode>

```typescript {filename:index.ts}
import * as Sentry from "@sentry/effect/client";
```typescript {tabTitle: Server} {filename: main.ts}
import * as Sentry from "@sentry/effect";
import { NodeRuntime } from "@effect/platform-node";
// ___PRODUCT_OPTION_START___ logs
import { Logger } from "effect";
import * as Logger from "effect/Logger";
// ___PRODUCT_OPTION_END___ logs
import { Layer } from "effect";
import * as Layer from "effect/Layer";
// ___PRODUCT_OPTION_START___ performance
import * as Tracer from "effect/Tracer";
// ___PRODUCT_OPTION_END___ performance
import { HttpLive } from "./Http.js";

const SentryLive = Layer.mergeAll(
Sentry.effectLayer({
dsn: "___PUBLIC_DSN___",
// ___PRODUCT_OPTION_START___ performance

// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for tracing.
// We recommend adjusting this value in production.
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs

// Enable logs to be sent to Sentry
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
}),
// ___PRODUCT_OPTION_START___ performance

// Enable Effect tracing
Layer.succeed(Tracer.Tracer, Sentry.SentryEffectTracer),
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs

// Forward Effect logs to Sentry
Logger.layer([Sentry.SentryEffectLogger]),
// ___PRODUCT_OPTION_END___ logs
// ___PRODUCT_OPTION_START___ metrics

// Forward Effect metrics to Sentry
Sentry.SentryEffectMetricsLayer,
// ___PRODUCT_OPTION_END___ metrics
);

const MainLive = HttpLive.pipe(Layer.provide(SentryLive));

MainLive.pipe(Layer.launch, NodeRuntime.runMain);
```

```typescript {tabTitle: Client} {filename: main.ts}
import * as Sentry from "@sentry/effect";
// ___PRODUCT_OPTION_START___ logs
import * as Logger from "effect/Logger";
// ___PRODUCT_OPTION_END___ logs
import * as Layer from "effect/Layer";
// ___PRODUCT_OPTION_START___ performance
import * as Tracer from "effect/Tracer";
// ___PRODUCT_OPTION_END___ performance

const SentryLive = Layer.mergeAll(
Sentry.effectLayer({
Expand All @@ -148,8 +251,6 @@ const SentryLive = Layer.mergeAll(
// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for tracing.
// We recommend adjusting this value in production.
// Learn more at
// https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
tracesSampleRate: 1.0,
integrations: [Sentry.browserTracingIntegration()],
// ___PRODUCT_OPTION_END___ performance
Expand All @@ -161,13 +262,13 @@ const SentryLive = Layer.mergeAll(
}),
// ___PRODUCT_OPTION_START___ performance

// Enable Effect tracing for the browser
Layer.setTracer(Sentry.SentryEffectTracer),
// Enable Effect tracing
Layer.succeed(Tracer.Tracer, Sentry.SentryEffectTracer),
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs

// Forward Effect logs to Sentry
Logger.replace(Logger.defaultLogger, Sentry.SentryEffectLogger)
Logger.layer([Sentry.SentryEffectLogger]),
// ___PRODUCT_OPTION_END___ logs
);

Expand Down Expand Up @@ -199,7 +300,7 @@ To verify that Sentry captures errors and creates issues in your Sentry project,

```typescript
import { Effect } from "effect";
import * as Sentry from "@sentry/effect/server";
import * as Sentry from "@sentry/effect";

const program = Effect.gen(function* () {
yield* Effect.fail(new Error("Sentry Test Error"));
Comment thread
sentry[bot] marked this conversation as resolved.
Expand All @@ -226,7 +327,7 @@ To test your tracing configuration, update the previous code snippet to create a

```typescript
import { Effect } from "effect";
import * as Sentry from "@sentry/effect/server";
import * as Sentry from "@sentry/effect";

const program = Effect.gen(function* () {
yield* Effect.gen(function* () {
Expand Down Expand Up @@ -262,7 +363,7 @@ To verify that Sentry catches your logs, add some log statements to your applica

```typescript
import { Effect } from "effect";
import * as Sentry from "@sentry/effect/server";
import * as Sentry from "@sentry/effect";

const program = Effect.gen(function* () {
yield* Effect.log("User example action completed");
Expand Down
Loading