Zum Hauptinhalt springen
Die AppSignal-Integration für Next.js. Um sowohl Backend-Traces als auch Frontend-Fehler zu melden, wird empfohlen, @appsignal/nodejs in Kombination mit @appsignal/javascript und @appsignal/react auf der Client-Seite zu verwenden, um Full-Stack-Performance-Monitoring und Error-Tracking zu erhalten.
Aufgrund technischer Einschränkungen des AppSignal-Agents ist es nicht möglich, @appsignal/nodejs in der Serverless-Umgebung von Vercel zu verwenden. Wir empfehlen stattdessen die Verwendung unseres Vercel-Log-Drain sowie unserer Pakete Front-End-JavaScript und React.

​
Installation

Folgen Sie zunächst der Installationsanleitung für @appsignal/nodejs. Ändern Sie anschließend die Konfigurationsdatei next.config.js Ihres Next-Projekts, um Instrumentation-Hooks zu aktivieren: Wenn Sie Next 15 verwenden: 
const nextConfig = {
  serverExternalPackages: ["@appsignal/nodejs"],
};
Wenn Sie Next 13 oder 14 verwenden: 
const nextConfig = {
  // Add the `experimental` object if not present
  experimental: {
    // Add the following lines inside the object
    instrumentationHook: true,
    serverComponentsExternalPackages: ["@appsignal/nodejs"],
  },
};
Fügen Sie anschließend die folgende Datei als instrumentation.js im Stammverzeichnis Ihres Next.js-Projekts hinzu:
Wenn Ihr Projekt ein src-Verzeichnis hat, sollte die Datei instrumentation.js in diesem Verzeichnis abgelegt werden.Wenn Ihr Projekt den Next.js App Router verwendet, sollte die Datei nicht im Ordner app abgelegt werden, sondern in dem Ordner, der den Ordner app enthält.
export function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    require("./appsignal.cjs");
  }
}
Die Instrumentation-Hook-Datei verweist auf die Datei appsignal.cjs, die bei der Konfiguration von AppSignal erstellt wurde. Stellen Sie sicher, dass sich die Datei appsignal.cjs im selben Ordner wie die Datei instrumentation.js befindet, oder passen Sie den Pfad des require in der Datei instrumentation.js entsprechend an. Ändern Sie schließlich Ihre Konfigurationsdatei appsignal.cjs, um die HTTP-Instrumentierung zu deaktivieren, da sie andernfalls redundante Traces erzeugen würde: 
const { Appsignal } = require("@appsignal/nodejs");

new Appsignal({
  // Add the `disableDefaultInstrumentations` list if not present
  disableDefaultInstrumentations: [
    // Add the following line inside the list
    "@opentelemetry/instrumentation-http",
  ],
});

​
TypeScript-Unterstützung

Bei Verwendung von TypeScript verweisen die Backtraces, die von serverseitigen Next.js-Fehlern erzeugt werden, auf die kompilierten JavaScript-Dateien. Folgen Sie diesen Schritten, um Next.js so zu konfigurieren, dass die Backtraces auf den ursprünglichen TypeScript-Code verweisen. Konfigurieren Sie Next.js zunächst so, dass Source Maps erzeugt werden, indem Sie die folgenden Zeilen zur Datei next.config.js Ihrer Anwendung hinzufügen: 
const nextConfig = {
  // Add the `webpack` function if not present
  webpack: (config, { isServer }) => {
    // Add the following lines inside the function
    if (isServer) {
      config.devtool = "eval-source-map";
    }

    return config;
  },
};
Ändern Sie anschließend in Ihrer package.json, wie Ihre Next.js-Anwendung beim Ausführen von npm run start gestartet wird, indem Sie die Umgebungsvariable NODE_OPTIONS verwenden, um das Flag --enable-source-maps an die Node.js-Laufzeit zu übergeben: 
{
  "scripts": {
    // Modify the `start` script as follows
    "start": "NODE_OPTIONS=--enable-source-maps next start"
  }
}
Wenn Sie schließlich das Frontend-Integrationspaket @appsignal/javascript verwenden, um clientseitige Fehler zu erfassen, fügen Sie die Option productionBrowserSourceMaps zur Datei next.config.js hinzu, damit Next.js öffentliche Source Maps erzeugt: 
const nextConfig = {
  // Add the `productionBrowserSourceMaps` flag
  productionBrowserSourceMaps: true,
};

​
Funktionen

Die Next.js-Integration sendet AppSignal eine Performance-Probe für jede Anfrage. Innerhalb jeder Probe zeigt die Event-Timeline Ereignisse mit ihrer Dauer an, die Folgendem entsprechen:
  • Rendern des Dokuments
  • Ausführen der Funktion getServerSideProps (nur Pages Router)
  • Ausführen des Route-Handlers
  • Ausführen von HTTP-Anfragen mit dem serverseitigen fetch von Next.js (nur App Router)

​
Standalone-Output

Es werden möglicherweise keine Daten gemeldet, wenn Next.js mit output: "standalone" in next.config.js konfiguriert ist. Wenn Next.js die App-Größe so optimiert, dass nur das enthalten ist, was von der App verwendet wird, werden die AppSignal-Extension und der Agent ausgelassen, die die Daten an unsere Server melden. Wenn Sie den Next.js „with-docker“-Starter verwenden, insbesondere das Dockerfile, ist eine Änderung erforderlich, um sicherzustellen, dass die AppSignal-Extension und der Agent im Produktions-Docker-Image enthalten sind. Fügen Sie die folgende Zeile zu Ihrem Dockerfile hinzu, nach ähnlichen COPY-Zeilen gegen Ende der Datei: 
# Dockerfile
COPY --from=builder --chown=nextjs:nodejs /app/node_modules/@appsignal/nodejs ./node_modules/@appsignal/nodejs
Die Änderung in Git wird in etwa wie folgt aussehen, Ihr Dockerfile kann jedoch leicht abweichen: 
--- Dockerfile
+++ Dockerfile
@@ -48,6 +48,7 @@ COPY --from=builder /app/public ./public
 # https://nextjs.org/docs/advanced-features/output-file-tracing
 COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
 COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/node_modules/@appsignal/nodejs ./node_modules/@appsignal/nodejs

 USER nextjs