Sentry

Sentry is an error tracking and performance monitoring platform.

While logging is typically used to record routine application activity, Sentry is designed to capture exceptions, request failures, performance traces, and other diagnostic information that helps explain why something went wrong.

When an instrumented error occurs, Sentry records the stack trace, request context, runtime information, and other metadata needed to investigate the problem.

Oolvay includes first-class Sentry support across the browser, server runtime, and edge runtime. The integration is completely optional and follows the same Bring Your Own Keys philosophy as the rest of the observability stack.

When disabled, Sentry does not initialize in the browser, server runtime, or edge runtime, and no events are sent to Sentry.

What gets captured

Once initialized, Sentry can automatically capture three categories of telemetry:

Errors

Unhandled client-side exceptions
Unhandled server-side exceptions
Unhandled edge runtime exceptions
Request errors
Route transition errors

Performance

Distributed traces
Transaction timing data

Session Replay

Recorded browser sessions according to your configured sampling rates

The primary exception is a handled error. If an exception is caught inside a try/catch block, or if your application returns an error state instead of throwing an exception, Sentry will not receive it unless you report it explicitly.

How it works

Sentry is initialized separately for each runtime:

File	Runtime
`instrumentation-client.ts`	Browser
`sentry.server.config.ts`	Node.js
`sentry.edge.config.ts`	Edge

The instrumentation.ts file loads the correct configuration automatically based on the current runtime.

instrumentation.ts

How is this guide?

0 / 2,000 characters

Logging

Configure structured application logging, choose a transport provider, and understand how log levels, sampling, and redaction work together.

Analytics

Track product usage, page views, and user identification with PostHog, gated behind visitor consent.

On this page

Sentry What gets captured Errors Performance Session Replay How it works Enabling Sentry Runtime telemetry vs. build-time integration Runtime telemetry Build-time integration Configuration tracesSampleRateRoutes that often justify higher sampling Routes that often justify lower sampling replaysSessionSampleRateSituations that often justify higher sampling Situations that often justify lower sampling replaysOnErrorSampleRatesendDefaultPiiKey concepts Session Replay Source maps Performance monitoring Capturing handled exceptions Adding context to exceptions Fingerprints Tags Context Request IDs The monitoring tunnel Recommended settings Development Production Disabling Sentry Common issues Errors are not appearing in Sentry Session Replay is not working Browser console shows CSP violations Production stack traces are minified Captured exceptions are missing context

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config")
  }

  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config")
  }
}

Create an account at https://sentry.io if you do not already have one.

Find your organization slug.

In the Sentry dashboard:

Hover over Settings in the left sidebar.
Under Organization, click General Settings.
Locate the Organization Slug field.

The value shown in that field is your organization name. Add it to your environment variables:

.env.local

SENTRY_ORG=

Create or locate your Sentry project. In the Sentry dashboard:

Hover over Settings in the left sidebar.
Under Organization, click Projects.
If you already have a project, open it and copy the Slug.
Otherwise, click Create Project and choose Next.js as the platform.

The project slug becomes your project name. Add it to your environment variables:

.env.local

SENTRY_PROJECT=

Create an auth token. In the Sentry dashboard:

Hover over Settings in the left sidebar.
Under Developer Settings, click Organization Tokens.
Click Create New Token.
Copy the generated token.

Add it to your environment variables:

.env.local

SENTRY_AUTH_TOKEN=sentrys_***

Obtain your DSN. In the Sentry dashboard:

Hover over Settings in the left sidebar.
Under Organization, click Projects.
You must already have a project listed there. Click to open it.
In the now-updated left sidebar options, locate SDK Setup.
Click Client Keys (DSN) under that head.
If you already have a key, copy its DSN.
Otherwise, click the Generate New Key button and copy the DSN of the newly-generated key.

This DSN then goes into your environment variables:

.env.local

NEXT_PUBLIC_SENTRY_DSN=https://...

At this point you should have these values in your .env.local:

.env.local

NEXT_PUBLIC_SENTRY_DSN=https://...
SENTRY_ORG=
SENTRY_PROJECT=
SENTRY_AUTH_TOKEN=sentrys_***

Enable Sentry in config/site.ts.

config/site.ts

observability: {
  errorTracking: {
    enabled: true,
  },
},

Restart your development server.

bun dev

Sentry configuration is loaded during application startup. Changes to environment variables will not be picked up until the server restarts.

Sentry.withScope((scope) => {
  scope.setTag("action", "createSSOProvider")
  scope.setTag("type", "server-action")

  scope.setContext("sso", {
    provider: input.provider,
    domain: input.domain,
  })

  Sentry.captureException(error)
})