Effect

Learn how to set up and configure Sentry in your Effect application, capture your first errors, and view them in Sentry.

This guide will show you how to integrate Sentry into your Effect 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.

You need:

Choose the features you want to configure, and this guide will show you how:

Want to learn more about these features?
  • Issues (always enabled): Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.
  • Tracing: Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
  • Logs: Centralize and analyze your application logs to correlate them with errors and performance issues. Search, filter, and visualize log data to understand what's happening in your applications.
  • Application Metrics: Track and analyze custom application metrics, such as response times and database query durations, to understand trends and patterns in your application's performance and behavior over time.

Run the command for your preferred package manager to add the Sentry SDK to your application.

Copied
npm install @sentry/effect --save

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.

Available since: v10.44.0

  • 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.

main.ts
Copied
import * as Sentry from "@sentry/effect";
import { NodeRuntime } from "@effect/platform-node";
// ___PRODUCT_OPTION_START___ logs
import * as Logger from "effect/Logger";
// ___PRODUCT_OPTION_END___ logs
import * as Layer from "effect/Layer";
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.
    // Learn more at
    // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
    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.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
  // ___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);

Available since: v10.50.0

Effect v4 changes how you install the default Tracer and Logger services. Use Layer.succeed(Tracer.Tracer, …) plus Logger.layer([…]).

main.ts
Copied
import * as Sentry from "@sentry/effect";
import { NodeRuntime } from "@effect/platform-node";
// ___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
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);

The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your source maps to Sentry. The easiest way to do this is by using the Sentry Wizard.

Alternatively, take a look at our Uploading Source Maps documentation.

Copied
npx @sentry/wizard@latest -i sourcemaps

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

To verify that Sentry captures errors and creates issues in your Sentry project, add a test error:

Copied
import { Effect } from "effect";
import * as Sentry from "@sentry/effect";

const program = Effect.gen(function* () {
  yield* Effect.fail(new Error("Sentry Test Error"));
});

// Run with your layer that includes Sentry.effectLayer

To test your tracing configuration, update the previous code snippet to create a custom span:

Copied
import { Effect } from "effect";
import * as Sentry from "@sentry/effect";

const program = Effect.gen(function* () {
  yield* Effect.gen(function* () {
    // Simulate some work
    yield* Effect.sleep("100 millis");
    yield* Effect.fail(new Error("Sentry Test Error"));
  }).pipe(
    Effect.withSpan("My First Test Transaction", {
      attributes: { op: "test" },
    }),
  );
});

To verify that Sentry catches your logs, add some log statements to your application:

Copied
import { Effect } from "effect";
import * as Sentry from "@sentry/effect";

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

  yield* Effect.logWarning("Slow operation detected").pipe(
    Effect.annotateLogs({
      operation: "data_fetch",
      duration: "3500ms",
    }),
  );

  yield* Effect.logError("Validation failed").pipe(
    Effect.annotateLogs({
      field: "email",
      reason: "Invalid email",
    }),
  );
});

Now, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).

Need help locating the captured errors in your Sentry project?
  • Open the Issues page and select an error from the issues list to view the full details and context of this error. For more details, see this interactive walkthrough.
  • Open the Traces page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click here.
  • Open the Logs page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click here.
  • Open the Application Metrics page to view and analyze your metrics. For more details, see this interactive walkthrough.

Are you having problems setting up the SDK?
Previous
Welcome to Sentry
Next
Installation Methods
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").