@sigil-dev/plugin-sentry

Integrates Sentry with Grimoire. Captures errors and fatal log entries, optionally captures warnings, and reports worker crashes with worker context attached.

Installation

bun add @sigil-dev/plugin-sentry @sentry/bun

Usage

import { defineConfig } from "@sigil-dev/grimoire";
import { sentryPlugin } from "@sigil-dev/plugin-sentry";

export default defineConfig({
  plugins: [
    sentryPlugin({
      dsn: process.env.SENTRY_DSN!,
    }),
  ],
});

Options

interface SentryPluginOptions {
  /** Sentry DSN. Required. */
  dsn: string;
  /** Also capture warn-level log entries as Sentry messages. Default: false. */
  captureWarns?: boolean;
  /** Return false to suppress a log entry from being sent to Sentry. */
  beforeSend?: (entry: LogEntry) => boolean;
  /** Additional options passed directly to Sentry.init(). */
  sentryOptions?: Record<string, unknown>;
}

What gets captured

| Event | Sentry level | Notes | |---|---|---| | log.error(...) | error | Captures as exception with scope + worker tags. | | log.fatal(...) | fatal | Same as error. | | log.warn(...) | warning | Only if captureWarns: true. | | Worker crash | error | Captured as message with worker name and mode tags. |

All captured events include request context (url, method) set via Sentry.setContext on each request.

Filtering events

Use beforeSend to suppress specific entries:

sentryPlugin({
  dsn: process.env.SENTRY_DSN!,
  beforeSend(entry) {
    // don't send expected 404s to Sentry
    if (entry.message.includes("Not Found")) return false;
    return true;
  },
})

Passing additional Sentry options

Any option accepted by Sentry.init() can be passed via sentryOptions:

sentryPlugin({
  dsn: process.env.SENTRY_DSN!,
  sentryOptions: {
    environment: process.env.NODE_ENV,
    release: process.env.GIT_SHA,
    tracesSampleRate: 0.2,
  },
})