JavaScript asynkron kontekstpropagering: Sporing av forespørsler og fortsettelse med AsyncLocalStorage

I moderne server-side JavaScript-utvikling, spesielt med Node.js, er asynkrone operasjoner allestedsnærværende. Å håndtere tilstand og kontekst på tvers av disse asynkrone grensene kan være utfordrende. Dette blogginnlegget utforsker konseptet asynkron kontekstpropagering, med fokus på hvordan man bruker AsyncLocalStorage for å oppnå effektiv sporing av forespørsler og fortsettelse. Vi vil undersøke fordelene, begrensningene og virkelige anvendelser, og gi praktiske eksempler for å illustrere bruken.

Forstå asynkron kontekstpropagering

Asynkron kontekstpropagering refererer til evnen til å opprettholde og propagere kontekstinformasjon (f.eks. forespørsels-ID-er, brukerautentiseringsdetaljer, korrelasjons-ID-er) på tvers av asynkrone operasjoner. Uten riktig kontekstpropagering blir det vanskelig å spore forespørsler, korrelere logger og diagnostisere ytelsesproblemer i distribuerte systemer.

Tradisjonelle tilnærminger til å håndtere kontekst er ofte avhengige av å sende kontekstobjekter eksplisitt gjennom funksjonskall, noe som kan føre til ordrik og feilutsatt kode. AsyncLocalStorage tilbyr en mer elegant løsning ved å gi en måte å lagre og hente kontekstdata innenfor en enkelt utførelseskontekst, selv på tvers av asynkrone operasjoner.

Introduksjon til AsyncLocalStorage

AsyncLocalStorage er en innebygd Node.js-modul (tilgjengelig siden Node.js v14.5.0) som gir en måte å lagre data som er lokale for levetiden til en asynkron operasjon. Den skaper i hovedsak et lagringssted som bevares på tvers av await-kall, promises og andre asynkrone grenser. Dette lar utviklere få tilgang til og endre kontekstdata uten å sende dem eksplisitt rundt.

Nøkkelfunksjoner i AsyncLocalStorage:

• Automatisk kontekstpropagering: Verdier lagret i AsyncLocalStorage blir automatisk propagert på tvers av asynkrone operasjoner innenfor samme utførelseskontekst.
• Forenklet kode: Reduserer behovet for å eksplisitt sende kontekstobjekter gjennom funksjonskall.
• Forbedret observerbarhet: Forenkler sporing av forespørsler og korrelasjon av logger og metrikker.
• Trådsikkerhet: Gir trådsikker tilgang til kontekstdata innenfor den gjeldende utførelseskonteksten.

Bruksområder for AsyncLocalStorage

AsyncLocalStorage er verdifull i ulike scenarier, inkludert:

• Sporing av forespørsler: Tildele en unik ID til hver innkommende forespørsel og propagere den gjennom hele forespørselens livssyklus for sporingsformål.
• Autentisering og autorisering: Lagre brukerautentiseringsdetaljer (f.eks. bruker-ID, roller, tillatelser) for tilgang til beskyttede ressurser.
• Logging og revisjon: Legge til forespørsel-spesifikke metadata i loggmeldinger for bedre feilsøking og revisjon.
• Ytelsesovervåking: Spore utførelsestiden til forskjellige komponenter i en forespørsel for ytelsesanalyse.
• Transaksjonsbehandling: Håndtere transaksjonstilstand på tvers av flere asynkrone operasjoner (f.eks. databasetransaksjoner).

Praktisk eksempel: Sporing av forespørsler med AsyncLocalStorage

La oss illustrere hvordan man bruker AsyncLocalStorage for sporing av forespørsler i en enkel Node.js-applikasjon. Vi vil lage en mellomvare som tildeler en unik ID til hver innkommende forespørsel og gjør den tilgjengelig gjennom hele forespørselens livssyklus.

Kodeeksempel

Installer først de nødvendige pakkene (om nødvendig):

            npm install uuid express
            

              
                Copy
              
            
          

Her er koden:

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Mellomvare for å tildele en forespørsels-ID og lagre den i AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simuler en asynkron operasjon
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Rutebehandler
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

I dette eksempelet:

1. Vi oppretter en AsyncLocalStorage-instans.
2. Vi definerer en mellomvare som tildeler en unik ID til hver innkommende forespørsel ved hjelp av uuid-biblioteket.
3. Vi bruker asyncLocalStorage.run() for å utføre forespørselsbehandleren innenfor konteksten til AsyncLocalStorage. Dette sikrer at alle verdier som er lagret i AsyncLocalStorage, er tilgjengelige gjennom hele forespørselens livssyklus.
4. Inne i mellomvaren lagrer vi forespørsels-ID-en i AsyncLocalStorage med asyncLocalStorage.getStore().set('requestId', requestId).
5. Vi definerer en asynkron funksjon doSomethingAsync() som simulerer en asynkron operasjon og henter forespørsels-ID-en fra AsyncLocalStorage.
6. I rutebehandleren henter vi forespørsels-ID-en fra AsyncLocalStorage og inkluderer den i responsen.

Når du kjører denne applikasjonen og sender en forespørsel til http://localhost:3000, vil du se at forespørsels-ID-en blir logget både i rutebehandleren og i den asynkrone funksjonen, noe som demonstrerer at konteksten blir korrekt propagert.

Forklaring

• AsyncLocalStorage-instans: Vi oppretter en instans av AsyncLocalStorage som vil inneholde våre kontekstdata.
• Mellomvare: Mellomvaren fanger opp hver innkommende forespørsel. Den genererer en UUID og bruker deretter asyncLocalStorage.run for å utføre resten av forespørselsbehandlingen *innenfor* konteksten til denne lagringen. Dette er avgjørende; det sikrer at alt nedstrøms har tilgang til de lagrede dataene.
• asyncLocalStorage.run(new Map(), ...): Denne metoden tar to argumenter: en ny, tom Map (du kan bruke andre datastrukturer hvis det passer for din kontekst) og en tilbakekallingsfunksjon. Tilbakekallingsfunksjonen inneholder koden som skal kjøres innenfor den asynkrone konteksten. Alle asynkrone operasjoner som startes innenfor dette tilbakekallet vil automatisk arve dataene som er lagret i Map-en.
• asyncLocalStorage.getStore(): Dette returnerer Map-en som ble sendt til asyncLocalStorage.run. Vi bruker den til å lagre og hente forespørsels-ID-en. Hvis run ikke er blitt kalt, vil dette returnere undefined, og det er derfor det er viktig å kalle run i mellomvaren.
• Asynkron funksjon: Funksjonen doSomethingAsync simulerer en asynkron operasjon. Avgjørende er at selv om den er asynkron (ved hjelp av setTimeout), har den fortsatt tilgang til forespørsels-ID-en fordi den kjører innenfor konteksten som er etablert av asyncLocalStorage.run.

Avansert bruk: Kombinere med loggbiblioteker

Å integrere AsyncLocalStorage med loggbiblioteker (som Winston eller Pino) kan betydelig forbedre observerbarheten til applikasjonene dine. Ved å injisere kontekstdata (f.eks. forespørsels-ID, bruker-ID) i loggmeldinger, kan du enkelt korrelere logger og spore forespørsler på tvers av forskjellige komponenter.

Eksempel med Winston

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (modified)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Incoming request: ${req.url}`); // Log the incoming request
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Doing something async...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Handling request...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

I dette eksempelet:

• Vi oppretter en Winston-loggerinstans og konfigurerer den til å inkludere forespørsels-ID-en fra AsyncLocalStorage i hver loggmelding. Nøkkelen er winston.format.printf, som henter forespørsels-ID-en (hvis tilgjengelig) fra AsyncLocalStorage. Vi sjekker om asyncLocalStorage.getStore() eksisterer for å unngå feil når vi logger utenfor en forespørselskontekst.
• Vi oppdaterer mellomvaren til å logge URL-en for den innkommende forespørselen.
• Vi oppdaterer rutebehandleren og den asynkrone funksjonen til å logge meldinger med den konfigurerte loggeren.

Nå vil alle loggmeldinger inkludere forespørsels-ID-en, noe som gjør det enklere å spore forespørsler og korrelere logger.

Alternative tilnærminger: cls-hooked og Async Hooks

Før AsyncLocalStorage ble tilgjengelig, ble biblioteker som cls-hooked ofte brukt for asynkron kontekstpropagering. cls-hooked bruker Async Hooks (et lavere nivå Node.js API) for å oppnå lignende funksjonalitet. Mens cls-hooked fortsatt er mye brukt, er AsyncLocalStorage generelt foretrukket på grunn av at det er innebygd og har forbedret ytelse.

Async Hooks (async_hooks)

Async Hooks tilbyr et lavere nivå API for å spore livssyklusen til asynkrone operasjoner. Selv om AsyncLocalStorage er bygget på toppen av Async Hooks, er det ofte mer komplekst og mindre ytelsesdyktig å bruke Async Hooks direkte. Async Hooks er mer egnet for svært spesifikke, avanserte bruksområder der finkornet kontroll over den asynkrone livssyklusen er nødvendig. Unngå å bruke Async Hooks direkte med mindre det er absolutt nødvendig.

Hvorfor foretrekke AsyncLocalStorage fremfor cls-hooked?

• Innebygd: AsyncLocalStorage er en del av Node.js-kjernen, noe som eliminerer behovet for eksterne avhengigheter.
• Ytelse: AsyncLocalStorage er generelt mer ytelsesdyktig enn cls-hooked på grunn av sin optimaliserte implementasjon.
• Vedlikehold: Som en innebygd modul blir AsyncLocalStorage aktivt vedlikeholdt av Node.js-kjerneteamet.

Hensyn og begrensninger

Selv om AsyncLocalStorage er et kraftig verktøy, er det viktig å være klar over begrensningene:

• Kontekstgrenser: AsyncLocalStorage propagerer kun kontekst innenfor samme utførelseskontekst. Hvis du sender data mellom forskjellige prosesser eller servere (f.eks. via meldingskøer eller gRPC), må du fortsatt eksplisitt serialisere og deserialisere kontekstdataene.
• Minnelekkasjer: Feil bruk av AsyncLocalStorage kan potensielt føre til minnelekkasjer hvis kontekstdataene ikke blir ryddet opp skikkelig. Sørg for at du bruker asyncLocalStorage.run() riktig og unngå å lagre store mengder data i AsyncLocalStorage.
• Kompleksitet: Selv om AsyncLocalStorage forenkler kontekstpropagering, kan det også legge til kompleksitet i koden din hvis den ikke brukes forsiktig. Sørg for at teamet ditt forstår hvordan det fungerer og følger beste praksis.
• Ikke en erstatning for globale variabler: AsyncLocalStorage er *ikke* en erstatning for globale variabler. Det er spesifikt designet for å propagere kontekst innenfor en enkelt forespørsel eller transaksjon. Overdreven bruk kan føre til tett koblet kode og gjøre testing vanskeligere.

Beste praksis for bruk av AsyncLocalStorage

For å bruke AsyncLocalStorage effektivt, bør du vurdere følgende beste praksis:

• Bruk mellomvare: Bruk mellomvare for å initialisere AsyncLocalStorage og lagre kontekstdata i begynnelsen av hver forespørsel.
• Lagre minimalt med data: Lagre kun essensielle kontekstdata i AsyncLocalStorage for å minimere minnebruk. Unngå å lagre store objekter eller sensitiv informasjon.
• Unngå direkte tilgang: Innkapsle tilgang til AsyncLocalStorage bak veldefinerte API-er for å unngå tett kobling og forbedre kodens vedlikeholdbarhet. Lag hjelpefunksjoner eller klasser for å håndtere kontekstdata.
• Vurder feilhåndtering: Implementer feilhåndtering for å elegant håndtere tilfeller der AsyncLocalStorage ikke er riktig initialisert.
• Test grundig: Skriv enhets- og integrasjonstester for å sikre at kontekstpropagering fungerer som forventet.
• Dokumenter bruken: Dokumenter tydelig hvordan AsyncLocalStorage brukes i applikasjonen din for å hjelpe andre utviklere med å forstå kontekstpropageringsmekanismen.

Integrasjon med OpenTelemetry

OpenTelemetry er et åpen kildekode-rammeverk for observerbarhet som tilbyr API-er, SDK-er og verktøy for å samle inn og eksportere telemetridata (f.eks. sporinger, metrikker, logger). AsyncLocalStorage kan sømløst integreres med OpenTelemetry for å automatisk propagere sporingskontekst på tvers av asynkrone operasjoner.

OpenTelemetry er sterkt avhengig av kontekstpropagering for å korrelere sporinger på tvers av forskjellige tjenester. Ved å bruke AsyncLocalStorage kan du sikre at sporingskonteksten blir korrekt propagert innenfor Node.js-applikasjonen din, slik at du kan bygge et omfattende distribuert sporingssystem.

Mange OpenTelemetry SDK-er bruker automatisk AsyncLocalStorage (eller cls-hooked hvis AsyncLocalStorage ikke er tilgjengelig) for kontekstpropagering. Sjekk dokumentasjonen til din valgte OpenTelemetry SDK for spesifikke detaljer.

Konklusjon

AsyncLocalStorage er et verdifullt verktøy for å håndtere asynkron kontekstpropagering i server-side JavaScript-applikasjoner. Ved å bruke det for sporing av forespørsler, autentisering, logging og andre bruksområder, kan du bygge mer robuste, observerbare og vedlikeholdbare applikasjoner. Selv om alternativer som cls-hooked og Async Hooks finnes, er AsyncLocalStorage generelt det foretrukne valget på grunn av at det er innebygd, har god ytelse og er enkelt å bruke. Husk å følge beste praksis og vær oppmerksom på begrensningene for å utnytte egenskapene effektivt. Evnen til å spore forespørsler og korrelere hendelser på tvers av asynkrone operasjoner er avgjørende for å bygge skalerbare og pålitelige systemer, spesielt i mikrotjenestearkitekturer og komplekse distribuerte miljøer. Bruk av AsyncLocalStorage hjelper til med å oppnå dette målet, noe som til slutt fører til bedre feilsøking, ytelsesovervåking og generell applikasjonshelse.