Next.js instrumentavimas: programos stebėjimo kablys (hooks) produkcijos aplinkos įžvalgoms

Next.js instrumentavimas suteikia galingą mechanizmą stebėti ir matuoti jūsų programos našumą produkcijos aplinkoje. Naudodami programos stebėjimo kablys (hooks), galite gauti išsamių įžvalgų apie užklausų apdorojimą, atvaizdavimą serveryje (server-side rendering), duomenų gavimą ir kitus svarbius jūsų programos veikimo aspektus. Tai leidžia nustatyti strigimo vietas, diagnozuoti našumo problemas ir optimizuoti programą siekiant geresnės vartotojo patirties. Tai ypač svarbu diegiant Next.js programas visame pasaulyje, kur tinklo delsa ir geografiškai paskirstyti vartotojai gali sukelti unikalių iššūkių.

Kas yra Next.js instrumentavimas?

Instrumentavimo funkcija Next.js leidžia registruoti kablys (hooks), kurie vykdomi įvairiuose programos gyvavimo ciklo etapuose. Šie kablys gali būti naudojami rinkti metrikas, sekimo duomenis (traces) ir žurnalus (logs), kurie vėliau gali būti siunčiami į programos našumo stebėjimo (APM) sistemą ar kitus stebimumo įrankius. Tai suteikia išsamų jūsų programos našumo vaizdą realiuoju laiku.

Skirtingai nuo tradicinio kliento pusės stebėjimo, kuris fiksuoja tik naršyklės patirtį, Next.js instrumentavimas suteikia stebimumą tiek kliento, tiek serverio pusėje, leidžiantį matyti visos programos (full-stack) našumą. Tai yra labai svarbu norint suprasti, kaip atvaizdavimas serveryje, API maršrutai ir duomenų gavimas veikia bendrą vartotojo patirtį.

Pagrindiniai instrumentavimo privalumai

Geresnis stebimumas: Gaukite išsamų matomumą apie savo programos našumo metrikas, sekimo duomenis ir žurnalus.
Greitesnis problemų sprendimas: Greitai nustatykite ir diagnozuokite našumo problemas naudodami išsamius našumo duomenis.
Optimizuotas našumas: Tiksliai nustatykite našumo strigimo vietas ir optimizuokite savo programą geresnei vartotojo patirčiai.
Stebėjimas realiuoju laiku: Stebėkite savo programos našumą realiuoju laiku, kad galėtumėte aktyviai aptikti problemas ir į jas reaguoti.
Sąnaudų mažinimas: Nustatydami neefektyvias vietas, galite sumažinti infrastruktūros išlaidas. Pavyzdžiui, sutrumpinus be-serverių (serverless) funkcijos vykdymo laiką tiesiogiai sumažinamos išlaidos.

Instrumentavimo nustatymas Next.js

Norėdami įjungti instrumentavimą savo Next.js programoje, turite sukurti instrumentation.js (arba instrumentation.ts) failą pagrindiniame projekto kataloge. Šiame faile bus kablys, kuriuos norite registruoti.

Štai pagrindinis instrumentation.ts failo pavyzdys:

// instrumentation.ts

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { trace } = await import('./utils/tracing');

    trace('registering-tracing');
  }
}

Šiame pavyzdyje importuojame trace funkciją iš ./utils/tracing failo ir iškviečiame ją register funkcijoje. register funkciją automatiškai iškviečia Next.js, kai programa paleidžiama.

Sąlyginis vykdymas pagal vykdymo aplinką

Kintamasis process.env.NEXT_RUNTIME yra labai svarbus nustatant vykdymo kontekstą. Jis leidžia sąlygiškai vykdyti kodą priklausomai nuo to, ar programa veikia Node.js aplinkoje (serverio pusės atvaizdavimui, API maršrutams ir t. t.), ar Edge Runtime aplinkoje (edge funkcijoms). Tai svarbu, nes tam tikros stebėjimo bibliotekos ar įrankiai gali būti suderinami tik su viena ar kita vykdymo aplinka.

Pavyzdžiui, galite norėti naudoti konkretų APM agentą Node.js aplinkoms ir kitą įrankį Edge Runtime aplinkoms. Naudojant process.env.NEXT_RUNTIME, galite įkelti atitinkamus modulius tik tada, kai tai būtina.

Programos stebėjimo kablys diegimas

Dabar panagrinėkime keletą pavyzdžių, kaip įdiegti programos stebėjimo kablys Next.js.

1. Užklausos apdorojimo laiko matavimas

Vienas iš dažniausių instrumentavimo panaudojimo atvejų yra gaunamų užklausų apdorojimo laiko matavimas. Tai gali padėti nustatyti lėtus galinius taškus (endpoints) ir optimizuoti jų našumą.

Štai pavyzdys, kaip matuoti užklausos apdorojimo laiką naudojant performance API:

// utils/tracing.ts

import { performance } from 'perf_hooks';

export function trace(eventName: string) {
  const start = performance.now();

  return () => {
    const end = performance.now();
    const duration = end - start;

    console.log(`[${eventName}] took ${duration}ms`);
    // Tikroje programoje šiuos duomenis siųstumėte į APM sistemą.
  };
}

Faile instrumentation.ts:

// instrumentation.ts

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { trace } = await import('./utils/tracing');

    const endTrace = trace('request-handling');

    // Imituojamas užklausos apdorojimas
    await new Promise((resolve) => setTimeout(resolve, 100));

    endTrace();
  }
}

Šis pavyzdys matuoja užklausos apdorojimo laiką ir išveda trukmę į konsolę. Tikroje programoje šiuos duomenis siųstumėte į APM sistemą tolesnei analizei.

2. Atvaizdavimo serveryje (SSR) laiko stebėjimas

Atvaizdavimas serveryje (SSR) yra pagrindinė Next.js savybė, tačiau ji taip pat gali tapti našumo strigimo vieta. Puslapių atvaizdavimo serveryje laiko stebėjimas yra labai svarbus siekiant užtikrinti greitą vartotojo patirtį.

Galite naudoti instrumentavimą, kad išmatuotumėte getServerSideProps ar getStaticProps funkcijų vykdymo laiką. Šios funkcijos yra atsakingos už duomenų gavimą ir jų paruošimą atvaizdavimui serveryje.

// pages/index.tsx

import { GetServerSideProps } from 'next';
import { trace } from '../utils/tracing';

interface Props {
  data: string;
}

export const getServerSideProps: GetServerSideProps = async () => {
  const endTrace = trace('getServerSideProps');
  const data = await fetchData();
  endTrace();

  return {
    props: { data },
  };
};

async function fetchData() {
  // Imituojamas duomenų gavimas iš išorinės API
  await new Promise((resolve) => setTimeout(resolve, 50));
  return 'Data from API';
}

export default function Home({ data }: Props) {
  return {data};
}

Šiame pavyzdyje naudojame trace funkciją, kad išmatuotume getServerSideProps funkcijos vykdymo laiką. Tai leidžia mums nustatyti našumo problemas duomenų gavimo procese.

3. API maršrutų našumo sekimas

Next.js API maršrutai leidžia kurti be-serverių (serverless) funkcijas, kurios apdoroja API užklausas. Šių API maršrutų našumo stebėjimas yra būtinas siekiant užtikrinti greitai reaguojančią serverio dalį (backend).

Galite naudoti instrumentavimą, kad išmatuotumėte API užklausų apdorojimo laiką savo API maršrutuose.

// pages/api/hello.ts

import type { NextApiRequest, NextApiResponse } from 'next'
import { trace } from '../../utils/tracing';

type Data = {
  name: string
}

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const endTrace = trace('api-hello');
  // Imituojamas darbas
  await new Promise((resolve) => setTimeout(resolve, 25));
  endTrace();
  res.status(200).json({ name: 'John Doe' })
}

Šis pavyzdys matuoja API užklausos apdorojimo laiką ir grąžina JSON atsakymą. Tai padeda suprasti jūsų serverio dalies našumą ir nustatyti lėtus API galinius taškus.

4. Edge vykdymo aplinkos (Edge Runtime) našumo stebėjimas

Next.js Edge vykdymo aplinka (Edge Runtime) leidžia diegti jūsų programą arčiau vartotojų esančiuose serveriuose (edge). Tai gali žymiai pagerinti našumą, ypač globaliai paskirstytoms programoms. Tačiau svarbu stebėti jūsų programos našumą Edge vykdymo aplinkoje, kad įsitikintumėte, jog ji veikia efektyviai.

Instrumentavimas gali būti naudojamas stebėti jūsų programos našumą Edge vykdymo aplinkoje. Tai leidžia nustatyti našumo problemas, būdingas būtent Edge vykdymo aplinkai.

Svarbi pastaba: Ne visi stebėjimo įrankiai palaiko Edge vykdymo aplinką. Gali tekti naudoti specializuotus įrankius ar bibliotekas, skirtas Edge vykdymo aplinkai.

Pavyzdžiui, „Vercel“ teikia integruotą analitiką, kurią galima naudoti programos našumui stebėti Edge vykdymo aplinkoje. Taip pat galite naudoti trečiųjų šalių stebėjimo įrankius, palaikančius Edge vykdymo aplinką, tokius kaip „Datadog“ ar „New Relic“.

Integracija su APM sistemomis

Duomenys, surinkti jūsų instrumentavimo kablys, yra vertingiausi, kai siunčiami į APM (Application Performance Monitoring) sistemą. APM sistemos suteikia įrankius našumo duomenų vizualizavimui, analizei ir perspėjimams. Populiarios APM sistemos apima:

Datadog: Išsami stebėjimo ir analizės platforma.
New Relic: APM platforma su plačiu funkcijų spektru.
Sentry: Populiarus klaidų sekimo ir našumo stebėjimo įrankis.
Honeycomb: Stebimumo platforma šiuolaikinėms programoms.
Dynatrace: Dirbtiniu intelektu paremta stebėjimo ir stebimumo platforma.

Konkretūs integravimo su APM sistema žingsniai priklausys nuo pasirinktos sistemos. Tačiau bendras procesas apima šiuos veiksmus:

Įdiekite APM agentą arba SDK savo Next.js programoje.
Konfigūruokite APM agentą naudodami savo APM sistemos API raktą ar prisijungimo duomenis.
Naudokite APM agento API, kad siųstumėte metrikas, sekimo duomenis ir žurnalus iš savo instrumentavimo kablys.

Pavyzdys naudojant OpenTelemetry su Datadog:

OpenTelemetry yra atvirojo kodo stebimumo sistema, suteikianti standartizuotą būdą rinkti ir eksportuoti telemetrijos duomenis. Ji gali būti naudojama integruoti su įvairiomis APM sistemomis, įskaitant Datadog.

// utils/tracing.ts

import { trace, context } from '@opentelemetry/api';

const tracer = trace.getTracer('my-app-tracer');

export function traceFunction any>(
  operationName: string,
  fn: T
): T {
  return function tracedFunction(...args: Parameters): ReturnType {
    const span = tracer.startSpan(operationName);
    const ctx = trace.setSpan(context.active(), span);

    try {
      return context.with(ctx, () => fn(...args));
    } finally {
      span.end();
    }
  } as T;
}

Panaudojimas getServerSideProps viduje:

// pages/index.tsx

import { GetServerSideProps } from 'next';
import { traceFunction } from '../utils/tracing';

interface Props {
  data: string;
}

async function fetchData() {
  // Imituojamas duomenų gavimas iš išorinės API
  await new Promise((resolve) => setTimeout(resolve, 50));
  return 'Data from API';
}

export const getServerSideProps: GetServerSideProps = async () => {
  const tracedFetchData = traceFunction('fetchData', fetchData);
  const data = await tracedFetchData();

  return {
    props: { data },
  };
};

export default function Home({ data }: Props) {
  return {data};
}

Šis supaprastintas OpenTelemetry pavyzdys parodo, kaip apgaubti funkciją sekimo intervalu (tracing span). Tikrasis OpenTelemetry SDK ir Datadog agento nustatymas bei konfigūravimas yra sudėtingesnis ir reikalauja papildomų žingsnių, įskaitant aplinkos kintamųjų nustatymą, eksportuotojo konfigūravimą ir SDK inicijavimą jūsų instrumentation.ts faile. Išsamių instrukcijų ieškokite OpenTelemetry ir Datadog dokumentacijoje.

Gerosios Next.js instrumentavimo praktikos

Pradėkite anksti: Įdiekite instrumentavimą ankstyvoje kūrimo stadijoje, kad nustatytumėte našumo problemas prieš joms pasiekiant produkcijos aplinką.
Sutelkti dėmesį į svarbiausias metrikas: Teikite pirmenybę metrikoms, kurios yra svarbiausios jūsų programos našumui, pavyzdžiui, užklausos apdorojimo laikui, atvaizdavimo serveryje laikui ir API maršrutų našumui.
Naudokite prasmingus įvykių pavadinimus: Naudokite aiškius ir aprašomuosius įvykių pavadinimus savo instrumentavimo kablys, kad būtų lengviau suprasti duomenis.
Minimizuokite papildomą apkrovą: Užtikrinkite, kad jūsų instrumentavimo kodas būtų efektyvus ir nesukurtų didelės papildomos apkrovos jūsų programos našumui.
Naudokite sąlyginį vykdymą: Naudokite process.env.NEXT_RUNTIME, kad sąlygiškai vykdytumėte kodą priklausomai nuo vykdymo aplinkos.
Saugokite jautrius duomenis: Venkite registruoti ar siųsti jautrius duomenis į APM sistemas.
Testuokite savo instrumentavimą: Kruopščiai testuokite savo instrumentavimo kodą, kad įsitikintumėte, jog jis veikia teisingai ir nesukelia klaidų ar našumo problemų.
Stebėkite savo instrumentavimą: Stebėkite savo instrumentavimo kodą, kad įsitikintumėte, jog jis neveikia netinkamai ar nesukelia našumo problemų.

Dažniausios klaidos ir jų sprendimai

Neteisingas vykdymo aplinkos nustatymas: Įsitikinkite, kad teisingai naudojate `process.env.NEXT_RUNTIME`, kad išvengtumėte klaidų, kai kodas vykdomas netinkamoje aplinkoje. Patikrinkite savo sąlyginę logiką ir aplinkos kintamuosius.
Perteklinis žurnalų registravimas: Venkite registruoti per daug duomenų, nes tai gali paveikti našumą. Registruokite tik informaciją, kuri yra būtina derinimui ir stebėjimui. Apsvarstykite duomenų atrankos (sampling) technikas, kad sumažintumėte registruojamų duomenų kiekį.
Jautrių duomenų atskleidimas: Būkite atsargūs ir neregistruokite jautrių duomenų, tokių kaip slaptažodžiai ar API raktai. Naudokite aplinkos kintamuosius ar konfigūracijos failus jautriems duomenims saugoti ir venkite tiesiogiai registruoti šias vertes.
Asinchroniškumo problemos: Dirbdami su asinchroninėmis operacijomis, įsitikinkite, kad jūsų sekimo intervalai (tracing spans) yra tinkamai uždaromi. Jei intervalas neuždaromas, tai gali lemti netikslius našumo duomenis. Naudokite `try...finally` blokus arba Promises, kad užtikrintumėte, jog intervalai visada bus uždaryti.
Trečiųjų šalių bibliotekų konfliktai: Žinokite, kad kai kurios trečiųjų šalių bibliotekos gali konfliktuoti su instrumentavimo kodu. Kruopščiai testuokite savo instrumentavimo kodą, kad įsitikintumėte, jog jis nesukelia problemų su kitomis bibliotekomis.

Išvada

Next.js instrumentavimas suteikia galingą mechanizmą stebėti ir matuoti jūsų programos našumą produkcijos aplinkoje. Įdiegę programos stebėjimo kablys, galite gauti išsamių įžvalgų apie užklausų apdorojimą, atvaizdavimą serveryje, duomenų gavimą ir kitus svarbius jūsų programos veikimo aspektus. Tai leidžia nustatyti strigimo vietas, diagnozuoti našumo problemas ir optimizuoti programą siekiant geresnės vartotojo patirties.

Laikydamiesi šiame vadove pateiktų geriausių praktikų, galite efektyviai pasinaudoti Next.js instrumentavimu, siekdami pagerinti savo programų našumą ir patikimumą, nepriklausomai nuo to, kur yra jūsų vartotojai. Nepamirškite pasirinkti tinkamą APM sistemą pagal savo poreikius ir nuolat stebėti programos našumą, kad aktyviai nustatytumėte ir spręstumėte problemas.