Sentry Next.js

https://docs.sentry.io/platforms/javascript/guides/nextjs
Admin
Learn how to set up and configure Sentry in your Next.js application using the installation wizard,...
Tokens:114,908
Snippets:1,069
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example Page Directory Structure

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs

The wizard creates /sentry-example-page with a button that triggers a test error, and an API route for testing. Use this to verify your setup.

```bash
app/
├── sentry-example-page/
│   └── page.tsx       # Test page with error button
└── api/
    └── sentry-example-api/
        └── route.ts   # Test API route
```

--------------------------------

### Start Next.js Dev Server

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs

Starts the Next.js development server to verify the Sentry setup. After running this command, visit localhost:3000/sentry-example-page and click "Throw Sample Error" to test all enabled features.

```bash
npm run dev
```

--------------------------------

### Install Sentry Next.js wizard

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay

Run the Sentry wizard to install @sentry/nextjs if it is not already installed. This command sets up the SDK and its configuration files.

```bash
npx @sentry/wizard@latest -i nextjs
```

--------------------------------

### startSession

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/apis

Starts a new session.

```APIDOC
## startSession

### Description
Starts a new session.

### Method
function

### Endpoint
startSession

### Parameters
None

### Request Example
```
const session = startSession();
```

### Response
#### Success Response
- **Session** - The newly created session object.

#### Response Example
```
{
  "session": {}
}
```
```

--------------------------------

### Start span with attributes and use tracesSampler

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/sampling

Shows how to start a span with attributes and how the tracesSampler function receives the span name and initial attributes. The example returns false for the span named "Search from navbar" to avoid sampling it.

```javascript
Sentry.startSpan({
  name: "Search from navbar",
  op: "search",
  attributes: {
    testGroup: "A3",
    treatmentName: "eager load",
  },
});

// Will result in `tracesSampler` receiving:
function tracesSampler(samplingContext) {
  /*
  samplingContext = { 
    name: "Search from navbar", 
    attributes: {
      testGroup: 'A3',
      treatmentName: 'eager load',
    },
  }
  */

  // Do not sample this specific span
  return name !== "Search from navbar";
}
```

--------------------------------

### Install @sentry/nextjs with npm

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/pages-router

Install the Sentry SDK for Next.js using npm. This is the primary command shown; yarn and pnpm variations are mentioned but not displayed.

```bash
npm install @sentry/nextjs --save
```

--------------------------------

### startNewTrace

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/apis

Start a new trace that is active in the provided callback.

```APIDOC
## startNewTrace

### Description
Start a new trace that is active in the provided callback.

### Signature
```typescript
function startNewTrace<T>(callback: () => T): T
```

### Parameters
- **callback** (() => T) - Required - The callback in which the new trace is active.

```

--------------------------------

### startNewTrace

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/apis

Starts a new trace that is active in the provided callback.

```APIDOC
## `startNewTrace<T>(callback: () => T): T`

### Description
Starts a new trace that is active in the provided callback.

### Method
Function call

### Endpoint
`Sentry.startNewTrace`

### Parameters
#### Function Parameters
- **callback** (() => T) - Required - The callback in which the new trace is active.

### Request Example
```javascript
// Example usage
Sentry.startNewTrace(() => {
  // ...
});
```

### Response
#### Success Response
Returns the value returned by the callback.
```

--------------------------------

### Trace Propagation Example 1: Microservices E-commerce

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/distributed-tracing

Example 1: Microservices E-commerce Platform. This configuration passes trace headers to your main API server and authentication server, enabling end-to-end tracing across these services.

```javascript
// instrumentation-client.js
Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  integrations: [Sentry.browserTracingIntegration()],
  tracePropagationTargets: [
    "https://api.myecommerce.com",
    "https://auth.myecommerce.com",
  ],
});
```

--------------------------------

### Span Starting Options

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/instrumentation

Options that can be used for all span starting functions in the Sentry Next.js SDK.

```APIDOC
## Span Starting Options

### Description
Options that can be used for all span starting functions in the Sentry Next.js SDK.

### Options

#### `name` (string) - Required
- The name of the span.

#### `op` (string) - Optional
- The operation of the span.

#### `startTime` (number) - Optional
- The start time of the span.

#### `attributes` (Record<string, Primitive>) - Optional
- Attributes to attach to the span.

#### `parentSpan` (Span) - Optional
- If set, make the span a child of the specified span. Otherwise, the span will be a child of the currently active span.

#### `onlyIfParent` (boolean) - Optional
- If true, ignore the span if there is no active parent span.

#### `forceTransaction` (boolean) - Optional
- If true, ensure this span shows up as transaction in the Sentry UI. Not available in stream mode. Use `parentSpan: null` instead to ensure this span shows up as service span.

### Notes
Only `name` is required, all other options are optional.
```

--------------------------------

### client.on('replayStart')

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions

Listens for the `replayStart` lifecycle event on the Sentry client. This event is emitted when a replay recording starts, providing the session ID and recording mode ('session' or 'buffer').

```APIDOC
## client.on('replayStart')

### Description
Listens for the `replayStart` lifecycle event on the Sentry client. This event is emitted when a replay recording starts, providing the session ID and recording mode ('session' or 'buffer').

### Method
`on`

### Endpoint
`client.on('replayStart', callback)`

### Parameters
- **eventName** (string) - Required - The event name, must be `'replayStart'`.
- **callback** (function) - Required - A function that receives an object with the following properties:
  - **sessionId** (string) - The ID of the replay session.
  - **recordingMode** (string) - The recording mode: `'session'` or `'buffer'`.

### Request Example
javascript
const client = Sentry.getClient();

client.on("replayStart", ({ sessionId, recordingMode }) => {
  // recordingMode: 'session' | 'buffer'
  console.log(`Replay ${sessionId} started in ${recordingMode} mode`);
});


### Response
No response value is returned. The callback is invoked when the event occurs.

### Notes
- Available since `v10.50.0`.
```

--------------------------------

### Sentry.startSpan

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/instrumentation/custom-instrumentation

Documentation for the Sentry.startSpan method, including options, usage, and examples for synchronous, asynchronous, and nested spans.

```APIDOC
## Sentry.startSpan

### Description
Starts a new active span that is automatically ended when the provided callback completes. The span is active within the callback and becomes the parent of any nested spans. If the callback throws or rejects, the span is marked as failed.

### Method
`startSpan`

### Signature
`Sentry.startSpan(options, callback)`

### Parameters
#### Options
- **name** (`string`) - Required - The name of the span.
- **op** (`string`) - Optional - The operation of the span.
- **startTime** (`number`) - Optional - The start time of the span.
- **attributes** (`Record<string, Primitive>`) - Optional - Attributes to attach to the span.
- **parentSpan** (`Span`) - Optional - If set, makes the span a child of the specified span. Otherwise, the span is a child of the currently active span.
- **onlyIfParent** (`boolean`) - Optional - If true, ignore the span if there is no active parent span.
- **forceTransaction** (`boolean`) - Optional - If true, ensures this span shows up as a transaction in the Sentry UI. Not available in stream mode. Use `parentSpan: null` instead to ensure this span shows up as a service span.

#### Callback
- **callback** (`() => T | Promise<T>`) - Required - The synchronous or asynchronous function to execute within the span. The span ends when the callback returns or the promise resolves/rejects.

### Return Value
Returns the result of the callback (`T` or `Promise<T>`).

### Example (Synchronous)
```javascript
const result = Sentry.startSpan({ name: "Important Function" }, () => {
  return expensiveFunction();
});
```

### Example (Asynchronous)
```javascript
const result = await Sentry.startSpan(
  { name: "Important Function" },
  async () => {
    const res = await doSomethingAsync();
    return updateRes(res);
  },
);
```

### Example (Nested Spans)
```javascript
const result = await Sentry.startSpan(
  {
    name: "Important Function",
  },
  async () => {
    const res = await Sentry.startSpan({ name: "Child Span" }, () => {
      return expensiveAsyncFunction();
    });

    return updateRes(res);
  },
);
```
```

--------------------------------

### Start a new trace with Sentry.startNewTrace

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/trace-propagation/custom-instrumentation

Starts a new trace that remains valid for the duration of the callback, disconnecting it from the current distributed trace. Once the callback ends, the SDK continues the previous trace if available. Available since v8.5.0.

```javascript
myButton.addEventListener("click", async () => {

  Sentry.startNewTrace(() => {
    Sentry.startSpan(
      { op: "ui.interaction.click", name: "fetch click" },
      async () => {
        await fetch("http://example.com");
      },
    );
  });

});
```

--------------------------------

### Trace Propagation Example 2: Mobile App with Backend Services

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/distributed-tracing

Example 2: Mobile App with Backend Services. This configuration tracks user actions across your main API, media server, and local API endpoints. It captures 100% of spans, which is useful for development and debugging; consider reducing in production or using traceSampler.

```javascript
// instrumentation-client.js
Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  integrations: [Sentry.browserTracingIntegration()],
  // Capture 100% of spans. This is useful for development and debugging. Consider reducing in production or using traceSampler
  tracesSampleRate: 1.0,
  tracePropagationTargets: [
    "https://api.myapp.com",
    "https://media.myapp.com",
    /^\/local-api\//,
  ],
});
```

--------------------------------

### withServerActionInstrumentation signature and usage example

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/enriching-events/identify-user

Instrument Next.js Server Actions by wrapping their content in withServerActionInstrumentation, along with a name to describe the action. Optionally pass form data and headers to record them, and configure recordResponse to record the Server Action responses. The example shows a Server Component with a server action that returns a value.

```typescript
function withServerActionInstrumentation(
serverActionName: string,
options?: Options,
callback: A
): Promise<ReturnType<A>>
```

```tsx
import * as Sentry from "@sentry/nextjs";
import { headers } from "next/headers";

export default function ServerComponent() {
  async function myServerAction(formData: FormData) {
    "use server";
    return await Sentry.withServerActionInstrumentation(
      "myServerAction", // The name you want to associate this Server Action with in Sentry
      {
        formData, // Optionally pass in the form data
        headers: await headers(), // Optionally pass in headers
        recordResponse: true, // Optionally record the server action response
      },
      async () => {
        // ... Your Server Action code

        return { name: "John Doe" };
      },
    );
  }

  return (
    <form action={myServerAction}>
      <input type="text" name="some-input-value" />
      <button type="submit">Run Action</button>
    </form>
  );
}
```

--------------------------------

### Lazy-load Replay integration

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay

Load Replay only when needed instead of at startup to reduce initial bundle size. This example shows how to add the integration later using dynamic import.

```typescript
// Don't add replayIntegration to init
Sentry.init({
  integrations: [],
});

// Later, when you want to start recording:
import("@sentry/nextjs").then((lazyLoadedSentry) => {
  Sentry.addIntegration(lazyLoadedSentry.replayIntegration());
});
```

--------------------------------

### init

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/apis

Initializes the SDK with the given options. This is the primary way to configure the SDK after initialization.

```APIDOC
## init

### Description
Initializes the SDK with the given options. See the Options page for the options you can pass to `init`.

### Method
function

### Signature
`function init(options: InitOptions): Client | undefined`

### Parameters
- **options** (InitOptions) - Required - Configuration options for the SDK.

### Returns
- **Client | undefined** - The initialized client, or undefined if initialization failed.

```

--------------------------------

### Generate tracing meta tags manually with Sentry.getTraceData()

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/trace-propagation/custom-instrumentation

Use Sentry.getTraceData() to get the meta tag values and generate the meta tags yourself for more control. The two blocks are identical renderings of the same example.

```javascript
function renderHtml() {

  const metaTagValues = Sentry.getTraceData();


  return `
    <html>
      <head>

        <meta name="sentry-trace" content="${metaTagValues["sentry-trace"]}">
        <meta name="baggage" content="${metaTagValues.baggage}">

      </head>
      <body>
        <!-- Your HTML content -->
      </body>
    </html>
  `;
}

```

```javascript
function renderHtml() {
  const metaTagValues = Sentry.getTraceData();

  return `
    <html>
      <head>
        <meta name="sentry-trace" content="${metaTagValues["sentry-trace"]}">
        <meta name="baggage" content="${metaTagValues.baggage}">
      </head>
      <body>
        <!-- Your HTML content -->
      </body>
    </html>
  `;
}

```

--------------------------------

### init(options: InitOptions): Client | undefined

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/apis

Initializes the Sentry SDK with the provided options.

```APIDOC
## init(options: InitOptions): Client | undefined

### Description
Initializes the SDK with the given options. See Options for the options you can pass to `init`.

### Method
function

### Signature
`init(options: InitOptions): Client | undefined`

### Parameters
- **options** (InitOptions) - Required - The initialization options for the SDK.
```

--------------------------------

### init(options: InitOptions): Client | undefined

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/enriching-events/identify-user

Initializes the Sentry SDK with the provided options. This is the primary entry point for setting up Sentry in your application.

```APIDOC
## init(options: InitOptions): Client | undefined

### Description
Initializes the Sentry SDK with the given options. See Options for the options you can pass to `init`.

### Method
Function

### Signature
`function init(options: InitOptions): Client | undefined`

### Parameters
- **options** (InitOptions) - Required - Configuration options for the SDK.

### Returns
- **Client | undefined** - The initialized client, or undefined if initialization failed.

```

--------------------------------

### startSpanManual

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/apis

Starts a new span that is active in the provided callback. The span will be a child of the currently active span, if there is one. The started span will not automatically end - you have to call `span.end()` when the span is done.

```APIDOC
## startSpanManual

### Description
Starts a new span that is active in the provided callback. The span will be a child of the currently active span, if there is one. The started span will not automatically end - you have to call `span.end()` when the span is done.

### Signature
```typescript
function startSpanManual<T>(options: StartSpanOptions, callback: (span: Span) => T): T
```

### Parameters
- **options** (StartSpanOptions) - Required - Options for the span.
  - **name** (string) - Required - Name of the span.
  - **attributes** (Record<string, string | number | boolean | null | undefined>) - Optional - Attributes to add to the span.
  - **startTime** (number) - Optional - The timestamp to use for the span start. If not provided, the current time will be used.
  - **op** (string) - Optional - The operation name for the span. This is used to group spans in the UI.
  - **forceTransaction** (boolean) - Optional - If true, the span will be forced to be sent as a transaction, even if it is not the root span. Not available in stream mode. Use `parentSpan: null` instead to make this span show up as service span.
  - **parentSpan** (Span | null) - Optional - The parent span for the new span. If not provided, the current span will be used.
  - **onlyIfParent** (boolean) - Optional - If true, the span will only be created if there is an active span.
- **callback** ((span: Span) => T) - Required - The callback that receives the span and returns a value.

### Example
```javascript
const status = await Sentry.startSpanManual(
  { name: "my-span" },
  async (span) => {
    const status = await doSomething();
    span.end();
    return status;
  },
);
```
```

--------------------------------

### startBrowserTracingNavigationSpan

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/apis

Documentation for the startBrowserTracingNavigationSpan client-side API.

```APIDOC
## function startBrowserTracingNavigationSpan

### Description
Starts a navigation span that ends automatically when the page is considered idle. If a pageload or navigation span is currently ongoing, it is ended first. In most cases, you do not need to call this, as browserTracingIntegration handles it automatically, but you can use it if you opt out of navigation spans. This function does nothing if browserTracingIntegration is not enabled.

### Signature
```
function startBrowserTracingNavigationSpan(client: Client, options: StartSpanOptions): Span | undefined
```

### Parameters
- **client** (Client) - Required - The Sentry client.
- **options** (StartSpanOptions) - Required - Options for starting the span.

### Returns
- **Span | undefined** - The started span, or undefined if the function could not start one.
```

--------------------------------

### Sentry.captureCheckIn()

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/crons

Tracks a job's progress by sending check-ins at the start and end of the job. Notifies Sentry if the job didn't start when expected (missed) or exceeded its maximum runtime (failed).

```APIDOC
## Sentry.captureCheckIn()

### Description
Tracks a job's progress by sending check-ins at the start and end of the job. Notifies Sentry if the job didn't start when expected (missed) or exceeded its maximum runtime (failed).

### Method
captureCheckIn

### Signature
Sentry.captureCheckIn(checkIn)

### Parameters
- **checkIn** (object) - Required - The check-in object containing the following fields:
  - **monitorSlug** (string) - Required - The unique slug identifying the monitor.
  - **status** (string) - Required - The status of the job: "in_progress", "ok", or "error".
  - **checkInId** (string) - Optional - The ID returned from the initial in_progress check-in. Required for subsequent check-ins (ok/error).

### Request Example
```javascript
// Start of job
const checkInId = Sentry.captureCheckIn({
  monitorSlug: "<monitor-slug>",
  status: "in_progress",
});

// Execute your scheduled task here...

// Successful completion
Sentry.captureCheckIn({
  checkInId,
  monitorSlug: "<monitor-slug>",
  status: "ok",
});
```

### Error Example
```javascript
// Job failure
Sentry.captureCheckIn({
  checkInId,
  monitorSlug: "<monitor-slug>",
  status: "error",
});
```
```

--------------------------------

### startSpanManual

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/apis

Starts a new span that is active in the provided callback. The span will be a child of the currently active span, if there is one. The started span will not automatically end; you must call `span.end()` when the span is done.

```APIDOC
## `startSpanManual<T>(options: StartSpanOptions, callback: (span: Span) => T): T`

### Description
Starts a new span that is active in the provided callback. The span will be a child of the currently active span, if there is one. The started span will not automatically end; you must call `span.end()` when the span is done.

### Method
Function call

### Endpoint
`Sentry.startSpanManual`

### Parameters
#### Function Parameters
- **options** (StartSpanOptions) - Required - Configuration for the new span.
  - **name** (string) - Required - The name of the span.
  - **attributes** (Record<string, string | number | boolean | null | undefined>) - Optional - Attributes to add to the span.
  - **startTime** (number) - Optional - The timestamp to use for the span start. If not provided, the current time will be used.
  - **op** (string) - Optional - The operation name for the span. Used to group spans in the UI.
  - **forceTransaction** (boolean) - Optional - If true, the span will be forced to be sent as a transaction, even if it is not the root span. Not available in stream mode. Use `parentSpan: null` instead to make this span show up as a service span.
  - **parentSpan** (Span | null) - Optional - The parent span for the new span. If not provided, the current span will be used.
  - **onlyIfParent** (boolean) - Optional - If true, the span will only be created if there is an active span.
- **callback** ((span: Span) => T) - Required - The callback that receives the span and returns a value of type T.

### Request Example
```javascript
const status = await Sentry.startSpanManual(
  { name: "my-span" },
  async (span) => {
    const status = await doSomething();
    span.end();
    return status;
  },
);
```

### Response
#### Success Response
Returns the value returned by the callback.

#### Response Example
```javascript
// The value returned by the callback, e.g., the status variable.
```
```

--------------------------------

### Initialize client SDK in instrumentation-client.ts

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/pages-router

Create this file in your application's root directory (or src folder) to initialize the client-side Sentry SDK. It includes performance tracing with a sample rate of 100% in development and 10% in production, session replay integration, and exports onRouterTransitionStart for router transition tracking. Use your DSN directly or a public environment variable like NEXT_PUBLIC_SENTRY_DSN.

```typescript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",

  // ___PRODUCT_OPTION_START___ performance

  // Capture 100% in dev, 10% in production
  // Adjust based on your traffic volume
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
  integrations: [
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
  ],
  // ___PRODUCT_OPTION_START___ session-replay

  // Capture Replay for 10% of all sessions,
  // plus for 100% of sessions with an error
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
});

export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
```

--------------------------------

### startSpanManual

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/enriching-events/identify-user

Starts a new span that is active in the provided callback. The span will be a child of the currently active span, if there is one. Any spans created inside of the callback will be children of this span. The started span will not automatically end - you have to call `span.end()` when the span is done.

```APIDOC
## `startSpanManual<T>(options: StartSpanOptions, callback: (span: Span) => T): T`

### Description
Starts a new span that is active in the provided callback. The span will be a child of the currently active span, if there is one. Any spans created inside of the callback will be children of this span. The started span will not automatically end - you have to call `span.end()` when the span is done.

### Parameters
- **options** (StartSpanOptions) - Required - Options for the new span.
  - **name** (string) - Required - The name of the span.
  - **attributes** (Record<string, string | number | boolean | null | undefined>) - Optional - Attributes to add to the span.
  - **startTime** (number) - Optional - The timestamp to use for the span start. If not provided, the current time will be used.
  - **op** (string) - Optional - The operation name for the span. This is used to group spans in the UI.
  - **forceTransaction** (boolean) - Optional - If true, the span will be forced to be sent as a transaction, even if it is not the root span. Not available in stream mode. Use `parentSpan: null` instead to make this span show up as service span.
  - **parentSpan** (Span | null) - Optional - The parent span for the new span. If not provided, the current span will be used.
  - **onlyIfParent** (boolean) - Optional - If true, the span will only be created if there is an active span.
- **callback** ((span: Span) => T) - Required - The callback in which the span is active. The span must be ended manually by calling `span.end()`.

### Returns
- **T** - The return value of the callback.

### Example
```javascript
const status = await Sentry.startSpanManual(
  { name: "my-span" },
  async (span) => {
    const status = await doSomething();
    span.end();
    return status;
  },
);
```
```

--------------------------------

### Server SDK initialization (sentry.server.config.ts)

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs

Initializes Sentry for the Node.js server environment. Includes performance tracing with a sample rate of 1.0 in development and 0.1 in production.

```typescript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",

  // ___PRODUCT_OPTION_START___ performance
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
});
```

--------------------------------

### startBrowserTracingPageLoadSpan

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/apis

Documentation for the startBrowserTracingPageLoadSpan client-side API.

```APIDOC
## function startBrowserTracingPageLoadSpan

### Description
Starts a pageload span that ends automatically when the page is considered idle. If a pageload or navigation span is currently ongoing, it is ended first. In most cases, you do not need to call this, as browserTracingIntegration handles it automatically, but you can use it if you opt out of pageload spans. This function does nothing if browserTracingIntegration is not enabled.

### Signature
```
function startBrowserTracingPageLoadSpan(client: Client, options: StartSpanOptions): Span | undefined
```

### Parameters
- **client** (Client) - Required - The Sentry client.
- **options** (StartSpanOptions) - Required - Options for starting the span.

### Returns
- **Span | undefined** - The started span, or undefined if the function could not start one.
```

--------------------------------

### getActiveSpan(): Span | undefined

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/apis

Get the currently active span.

```APIDOC
## getActiveSpan(): Span | undefined

### Description
Get the currently active span.

### Method
function

### Signature
`getActiveSpan(): Span | undefined`

### Parameters
None

### Returns
- **Span | undefined** - The currently active span, or `undefined` if none is active.
```

--------------------------------

### Sentry.onUnhandledRejectionIntegration

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/unhandledrejection

Documentation for the Sentry onUnhandledRejectionIntegration, including its options and usage example.

```APIDOC
## [JavaScript] Sentry.onUnhandledRejectionIntegration

### Description
Registers handlers to capture global unhandled promise rejections. This integration is enabled by default and only works inside server environments (Node.js, Bun, Deno).

### Method
N/A (SDK integration)

### Endpoint
N/A (SDK integration)

### Parameters
#### Options
- **mode** (`'none' | 'warn' | 'strict'`) - Optional - Defines what to do after capturing an unhandled rejection. Defaults to `warn`.
  - `strict`: Raise the unhandled rejection as an uncaught exception. If the exception is handled, unhandledRejection is emitted.
  - `warn`: Always trigger a warning, no matter if the unhandledRejection hook is set or not but do not print the deprecation warning.
  - `none`: Silence all warnings.

### Request Example
```JavaScript
Sentry.init({
  integrations: [Sentry.onUnhandledRejectionIntegration()],
});
```

### Response
N/A (SDK integration)
```

--------------------------------

### Set up Sentry LaunchDarkly integration

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/launchdarkly

Configure Sentry with the LaunchDarkly integration and track boolean flag evaluations. Requires installing and instrumenting the LaunchDarkly SDK first. Only works in a browser environment and is available in Sentry SDK versions 8.43.0 or higher.

```javascript
import * as Sentry from "@sentry/nextjs";
import * as LaunchDarkly from "launchdarkly-js-client-sdk";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  integrations: [Sentry.launchDarklyIntegration()],
});

const ldClient = LaunchDarkly.initialize(
  "my-client-ID",
  { kind: "user", key: "my-user-context-key" },
  { inspectors: [Sentry.buildLaunchDarklyFlagUsedHandler()] },
);

// Evaluate a flag with a default value. You may have to wait for your client to initialize first.
ldClient?.variation("test-flag", false);

Sentry.captureException(new Error("Something went wrong!"));
```

--------------------------------

### Sentry.rewriteFramesIntegration()

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/rewriteframes

Documentation for the Sentry.rewriteFramesIntegration() integration, including its options and usage examples.

```APIDOC
## Sentry.rewriteFramesIntegration()

### Description
Allows you to apply a transformation to each frame of the stack trace. In the streamlined scenario, it can be used to change the name of the file frame it originates from, or it can be fed with an iterated function to apply any arbitrary transformation.

### Method
Integration initialization

### Endpoint
Sentry.rewriteFramesIntegration(options?)

### Parameters
#### Options
- **root** (string) - Optional - Root path that will be stripped from the current frame's filename by the default iteratee if the filename is an absolute path.
- **prefix** (string) - Optional - A custom prefix that will be used by the default iteratee. Default: `app://`
- **iteratee** ((frame) => frame) - Optional - Function that takes the frame, applies a transformation, and returns it.

### Request Example
```javascript
import * as Sentry from "<sdk-package-name>";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  integrations: [Sentry.rewriteFramesIntegration()],
});
```

### Response
#### Success Response
Returns an integration instance to be passed to the `integrations` array in `Sentry.init()`.

### Usage Examples
| Usage | Path in Stack Trace | Description |
| --- | --- | --- |
| `rewriteFramesIntegration()` | `app:///file.js` | The default behavior is to replace the absolute path, except the filename, and prefix it with the default prefix (`app:///`). |
| `rewriteFramesIntegration({prefix: 'foo/'})` | `foo/file.js` | Prefix `foo/` is used instead of the default prefix `app:///`. |
| `rewriteFramesIntegration({root: '/www'})` | `app:///src/app/file.js` | `root` is defined as `/www`, so only that part is trimmed from the beginning of the path. |
```

--------------------------------

### Sentry.setTag

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/apis

Example usage of the Sentry SDK's setTag API.

```APIDOC
## [SDK] Sentry.setTag

### Description
Sets a tag on the current scope. Tags are key-value pairs that are attached to events and are used for filtering and grouping.

### Method
SDK function

### Endpoint
Sentry.setTag(key, value)

### Parameters
- **key** (string) - Required - The tag key.
- **value** (string) - Required - The tag value.

### Request Example
```javascript
import * as Sentry from "@sentry/browser";
Sentry.setTag("tag", "value");
```

### Response
No return value.
```

--------------------------------

### Initialize Sentry with Unleash integration and evaluate a flag

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/unleash

This snippet shows how to set up the Sentry Unleash integration in a Next.js app. It imports the UnleashClient from 'unleash-proxy-client', adds the integration to Sentry.init, creates and starts the Unleash client, evaluates a flag, and captures an exception. The integration only works in a browser environment and requires Sentry SDK version 8.51.0 or higher. Note that the 'unleashClientClass' option was renamed to 'featureFlagClientClass' in v9.

```javascript
import * as Sentry from "@sentry/nextjs";
import { UnleashClient } from "unleash-proxy-client";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  integrations: [
    Sentry.unleashIntegration({ featureFlagClientClass: UnleashClient }),
  ],
});

const unleash = new UnleashClient({
  url: "https://<your-unleash-instance>/api/frontend",
  clientKey: "<your-client-side-token>",
  appName: "my-webapp",
});

unleash.start();

// Evaluate a flag with a default value. You may have to wait for your client to synchronize first.
unleash.isEnabled("test-flag");

Sentry.captureException(new Error("Something went wrong!"));
```

--------------------------------

### Initialize server SDK in sentry.server.config.ts

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/pages-router

Create this file in your application's root directory (or src folder) to initialize the server-side Sentry SDK. It configures the DSN and sets tracesSampleRate to 100% in development and 10% in production. Use your DSN directly or a public environment variable like NEXT_PUBLIC_SENTRY_DSN.

```typescript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",

  // ___PRODUCT_OPTION_START___ performance

  // Capture 100% in dev, 10% in production
  // Adjust based on your traffic volume
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
});
```

--------------------------------

### Client SDK initialization (instrumentation-client.ts)

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs

Initializes Sentry for the browser environment. Includes performance tracing and session replay options with sample rates. The tracesSampleRate is set to 1.0 in development and 0.1 in production.

```typescript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",

  // ___PRODUCT_OPTION_START___ performance
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ session-replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
  integrations: [
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
  ],
});

export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
```

--------------------------------

### Add Replay integration to Sentry.init

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay

Add replayIntegration() to the client initialization and configure sample rates. Set replaysSessionSampleRate to 1.0 during development to capture all sessions.

```typescript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",

  // This sets the sample rate to be 10%. You may want this to be 100% while
  // in development and sample at a lower rate in production
  replaysSessionSampleRate: 0.1,

  // If the entire session is not sampled, use the below sample rate to sample
  // sessions when an error occurs.
  replaysOnErrorSampleRate: 1.0,

  integrations: [Sentry.replayIntegration()],
});
```

--------------------------------

### getFeedback

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/apis

Get the feedback integration, if it has been added. This can be used to access the feedback integration in a type-safe way.

```APIDOC
## getFeedback

### Description
Gets the feedback integration if it has been added. This can be used to access the feedback integration in a type-safe way.

### Function Signature
`function getFeedback(): ReturnType<feedbackIntegration> | undefined`

### Return Value
Returns the feedback integration if it has been added, otherwise `undefined`.
```

--------------------------------

### startBrowserTracingPageLoadSpan

Source: https://docs.sentry.io/platforms/javascript/guides/nextjs/apis

Starts a pageload span that will be automatically ended when the page is considered idle. If a pageload/navigation span is currently ongoing, it will automatically be ended first. This is only available on the client. In most cases, you do not need to call this, as the `browserTracingIntegration` will automatically do that for you. However, if you opt-out of pageload spans, you can use this method to manually start such a span. Please note that this function will do nothing if `browserTracingIntegration` has not been enabled.

```APIDOC
## `startBrowserTracingPageLoadSpan(client: Client, options: StartSpanOptions): Span | undefined`

### Description
Starts a pageload span that will be automatically ended when the page is considered idle. If a pageload/navigation span is currently ongoing, it will automatically be ended first. This is only available on the client. In most cases, you do not need to call this, as the `browserTracingIntegration` will automatically do that for you. However, if you opt-out of pageload spans, you can use this method to manually start such a span. Please note that this function will do nothing if `browserTracingIntegration` has not been enabled.

### Method
Function call

### Endpoint
`Sentry.startBrowserTracingPageLoadSpan`

### Parameters
#### Function Parameters
- **client** (Client) - Required - The Sentry client.
- **options** (StartSpanOptions) - Required - Configuration for the new span.
  - **name** (string) - Required - The name of the span.
  - **attributes** (Record<string, string | number | boolean | null | undefined>) - Optional - Attributes to add to the span.
  - **startTime** (number) - Optional - The timestamp to use for the span start. If not provided, the current time will be used.
  - **op** (string) - Optional - The operation name for the span. Used to group spans in the UI.
  - **forceTransaction** (boolean) - Optional - If true, the span will be forced to be sent as a transaction, even if it is not the root span. Not available in stream mode. Use `parentSpan: null` instead to make this span show up as a service span.
  - **parentSpan** (Span | null) - Optional - The parent span for the new span. If not provided, the current span will be used.
  - **onlyIfParent** (boolean) - Optional - If true, the span will only be created if there is an active span.

### Request Example
```javascript
// Example usage
const span = Sentry.startBrowserTracingPageLoadSpan(client, { name: "pageload" });
```

### Response
#### Success Response
Returns the started span, or `undefined` if the span could not be started.
```
Tokens:
Raw