Next.js

Serverseitiges Monitoring von Next.js-Anwendungen

Kostenlos in jedem Plan, auch im kostenlosen

Kostenlos starten Dokumentation

Woher nehmen

Auf npm ansehen

npm

Voraussetzungen Next.js 13.4+ mit App Router, Node.js-Runtime

Paketname @dockcodes/dock-ray-next

Preise Kostenlos

Wozu es dient

Die offizielle DockRay-Integration für Next.js ermöglicht das Monitoring von Fehlern und der Performance von Next.js-Anwendungen. Sie meldet automatisch serverseitige Fehler, Fehler in der Edge Runtime und Middleware und ermöglicht optional die Erfassung von JavaScript-Fehlern aus dem Browser.

Die Integration unterstützt Next.js 14 und 15 sowie Anwendungen mit App Router und Pages Router.

Monitoring von Next.js-Fehlern

DockRay integriert sich in das Fehlerreporting von Next.js und ermöglicht die Erfassung von Problemen, die in verschiedenen Bereichen der Anwendung auftreten.

Unter anderem können Fehler in folgenden Bereichen überwacht werden:

Server Components,
Route Handlers,
Server Actions,
Streaming Rendering,
Pages Router und API Routes,
Middleware und Edge Runtime.

Ereignisse können Informationen über den Router, das Routenmuster, den Routentyp und die Rendering-Quelle enthalten. Dadurch lässt sich leichter feststellen, wo ein Problem aufgetreten ist.

Performance-Monitoring

DockRay ermöglicht das Monitoring der Verarbeitungszeit von Anfragen und Transaktionen in Next.js-Anwendungen. Die Häufigkeit der Datenerfassung kann über eine Sampling-Rate gesteuert werden.

Monitoring von JavaScript-Fehlern

Optional kann die Meldung von JavaScript-Fehlern aktiviert werden, die im Browser des Benutzers auftreten. Die Ereignisse werden zunächst an einen eigenen Endpoint der Next.js-Anwendung gesendet und anschließend an DockRay weitergeleitet.

Dadurch verbleibt der private Schlüssel des Projekts ausschließlich auf dem Server und wird nicht in den öffentlichen Anwendungscode eingebunden.

Edge Runtime und Middleware

Die Integration verfügt über einen separaten Einstiegspunkt für die Edge Runtime. Dadurch können Fehler gemeldet werden, die in Middleware und anderen Teilen der Anwendung auftreten, die auf der Edge Runtime ausgeführt werden.

Datenschutz und Sicherheit

Sensible Header wie Authorization, Cookie, Set-Cookie und X-Api-Key werden aus den gemeldeten Daten entfernt.

Die Übermittlung der IP-Adresse und des User-Agents ist optional und muss separat in der Konfiguration aktiviert werden.

Integration mit Vercel

Bei Anwendungen, die auf Vercel bereitgestellt werden, kann DockRay automatisch Informationen über die Deployment-Umgebung und die Anwendungsversion verwenden. Dadurch lassen sich Produktiv- und Preview-Deployments leichter voneinander unterscheiden.

Installation

Installation des Pakets

Installieren Sie DockRay mit npm:

bash

npm install @dockcodes/dock-ray-next

Konfiguration

Fügen Sie die DockRay-Projektdaten zu den Umgebungsvariablen hinzu:

RAY_TOKEN=project-token
RAY_PRIVATE_KEY=project-private-key
RAY_TRACES_SAMPLE_RATE=0.2

Den Projekt-Token und den privaten Schlüssel finden Sie im DockRay-Dashboard.

RAY_PRIVATE_KEY darf ausschließlich serverseitig verfügbar sein. Verwenden Sie dafür nicht das Präfix NEXT_PUBLIC_, da der Schlüssel sonst in den öffentlichen Anwendungscode eingebunden würde.

Ohne konfigurierten Projekt-Token und privaten Schlüssel bleibt die Integration inaktiv und sendet keine Daten.

Fehlerreporting aktivieren

Initialisieren Sie DockRay in der Datei instrumentation.ts im Stammverzeichnis des Projekts und konfigurieren Sie die Fehlerbehandlung:

import {
    initRay,
    rayRequestError
} from '@dockcodes/dock-ray-next';

export function register() {
    initRay();
}

export const>




    Nach der Konfiguration kann DockRay von Next.js erfasste Fehler melden, unter anderem aus Server Components, Route Handlers, Server Actions und Streaming Rendering.

So wird es verwendet

Ausnahmen meldet die Integration von selbst. Das hier ist für Meldungen, die Sie bewusst senden.

import { withRay } from '@dockcodes/dock-ray-next';

export default withRay(async function handler(req, res) {
    const order = await processOrder(req.body);

    res.status(200).json({
        success: true,
        order
    });
});