Kurs Next.js · Moduł 1: Konfiguracja Next.js

Instrumentacja i debugowanie aplikacji

15 min czytania ·
W tej lekcji9

W Metropolii Quantum zaawansowane systemy diagnostyczne są kluczowe dla prawidłowego funkcjonowania całej infrastruktury. Niewidzialne dla przeciętnego obywatela sieci czujników i analizatorów nieustannie monitorują każdy aspekt miejskich systemów, pozwalając inżynierom na szybkie wykrywanie i naprawianie problemów. Podobnie w świecie Next.js instrumentacja i narzędzia debugowania zapewniają deweloperom wgląd w działanie aplikacji i możliwość szybkiego rozwiązywania problemów.

Czym jest instrumentacja w Next.js?

Instrumentacja w kontekście Next.js odnosi się do procesu dodawania kodu monitorującego do aplikacji w celu zbierania danych o jej wydajności, błędach i zachowaniu. Jest to jak sieć czujników kwantowych rozmieszczonych w kluczowych punktach Metropolii Quantum - pozwalają one na monitorowanie stanu systemów i zbieranie danych niezbędnych do analizy ich działania.

Next.js 16 oferuje zaawansowane narzędzia instrumentacji, które pozwalają deweloperom lepiej zrozumieć i zoptymalizować działanie swoich aplikacji.

Konfiguracja instrumentacji w Next.js 16

W Next.js 16 do tego celu służy plik instrumentation.ts, stabilny od Next.js 15 i wykonywany raz, podczas startu serwera. Możesz go użyć do konfiguracji narzędzi monitorujących, takich jak Sentry, New Relic czy OpenTelemetry.

Aby włączyć instrumentację w aplikacji Next.js, wykonaj następujące kroki:

  1. Utwórz plik o nazwie instrumentation.ts (lub instrumentation.js) w katalogu głównym aplikacji (obok app lub src/app).

  2. Nie dodawaj żadnej flagi w next.config. W Next.js 13 i 14 instrumentacja była eksperymentalna i wymagała ustawienia experimental.instrumentationHook, ale od Next.js 15 jest stabilna, więc w Next.js 16 wystarczy sam plik. Starą konfigurację możesz jeszcze spotkać w starszych projektach:

    // next.config.js - tylko Next.js 13 i 14, w Next.js 16 zbędne
    /** @type {import('next').NextConfig} */
    const nextConfig = {
      experimental: {
        instrumentationHook: true,
      }
    };
    
    module.exports = nextConfig;
  3. Zaimplementuj hook register w pliku instrumentacji:

    // instrumentation.ts
    export async function register() {
      if (process.env.NEXT_RUNTIME === 'nodejs') {
        // Kod wykonywany tylko w środowisku Node.js (nie w Edge Runtime)
        console.log('Inicjalizacja systemu monitorowania Metropolii Quantum...');
    
        // Tutaj możesz zaimplementować właściwą instrumentację
        // np. inicjalizację Sentry, LogRocket, czy OpenTelemetry
      }
    }

Funkcja register jest wywoływana przy starcie aplikacji i może być używana do ustawienia monitorowania na poziomie całej aplikacji.

Integracja z popularnymi narzędziami monitorującymi

W Metropolii Quantum różne systemy monitorowania spełniają różne role - od monitorowania poziomu energii po śledzenie ruchu obywateli. Podobnie w świecie web developmentu różne narzędzia służą do różnych celów monitorowania.

1. OpenTelemetry

OpenTelemetry to zestaw API, bibliotek i narzędzi do zbierania danych telemetrycznych (metryk, logów i trace'ów) z aplikacji.

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    // Dynamiczny import, aby uniknąć problemów podczas budowania aplikacji
    const { registerOTel } = await import('./monitoring/otel');
    registerOTel();
  }
}

// monitoring/otel.ts
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';

export function registerOTel() {
  const sdk = new opentelemetry.NodeSDK({
    // Adres kolektora eksporter weźmie ze zmiennej OTEL_EXPORTER_OTLP_ENDPOINT i sam dopisze /v1/traces
    traceExporter: new OTLPTraceExporter(),
    instrumentations: [getNodeAutoInstrumentations()],
  });

  sdk.start();
  console.log('OpenTelemetry został zainicjalizowany');
}

2. Sentry

Sentry to popularna platforma do monitorowania błędów, która pozwala na śledzenie, priorytetyzację i naprawę błędów w czasie rzeczywistym.

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { initSentry } = await import('./monitoring/sentry');
    initSentry();
  }
}

// monitoring/sentry.ts
import * as Sentry from '@sentry/nextjs';

export function initSentry() {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV,
    tracesSampleRate: 1.0,
  });

  console.log('Sentry został zainicjalizowany');
}

3. Własna analityka

Możesz także zaimplementować własne rozwiązanie do zbierania danych analitycznych:

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { initAnalytics } = await import('./monitoring/analytics');
    initAnalytics();
  }
}

// monitoring/analytics.ts
import { NextRequest } from 'next/server';

// Middleware do zbierania danych analitycznych
export async function analyticsMiddleware(req: NextRequest, handler: () => Promise<Response>) {
  const start = Date.now();

  // Obsłuż żądanie i zmierz, ile to trwało
  const response = await handler();
  const responseTime = Date.now() - start;

  // Zapisz dane o wydajności
  console.log(`Ścieżka: ${req.nextUrl.pathname}, Czas: ${responseTime}ms`);

  // W rzeczywistej aplikacji wysłałbyś te dane do systemu analitycznego
  return response;
}

export function initAnalytics() {
  console.log('System analityczny Metropolii Quantum został zainicjalizowany');
}

Instrumentacja po stronie klienta

Instrumentacja nie ogranicza się tylko do serwera. W klienckich komponentach możesz korzystać z różnych narzędzi do monitorowania doświadczenia użytkownika i wydajności aplikacji.

React Profiler

React Profiler to wbudowane narzędzie React do mierzenia czasu renderowania komponentów. Możesz go użyć do identyfikacji wąskich gardeł wydajnościowych w swojej aplikacji.

// components/PerformanceWrapper.tsx
"use client";

import { Profiler, ProfilerOnRenderCallback, ReactNode } from 'react';

interface PerformanceWrapperProps {
  id: string;
  children: ReactNode;
}

export function PerformanceWrapper({ id, children }: PerformanceWrapperProps) {
  const handleRender: ProfilerOnRenderCallback = (
    id, // id komponentu, który został zrenderowany
    phase, // "mount", "update" lub "nested-update"
    actualDuration, // czas spędzony na renderowaniu
    baseDuration, // szacowany czas renderowania bez optymalizacji
    startTime, // kiedy React zaczął renderowanie
    commitTime // kiedy React zakończył renderowanie
  ) => {
    // Zapisz dane o wydajności
    console.log(`[Profiler] ${id} - ${phase}: ${actualDuration.toFixed(2)}ms`);

    // Uwaga: w zwykłym buildzie produkcyjnym React wyłącza Profiler, więc onRender się tu nie wywoła
    // (potrzebny build z profilowaniem: next build --profile)
    if (process.env.NODE_ENV === 'production') {
      // sendToAnalytics({ id, phase, actualDuration, baseDuration });
    }
  };

  return (
    <Profiler id={id} onRender={handleRender}>
      {children}
    </Profiler>
  );
}

Teraz możesz owinąć dowolny komponent w PerformanceWrapper, aby mierzyć jego wydajność:

// app/dashboard/page.tsx
"use client";

import { PerformanceWrapper } from '@/components/PerformanceWrapper';
import { DashboardContent } from '@/components/DashboardContent';

export default function DashboardPage() {
  return (
    <PerformanceWrapper id="dashboard-page">
      <DashboardContent />
    </PerformanceWrapper>
  );
}

Web Vitals

Web Vitals to inicjatywa Google mająca na celu zapewnienie jednolitych wskazówek dotyczących wskaźników jakości, które są niezbędne dla zapewnienia doskonałego wrażenia użytkownika w sieci.

Next.js 16 umożliwia łatwe raportowanie Web Vitals:

// app/_components/web-vitals.tsx
"use client";

import { useReportWebVitals } from 'next/web-vitals';

export function WebVitalsReporter() {
  useReportWebVitals((metric) => {
    const { id, name, rating, value } = metric;

    // Zapisz dane Web Vitals
    console.log(`[Web Vitals] ${name} (${rating}): ${value}`);

    // W produkcji wysłałbyś te dane do systemu analitycznego
    if (process.env.NODE_ENV === 'production') {
      // sendToAnalytics({ id, name, rating, value });
    }
  });

  return null;
}

Główny layout zostaje Server Componentem i tylko importuje ten mały komponent kliencki:

// app/layout.tsx
import { WebVitalsReporter } from './_components/web-vitals';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="pl">
      <body>
        <WebVitalsReporter />
        {children}
      </body>
    </html>
  );
}

Pole rating przyjmuje wartość good, needs-improvement albo poor, czyli gotową ocenę metryki według progów Google.

Debugowanie aplikacji Next.js 16

W Metropolii Quantum inżynierowie używają zaawansowanych narzędzi diagnostycznych, aby identyfikować i naprawiać problemy w systemach miejskich. Podobnie, deweloperzy Next.js mają dostęp do szeregu narzędzi, które ułatwiają debugowanie aplikacji.

1. Debugowanie po stronie serwera

a) Logi serwerowe

Najprostszym sposobem debugowania na serwerze jest dodanie logów:

// app/api/users/route.ts
export async function GET() {
  console.log('Rozpoczynam pobieranie użytkowników...');
  try {
    const users = await fetchUsers();
    console.log(`Pobrano ${users.length} użytkowników`);
    return Response.json(users);
  } catch (error) {
    console.error('Błąd podczas pobierania użytkowników:', error);
    return Response.json({ error: 'Internal Server Error' }, { status: 500 });
  }
}

Logi te będą widoczne w konsoli serwera, gdzie uruchomiona jest aplikacja Next.js.

b) Debugowanie z Node Inspector

Next.js obsługuje wbudowany debugger Node.js. Od Next.js 16.1 wystarczy dodać flagę --inspect do next dev (wcześniej używało się zmiennej NODE_OPTIONS='--inspect', która podłączała debugger do wszystkich procesów uruchamianych przez Next.js):

npx next dev --inspect

Następnie otwórz Chrome i przejdź do chrome://inspect, gdzie będziesz mógł się podłączyć do procesu Node.js i użyć narzędzi deweloperskich Chrome do debugowania.

Możesz także dodać breakpointy w kodzie za pomocą instrukcji debugger:

// app/api/data/route.ts
export async function GET() {
  debugger; // Zatrzyma wykonanie gdy podłączony jest debugger
  const data = await processData();
  return Response.json(data);
}

2. Debugowanie po stronie klienta

a) React Developer Tools

React Developer Tools to rozszerzenie przeglądarki, które pozwala na inspekcję drzewa komponentów React, monitorowanie props, state i hooks.

Aby efektywnie debugować za pomocą React Developer Tools:

  1. Zainstaluj rozszerzenie w swojej przeglądarce (Chrome, Firefox)
  2. Otwórz narzędzia deweloperskie przeglądarki i przejdź do zakładki "Components" lub "Profiler"
  3. Zbadaj strukturę komponentów i ich właściwości

Szczególnie użyteczne przy debugowaniu Server i Client Components są oznaczenia przy nazwach komponentów:

  • Server Components mają obok nazwy plakietkę ze środowiskiem (np. „Server”)
  • Client Components są wyświetlane bez takiej plakietki

b) Debugowanie stanu z użyciem React DevTools

// components/UserProfile.tsx
"use client";

import { useState, useEffect } from 'react';

export default function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchUser() {
      try {
        const response = await fetch(`/api/users/${userId}`);
        if (!response.ok) throw new Error('Failed to fetch user');
        const data = await response.json();
        setUser(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    fetchUser();
  }, [userId]);

  if (loading) return <div>Loading user data...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!user) return <div>No user found</div>;

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

W React DevTools możesz monitorować zmiany stanów user, loading i error w czasie rzeczywistym.

3. Debugowanie Server Actions

Server Actions, stabilne od Next.js 14, pozwalają na wykonywanie kodu na serwerze z komponentów klienckich. Debugowanie ich wymaga specjalnego podejścia:

// app/actions.ts
"use server";

import { revalidatePath } from 'next/cache';

export async function updateUserProfile(formData: FormData) {
  const userId = formData.get('userId');
  const name = formData.get('name');
  const email = formData.get('email');

  console.log(`Aktualizacja profilu dla użytkownika ${userId}:`, { name, email });

  try {
    // Logika aktualizacji profilu
    const result = await updateUserInDatabase(userId, { name, email });
    console.log('Rezultat aktualizacji:', result);

    // Odświeżenie ścieżki, aby pokazać zaktualizowane dane
    revalidatePath(`/users/${userId}`);

    return { success: true };
  } catch (error) {
    console.error('Błąd podczas aktualizacji profilu:', error);
    return { success: false, error: error.message };
  }
}

Debugowanie Server Actions polega głównie na:

  1. Dodawaniu logów serwera
  2. Sprawdzaniu, czy dane przekazywane z formularza są poprawne
  3. Monitorowaniu odpowiedzi zwracanych do komponentów klienckich

Od Next.js 16.2 część tej pracy wykonuje za Ciebie serwer deweloperski: przy każdym wywołaniu Server Function wypisuje w terminalu jej nazwę, argumenty, czas wykonania i plik, w którym ją zdefiniowano.

4. Narzędzia wbudowane w Next.js 16

Next.js 16 zawiera kilka wbudowanych narzędzi, które ułatwiają debugowanie:

a) Zaawansowane komunikaty błędów

Next.js 16 wyświetla szczegółowe komunikaty błędów w interfejsie deweloperskim, wskazując dokładnie, gdzie wystąpił problem i sugerując rozwiązania.

b) Fast Refresh

Fast Refresh pozwala na zachowanie stanu komponentów podczas wprowadzania zmian w kodzie, co znacznie ułatwia debugowanie i iteracyjny rozwój.

c) Next.js DevTools

W trybie deweloperskim Next.js 16 pokazuje w rogu strony wskaźnik Next.js Dev Tools. Działa bez żadnej konfiguracji: informuje o błędach kompilacji i wykonania, pokazuje, czy bieżąca trasa jest statyczna, czy dynamiczna, i otwiera panel z dodatkowymi informacjami. Jego położenie zmienisz opcją devIndicators, a asystentom AI te same informacje udostępnia serwer Next.js DevTools MCP.

Jeśli chcesz, żeby raporty Web Vitals wskazywały element odpowiedzialny za problem (np. obraz LCP albo element, który przesunął układ strony), włącz eksperymentalną opcję webVitalsAttribution:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    webVitalsAttribution: ['CLS', 'LCP'],
  },
};

module.exports = nextConfig;

Opcja jest eksperymentalna, więc włączaj ją tylko na czas szukania problemu; sam wskaźnik Dev Tools działa bez niej.

Monitorowanie wydajności aplikacji

W Metropolii Quantum inżynierowie nieustannie monitorują wydajność wszystkich systemów, aby zapewnić optymalne doświadczenie mieszkańcom. W świecie Next.js monitorowanie wydajności jest równie ważne dla zapewnienia dobrego doświadczenia użytkownikom.

1. Next.js Analytics

Next.js oferuje wbudowane narzędzie do monitorowania Web Vitals, które można zintegrować z narzędziem analitycznym:

// pages/_app.js - tylko Pages Router (w App Routerze użyj hooka useReportWebVitals, jak wyżej)
export function reportWebVitals(metric) {
  const { id, name, label, value } = metric;

  // Przykład: wysyłanie metryk do Google Analytics 4
  window.gtag('event', name, {
    value: Math.round(name === 'CLS' ? value * 1000 : value), // Wartości CLS są zazwyczaj małe
    event_label: id,
    non_interaction: true,
  });
}

2. Własne monitorowanie wydajności

Możesz także zaimplementować własne monitorowanie wydajności, wykorzystując Performance API:

// lib/performance.ts
export function measurePageLoad() {
  if (typeof window !== 'undefined' && window.performance) {
    const performanceEntries = performance.getEntriesByType('navigation');

    if (performanceEntries.length > 0) {
      const navigationEntry = performanceEntries[0] as PerformanceNavigationTiming;

      const metrics = {
        // Czas od rozpoczęcia nawigacji do zakończenia ładowania DOM
        domComplete: navigationEntry.domComplete,

        // Czas od rozpoczęcia nawigacji do pełnego załadowania strony
        loadComplete: navigationEntry.loadEventEnd,

        // Czas od rozpoczęcia nawigacji do pierwszego renderowania
        firstPaint: performance.getEntriesByName('first-paint')[0]?.startTime || 0,

        // Czas od rozpoczęcia nawigacji do pierwszego renderowania treści
        firstContentfulPaint: performance.getEntriesByName('first-contentful-paint')[0]?.startTime || 0,
      };

      console.log('Performance Metrics:', metrics);

      // W produkcji wysłałbyś te dane do systemu analitycznego
      if (process.env.NODE_ENV === 'production') {
        // sendToAnalytics(metrics);
      }
    }
  }
}

Funkcję tę możesz wywołać w komponencie klienckim, na przykład:

// components/PerformanceMonitor.tsx
"use client";

import { useEffect } from 'react';
import { measurePageLoad } from '@/lib/performance';

export function PerformanceMonitor() {
  useEffect(() => {
    // Mierz wydajność po załadowaniu strony
    if (document.readyState === 'complete') {
      measurePageLoad();
    } else {
      // loadEventEnd jest znany dopiero po zakończeniu obsługi zdarzenia load
      const onLoad = () => setTimeout(measurePageLoad, 0);
      window.addEventListener('load', onLoad);
      return () => window.removeEventListener('load', onLoad);
    }
  }, []);

  return null; // Komponent nie renderuje nic widocznego
}

Diagnostyka problemów z Server i Client Components

Jednym z najbardziej zaawansowanych aspektów Next.js 16 jest system Server i Client Components. Powoduje to jednak nowe wyzwania dotyczące debugowania.

1. Typowe problemy z Server Components

a) Próba użycia hooka React w Server Component

// app/dashboard/page.tsx
export default function Dashboard() {
  // BŁĄD: Nie można używać hooków w Server Components
  const [count, setCount] = useState(0);

  return <div>Dashboard</div>;
}

Rozwiązanie: Przenieś logikę stanu do Client Component.

// app/dashboard/page.tsx
import { DashboardClient } from './dashboard-client';

export default function Dashboard() {
  // Server Component
  return <DashboardClient />;
}

// dashboard-client.tsx
"use client";

import { useState } from 'react';

export function DashboardClient() {
  // Teraz możemy użyć hooka React
  const [count, setCount] = useState(0);

  return <div>Dashboard Count: {count}</div>;
}

b) Próba dostępu do API przeglądarki w Server Component

// app/dashboard/page.tsx
export default function Dashboard() {
  // BŁĄD: na serwerze nie ma obiektu window (ReferenceError: window is not defined)
  const windowWidth = window.innerWidth;

  return <div>Width: {windowWidth}</div>;
}

Rozwiązanie: Przenieś kod używający API przeglądarki do Client Component.

// app/dashboard/page.tsx
import { WindowSizeClient } from './window-size-client';

export default function Dashboard() {
  return <WindowSizeClient />;
}

// window-size-client.tsx
"use client";

import { useState, useEffect } from 'react';

export function WindowSizeClient() {
  const [windowWidth, setWindowWidth] = useState(0);

  useEffect(() => {
    setWindowWidth(window.innerWidth);

    const handleResize = () => setWindowWidth(window.innerWidth);
    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return <div>Width: {windowWidth}</div>;
}

2. Typowe problemy z Client Components

a) Import Server Component do Client Component

// BŁĄD: Nie można bezpośrednio importować Server Component do Client Component
// components/dashboard-wrapper.tsx
"use client";

import { ServerDataFetcher } from './server-data-fetcher';

export function DashboardWrapper() {
  return (
    <div className="dashboard">
      <ServerDataFetcher /> {/* To nie zadziała */}
    </div>
  );
}

Rozwiązanie: Przekazuj Server Components jako props do Client Components.

// app/dashboard/page.tsx
import { DashboardWrapper } from '@/components/dashboard-wrapper';
import { ServerDataFetcher } from '@/components/server-data-fetcher';

export default function Dashboard() {
  return (
    <DashboardWrapper>
      <ServerDataFetcher /> {/* Przekazanie jako children */}
    </DashboardWrapper>
  );
}

// components/dashboard-wrapper.tsx
"use client";

export function DashboardWrapper({ children }) {
  return (
    <div className="dashboard">
      {children}
    </div>
  );
}

// components/server-data-fetcher.tsx
// Server Component
export async function ServerDataFetcher() {
  const data = await fetchData();
  return <div>{data}</div>;
}

Narzędzia zewnętrzne do monitoringu produkcyjnego

W Metropolii Quantum centralne systemy monitorowania zbierają dane z tysięcy czujników rozmieszczonych po całym mieście, tworząc pełny obraz stanu miejskiej infrastruktury. W świecie aplikacji webowych podobne narzędzia zewnętrzne pomagają monitorować produkcyjne wdrożenia.

1. Vercel Analytics

Jeśli hostujesz swoją aplikację na Vercelu (twórcy Next.js), możesz skorzystać z Vercel Analytics:

npm install @vercel/analytics
# lub
yarn add @vercel/analytics
// app/layout.tsx
import { Analytics } from '@vercel/analytics/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  );
}

2. New Relic

New Relic to kompleksowe narzędzie do monitorowania aplikacji, które pozwala na śledzenie wydajności, błędów i zachowania użytkowników.

npm install newrelic
# lub
yarn add newrelic

Następnie utwórz plik newrelic.js w głównym katalogu projektu:

// newrelic.js
'use strict';

exports.config = {
  app_name: ['Quantum Voyages - Next.js'],
  license_key: process.env.NEW_RELIC_LICENSE_KEY,
  logging: {
    level: 'info'
  },
  allow_all_headers: true,
  attributes: {
    exclude: [
      'request.headers.cookie',
      'request.headers.authorization',
      'request.headers.proxyAuthorization',
      'request.headers.setCookie*',
      'request.headers.x*',
      'response.headers.cookie',
      'response.headers.authorization',
      'response.headers.proxyAuthorization',
      'response.headers.setCookie*',
      'response.headers.x*'
    ]
  }
};

3. Datadog

Datadog to platforma do monitorowania aplikacji i infrastruktury w chmurze: serwerów, baz danych, narzędzi i usług, z wbudowaną analizą zebranych danych.

npm install @datadog/browser-rum
# lub
yarn add @datadog/browser-rum
// app/datadog-rum.tsx
"use client";

import { useEffect } from 'react';
import { datadogRum } from '@datadog/browser-rum';

export function DatadogRUM() {
  useEffect(() => {
    if (process.env.NODE_ENV === 'production') {
      datadogRum.init({
        applicationId: process.env.NEXT_PUBLIC_DATADOG_APPLICATION_ID,
        clientToken: process.env.NEXT_PUBLIC_DATADOG_CLIENT_TOKEN,
        site: 'datadoghq.eu', // lub 'datadoghq.com' zależnie od regionu
        service: 'quantum-voyages',
        env: process.env.NODE_ENV,
        version: '1.0.0',
        sessionSampleRate: 100,
        sessionReplaySampleRate: 100,
        trackUserInteractions: true,
        trackResources: true,
        trackLongTasks: true,
        defaultPrivacyLevel: 'mask-user-input'
      });
    }
  }, []);

  return null;
}

Następnie dodaj komponent do layoutu:

// app/layout.tsx
import { DatadogRUM } from './datadog-rum';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <DatadogRUM />
      </body>
    </html>
  );
}

Podsumowanie

Instrumentacja i debugowanie to kluczowe aspekty rozwoju aplikacji Next.js 16, podobnie jak systemy monitorowania są niezbędne dla prawidłowego funkcjonowania Metropolii Quantum. Dzięki odpowiednim narzędziom i praktykom możesz:

  1. Monitorować wydajność aplikacji w środowisku produkcyjnym
  2. Śledzić błędy i szybko je naprawiać
  3. Zrozumieć zachowanie użytkowników i optymalizować doświadczenie
  4. Debugować złożone scenariusze związane z Server i Client Components
  5. Zapewnić niezawodność aplikacji w miarę jej rozwoju

Pamiętaj, że najlepszym podejściem jest wczesne włączenie instrumentacji i monitoringu w cykl rozwoju aplikacji, a nie dokładanie ich na samym końcu. Podobnie jak inżynierowie Metropolii Quantum projektują systemy monitorowania równocześnie z budową infrastruktury miejskiej, ty powinieneś implementować narzędzia do debugowania i monitorowania już na wczesnych etapach rozwoju aplikacji Next.js.

W kolejnej lekcji poznasz narzędzia deweloperskie Next.js 16, a zarządzaniem zmiennymi środowiskowymi w konfiguracji produkcyjnej zajmiemy się w module 8, co pozwoli na bezpieczne przechowywanie wrażliwych danych i dostosowywanie zachowania aplikacji do różnych środowisk.

Kod do tej lekcji: App.tsx
import React, { useState } from 'react';

interface LogEntry {
  id: number;
  timestamp: string;
  level: 'info' | 'warn' | 'error';
  system: string;
  message: string;
}

const InstrumentationDashboard = () => {
  const [logs, setLogs] = useState<LogEntry[]>([]);
  const [filter, setFilter] = useState<string>('all');
  const [otelEnabled, setOtelEnabled] = useState(false);
  const [sentryEnabled, setSentryEnabled] = useState(false);

  const addLog = (level: LogEntry['level'], system: string, message: string) => {
    const entry: LogEntry = {
      id: Date.now() + Math.random(),
      timestamp: new Date().toISOString().slice(11, 23),
      level,
      system,
      message,
    };
    setLogs(prev => [entry, ...prev].slice(0, 20));
  };

  const simulateRegister = () => {
    addLog('info', 'instrumentation.ts', 'wywołano register() - NEXT_RUNTIME=nodejs');
    setTimeout(() => {
      if (otelEnabled) addLog('info', 'OpenTelemetry', 'Eksporter śladów zainicjalizowany');
      if (sentryEnabled) addLog('info', 'Sentry', 'Śledzenie błędów włączone');
      addLog('info', 'Server', 'Hooki instrumentacji zarejestrowane');
    }, 500);
  };

  const simulateError = () => {
    addLog('error', 'Route Handler', 'Nieobsłużony wyjątek w /api/users');
    if (sentryEnabled) {
      setTimeout(() => addLog('warn', 'Sentry', 'Błąd przechwycony i wysłany do panelu'), 300);
    }
  };

  const simulateRequest = () => {
    addLog('info', 'Proxy', 'Przychodzące żądanie: GET /dashboard');
    if (otelEnabled) {
      addLog('info', 'OpenTelemetry', 'Utworzono span: HTTP GET /dashboard');
      setTimeout(() => addLog('info', 'OpenTelemetry', 'Span zakończony: 145ms'), 400);
    }
    setTimeout(() => addLog('info', 'Server', 'Wysłano odpowiedź: 200 OK'), 600);
  };

  const levelColor = (level: string) => {
    switch (level) {
      case 'info': return '#4caf50';
      case 'warn': return '#ff9800';
      case 'error': return '#f44336';
      default: return '#999';
    }
  };

  const filteredLogs = filter === 'all' ? logs : logs.filter(l => l.level === filter);

  return (
    <div style={{ background: '#0f0f23', minHeight: '100vh', padding: '20px', color: '#fff', fontFamily: 'monospace' }}>
      <h1 style={{ color: '#64ffda', textAlign: 'center', marginBottom: '8px' }}>
        Panel instrumentacji
      </h1>
      <p style={{ textAlign: 'center', color: '#888', marginBottom: '24px' }}>
        Metropolia Quantum - System Monitorowania
      </p>

      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '16px', maxWidth: '900px', margin: '0 auto 20px' }}>
        <div style={{ background: 'rgba(255,255,255,0.05)', padding: '16px', borderRadius: '10px', border: '1px solid #333' }}>
          <h3 style={{ color: '#7c4dff', marginBottom: '12px' }}>Narzędzia monitoringu</h3>
          <label style={{ display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '8px', cursor: 'pointer' }}>
            <input type="checkbox" checked={otelEnabled} onChange={() => setOtelEnabled(!otelEnabled)} />
            <span style={{ color: otelEnabled ? '#4caf50' : '#666' }}>OpenTelemetry</span>
          </label>
          <label style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
            <input type="checkbox" checked={sentryEnabled} onChange={() => setSentryEnabled(!sentryEnabled)} />
            <span style={{ color: sentryEnabled ? '#4caf50' : '#666' }}>Sentry</span>
          </label>
        </div>

        <div style={{ background: 'rgba(255,255,255,0.05)', padding: '16px', borderRadius: '10px', border: '1px solid #333' }}>
          <h3 style={{ color: '#7c4dff', marginBottom: '12px' }}>Symulacja</h3>
          <div style={{ display: 'flex', flexDirection: 'column', gap: '6px' }}>
            <button onClick={simulateRegister} style={{ padding: '8px', background: '#1a73e8', border: 'none', borderRadius: '6px', color: '#fff', cursor: 'pointer' }}>
              Hook register()
            </button>
            <button onClick={simulateRequest} style={{ padding: '8px', background: '#0f9d58', border: 'none', borderRadius: '6px', color: '#fff', cursor: 'pointer' }}>
              Żądanie HTTP
            </button>
            <button onClick={simulateError} style={{ padding: '8px', background: '#db4437', border: 'none', borderRadius: '6px', color: '#fff', cursor: 'pointer' }}>
              Wywołaj błąd
            </button>
          </div>
        </div>
      </div>

      <div style={{ maxWidth: '900px', margin: '0 auto' }}>
        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '10px' }}>
          <h3 style={{ color: '#64ffda' }}>Dziennik zdarzeń</h3>
          <div style={{ display: 'flex', gap: '6px' }}>
            {['all', 'info', 'warn', 'error'].map(f => (
              <button key={f} onClick={() => setFilter(f)}
                style={{ padding: '4px 12px', background: filter === f ? '#7c4dff' : 'rgba(255,255,255,0.1)',
                  border: 'none', borderRadius: '4px', color: '#fff', cursor: 'pointer', fontSize: '12px' }}>
                {f.toUpperCase()}
              </button>
            ))}
            <button onClick={() => setLogs([])}
              style={{ padding: '4px 12px', background: 'rgba(255,0,0,0.2)', border: 'none', borderRadius: '4px', color: '#f44336', cursor: 'pointer', fontSize: '12px' }}>
              WYCZYŚĆ
            </button>
          </div>
        </div>

        <div style={{ background: '#000', borderRadius: '8px', padding: '12px', minHeight: '200px', maxHeight: '300px', overflowY: 'auto' }}>
          {filteredLogs.length === 0 ? (
            <p style={{ color: '#555', textAlign: 'center', paddingTop: '80px' }}>
              Włącz narzędzia i zasymuluj zdarzenia, aby zobaczyć logi...
            </p>
          ) : (
            filteredLogs.map(log => (
              <div key={log.id} style={{ padding: '4px 0', borderBottom: '1px solid #1a1a1a', fontSize: '13px' }}>
                <span style={{ color: '#555' }}>{log.timestamp}</span>
                {' '}
                <span style={{ color: levelColor(log.level), fontWeight: 'bold' }}>[{log.level.toUpperCase()}]</span>
                {' '}
                <span style={{ color: '#7c4dff' }}>[{log.system}]</span>
                {' '}
                <span style={{ color: '#ccc' }}>{log.message}</span>
              </div>
            ))
          )}
        </div>
      </div>
    </div>
  );
};

export default InstrumentationDashboard;

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Który plik w katalogu głównym Next.js jest wykonywany przy starcie serwera w celu konfiguracji monitoringu?

  2. 2. Jaką funkcję implementuje się w pliku instrumentacji, aby uruchomić monitoring przy starcie aplikacji?

  3. 3. Co należy zrobić, gdy pojawia się błąd próby użycia hooka useState w Server Component?

Zadania praktyczne w grze

  • Klikanie w kolejności

    Ułóż polecenie, które w Next.js 16.1+ uruchamia serwer deweloperski z debuggerem Node.js

  1. PytaniePlik uruchamiany przy starcie serwera
  2. PytanieFunkcja hooka instrumentacji
  3. Kliknij w kolejnościUruchomienie debuggera Node
  4. PytanieHook w Server Component

Przydatne artykuły