Инструментация, Web Vitals и наблюдаемость

4. Инструментация, Web Vitals и наблюдаемость

Ваш проект включает примеры:

кастомной инструментации через src/instrumentation.ts и src/instrumentation-client.ts,
измерения Web Vitals через next/web-vitals в WebVitals‑компоненте,
страницы‑демо 15-instrumentation.

Здесь собраны принципы и паттерны, как «засунуть весь проект под микроскоп»: логирование, метрики, обработка ошибок.

4.1. Файл `instrumentation.ts`: глобовые хуки приложения

В App Router Next.js позволяет описывать глобовую инструментaцию в файле:

src/instrumentation.ts

Ключевые элементы:

export async function register() — вызывается при запуске:
- в Node.js‑рантайме,
- (опционально) в Edge‑рантайме.
export const onRequestError — глобовый хук ошибок запросов.

Паттерн register:

export async function register() {
  console.log('Instrumentation initialized');

  // Пример: выполняем код только на Node.js‑рантайме
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const os = await import('os');
    console.log('hostname', os.hostname());
  }

  // Здесь можно условно подключить разные модули в зависимости от рантайма
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    // await import('./instrumentation-node');
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    // await import('./instrumentation-edge');
  }
}

Идеи:

Можно инициализировать:
- подключение к системам логирования (Sentry, Datadog, Logtail и т.п.);
- глобовые обработчики ошибок;
- метрики (Prometheus, OpenTelemetry).
Разделяйте код для Node.js и Edge:
- process.env.NEXT_RUNTIME === 'nodejs' — можно использовать Node API (fs, os, process и т.п.);
- process.env.NEXT_RUNTIME === 'edge' — только Web‑/Edge‑совместимые API.

4.2. Глобовая обработка ошибок запросов: `onRequestError`

В instrumentation.ts также определяется:

export const onRequestError = async (err: any, request: any, context: any) => {
  console.log('ERROR', err, request, context);
};

Принцип: этот хук позволяет:

глобально логировать ошибки запросов,
отправлять информацию о падениях в ваш логгер/метрики.

Типичный практический вариант:

export async function onRequestError(
  error: unknown,
  request: Request,
  context: { route?: string },
) {
  // Отправляем ошибку в систему мониторинга
  // e.g. Sentry.captureException(error, { extra: { url: request.url } });
  console.error('Request error:', error, 'URL:', request.url, 'Context:', context);
}

4.3. Клиентская инструментaция: `instrumentation-client.ts`

Файл src/instrumentation-client.ts — место для:

инициализации клиентских SDK (анализ фронтенда, трекинг событий),
логирования клиентских ошибок.

Простейший пример (как в проекте):

console.log('Instrumentation client initialized');

Что обычно делают здесь на практике:

Инициализируют Sentry/Datadog/NewRelic на клиенте:

import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Подключают аналитические SDK (Amplitude, PostHog, Google Analytics и т.п.).

4.4. Web Vitals: измерение качества фронтенда

Компонент WebVitals в вашем src/app/_components/WebVitals.tsx использует:

useReportWebVitals из next/web-vitals,
функцию, которая логирует метрики.

Паттерн:

'use client';

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

function logWebVitals(metric: any) {
  console.log('METRIC', metric);
  // здесь можно отправить метрику на свой backend или в аналитический сервис
}

export function WebVitals() {
  useReportWebVitals(logWebVitals);
  return null;
}

Использование в RootLayout:

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

Какие метрики приходят:

FCP — First Contentful Paint,
LCP — Largest Contentful Paint,
CLS — Cumulative Layout Shift,
FID / INP — время реакции,
TTFB — Time to First Byte,
и др.

Паттерн отправки метрик на сервер:

function logWebVitals(metric: any) {
  // Пример отправки на backend
  navigator.sendBeacon(
    '/analytics',
    JSON.stringify({
      name: metric.name,
      value: metric.value,
      id: metric.id,
      label: metric.label,
    }),
  );
}

4.5. Страница‑демо `15-instrumentation`

Отдельная страница‑маршрут (в вашем коде она возвращает, например, 25-instrumentation/15-instrumentation) служит:

полигоном для тестирования инструментaции,
местом для проверки, что:
- вызывается register,
- клиентская инструментaция инициализируется,
- WebVitals и другие метрики работают.

Типичный вид:

export default function InstrumentationDemoPage() {
  return <div>Instrumentation demo page</div>;
}

Можно добавить на неё:

кнопку для искусственного выброса ошибки (проверка onRequestError/Sentry),
искусственные задержки, чтобы видеть показатели LCP/INP.

4.6. Общие принципы построения наблюдаемости

На основе ваших примеров можно сформулировать базовый чек‑лист:

1. Логирование на сервере:
- используйте instrumentation.ts для инициализации логгера;
- в server actions и API‑роутах логируйте ключевые события (создание/обновление сущностей, ошибки).
2. Логирование на клиенте:
- инициализируйте SDK в instrumentation-client.ts;
- перехватывайте window.onerror, unhandledrejection (если нужно).
3. Метрики производительности:
- подключите WebVitals в root layout;
- решите, куда отправлять метрики: свой backend, сторонний сервис.
4. Глобовая обработка ошибок:
- используйте onRequestError для серверных ошибок запросов;
- на клиенте используйте boundary‑компоненты (error.tsx в маршрутах, React error boundaries).

4.7. Пример «полной» связки

Ниже — пример того, как можно объединить всё вместе:

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

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    Sentry.init({
      dsn: process.env.SENTRY_DSN,
      tracesSampleRate: 1.0,
    });
  }
}

export async function onRequestError(
  error: unknown,
  request: Request,
  context: { route?: string },
) {
  Sentry.captureException(error, {
    extra: { url: request.url, route: context.route },
  });
}

// src/instrumentation-client.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

// src/app/_components/WebVitals.tsx
'use client';

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

export function WebVitals() {
  useReportWebVitals((metric) => {
    // Отправить на backend или в Sentry
    console.log('METRIC', metric);
  });

  return null;
}

Этот модуль в вашем «конспекте» отвечает за всё, что связано с наблюдаемостью: как увидеть, что происходит с приложением в продакшене, и как находить проблемы ещё до того, как их заметят пользователи.

4. Инструментация, Web Vitals и наблюдаемость

4.1. Файл instrumentation.ts: глобовые хуки приложения

4.2. Глобовая обработка ошибок запросов: onRequestError

4.3. Клиентская инструментaция: instrumentation-client.ts