Skip to content

index.mdx

Latest commit

 

History

History
285 lines (215 loc) · 9.18 KB

index.mdx

File metadata and controls

285 lines (215 loc) · 9.18 KB
title Effect
sdk sentry.javascript.effect
description Learn how to set up Sentry in your Effect application with first-class integration for tracing, logging, and metrics.

This SDK is currently in ALPHA. Alpha features are still in progress, may have bugs, and might include breaking changes. Please reach out on GitHub if you have any feedback or concerns.

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.

Step 1: Install

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

<OnboardingOptionButtons options={["error-monitoring", "performance", "logs", "metrics"]} />

Install the Sentry SDK

npm install @sentry/effect --save
yarn add @sentry/effect
pnpm add @sentry/effect

Step 2: Configure

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

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

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.
    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);
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.
    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
  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));

Effect v4

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

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);
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({
    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,
    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
  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
);

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

Features

The SDK provides composable layers for Effect integration:

- **Tracing** via `Sentry.SentryEffectTracer`: Effect spans are automatically traced as Sentry spans with distributed tracing support - **Logging** via `Sentry.SentryEffectLogger`: Effect logs are forwarded to Sentry (requires `enableLogs: true`) - **Metrics** via `Sentry.SentryEffectMetricsLayer`: Effect metrics (counters, gauges, histograms) are sent to Sentry

Step 3: Verify

Add a test error to verify your setup:

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

Head over to your project on Sentry.io to view the collected data.

Next Steps