Propagación de contexto asíncrono en JavaScript: rastreo de solicitudes y continuación con AsyncLocalStorage

En el desarrollo moderno de JavaScript del lado del servidor, particularmente con Node.js, las operaciones asíncronas son omnipresentes. Gestionar el estado y el contexto a través de estos límites asíncronos puede ser un desafío. Esta publicación de blog explora el concepto de propagación de contexto asíncrono, centrándose en cómo usar AsyncLocalStorage para lograr el rastreo de solicitudes y la continuación de manera efectiva. Examinaremos sus beneficios, limitaciones y aplicaciones en el mundo real, proporcionando ejemplos prácticos para ilustrar su uso.

Entendiendo la propagación de contexto asíncrono

La propagación de contexto asíncrono se refiere a la capacidad de mantener y propagar información de contexto (por ejemplo, IDs de solicitud, detalles de autenticación de usuario, IDs de correlación) a través de operaciones asíncronas. Sin una propagación de contexto adecuada, se vuelve difícil rastrear solicitudes, correlacionar registros y diagnosticar problemas de rendimiento en sistemas distribuidos.

Los enfoques tradicionales para gestionar el contexto a menudo se basan en pasar objetos de contexto explícitamente a través de las llamadas a funciones, lo que puede llevar a un código verboso y propenso a errores. AsyncLocalStorage ofrece una solución más elegante al proporcionar una forma de almacenar y recuperar datos de contexto dentro de un único contexto de ejecución, incluso a través de operaciones asíncronas.

Introducción a AsyncLocalStorage

AsyncLocalStorage es un módulo incorporado de Node.js (disponible desde Node.js v14.5.0) que proporciona una forma de almacenar datos que son locales al ciclo de vida de una operación asíncrona. Esencialmente, crea un espacio de almacenamiento que se preserva a través de llamadas a await, promesas y otros límites asíncronos. Esto permite a los desarrolladores acceder y modificar datos de contexto sin tener que pasarlos explícitamente.

Características clave de AsyncLocalStorage:

• Propagación automática de contexto: Los valores almacenados en AsyncLocalStorage se propagan automáticamente a través de operaciones asíncronas dentro del mismo contexto de ejecución.
• Código simplificado: Reduce la necesidad de pasar explícitamente objetos de contexto a través de las llamadas a funciones.
• Observabilidad mejorada: Facilita el rastreo de solicitudes y la correlación de registros y métricas.
• Seguridad en hilos (Thread-Safety): Proporciona acceso seguro a los datos de contexto dentro del contexto de ejecución actual.

Casos de uso para AsyncLocalStorage

AsyncLocalStorage es valioso en varios escenarios, incluyendo:

• Rastreo de solicitudes: Asignar un ID único a cada solicitud entrante y propagarlo a lo largo del ciclo de vida de la solicitud para fines de rastreo.
• Autenticación y autorización: Almacenar detalles de autenticación del usuario (por ejemplo, ID de usuario, roles, permisos) para acceder a recursos protegidos.
• Registro y auditoría: Adjuntar metadatos específicos de la solicitud a los mensajes de registro para una mejor depuración y auditoría.
• Monitoreo de rendimiento: Rastrear el tiempo de ejecución de diferentes componentes dentro de una solicitud para el análisis de rendimiento.
• Gestión de transacciones: Gestionar el estado transaccional a través de múltiples operaciones asíncronas (por ejemplo, transacciones de base de datos).

Ejemplo práctico: rastreo de solicitudes con AsyncLocalStorage

Ilustremos cómo usar AsyncLocalStorage para el rastreo de solicitudes en una aplicación simple de Node.js. Crearemos un middleware que asigna un ID único a cada solicitud entrante y lo hace disponible a lo largo del ciclo de vida de la solicitud.

Ejemplo de código

Primero, instala los paquetes necesarios (si es necesario):

            npm install uuid express
            

              
                Copy
              
            
          

Aquí está el código:

            // 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;

// Middleware para asignar un ID de solicitud y almacenarlo en AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simula una operación asíncrona
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Manejador de ruta
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
              
            
          

En este ejemplo:

1. Creamos una instancia de AsyncLocalStorage.
2. Definimos un middleware que asigna un ID único a cada solicitud entrante usando la librería uuid.
3. Usamos asyncLocalStorage.run() para ejecutar el manejador de la solicitud dentro del contexto de AsyncLocalStorage. Esto asegura que cualquier valor almacenado en AsyncLocalStorage esté disponible durante todo el ciclo de vida de la solicitud.
4. Dentro del middleware, almacenamos el ID de la solicitud en AsyncLocalStorage usando asyncLocalStorage.getStore().set('requestId', requestId).
5. Definimos una función asíncrona doSomethingAsync() que simula una operación asíncrona y recupera el ID de la solicitud de AsyncLocalStorage.
6. En el manejador de la ruta, recuperamos el ID de la solicitud de AsyncLocalStorage y lo incluimos en la respuesta.

Cuando ejecutes esta aplicación y envíes una solicitud a http://localhost:3000, verás el ID de la solicitud registrado tanto en el manejador de la ruta como en la función asíncrona, demostrando que el contexto se propaga correctamente.

Explicación

• Instancia de AsyncLocalStorage: Creamos una instancia de AsyncLocalStorage que contendrá nuestros datos de contexto.
• Middleware: El middleware intercepta cada solicitud entrante. Genera un UUID y luego usa asyncLocalStorage.run para ejecutar el resto del pipeline de manejo de la solicitud *dentro* del contexto de este almacenamiento. Esto es crucial; asegura que todo lo que sigue en la cadena tenga acceso a los datos almacenados.
• asyncLocalStorage.run(new Map(), ...): Este método toma dos argumentos: un nuevo Map vacío (puedes usar otras estructuras de datos si es apropiado para tu contexto) y una función de callback. La función de callback contiene el código que debe ejecutarse dentro del contexto asíncrono. Cualquier operación asíncrona iniciada dentro de este callback heredará automáticamente los datos almacenados en el Map.
• asyncLocalStorage.getStore(): Esto devuelve el Map que se pasó a asyncLocalStorage.run. Lo usamos para almacenar y recuperar el ID de la solicitud. Si run no ha sido llamado, esto devolverá undefined, por lo que es importante llamar a run dentro del middleware.
• Función asíncrona: La función doSomethingAsync simula una operación asíncrona. Crucialmente, aunque es asíncrona (usando setTimeout), todavía tiene acceso al ID de la solicitud porque se está ejecutando dentro del contexto establecido por asyncLocalStorage.run.

Uso avanzado: combinación con librerías de registro (Logging)

Integrar AsyncLocalStorage con librerías de registro (como Winston o Pino) puede mejorar significativamente la observabilidad de tus aplicaciones. Al inyectar datos de contexto (por ejemplo, ID de solicitud, ID de usuario) en los mensajes de registro, puedes correlacionar fácilmente los registros y rastrear solicitudes a través de diferentes componentes.

Ejemplo con 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 (modificado)
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}`); // Registra la solicitud entrante
    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
              
            
          

En este ejemplo:

• Creamos una instancia de logger de Winston y la configuramos para incluir el ID de la solicitud de AsyncLocalStorage en cada mensaje de registro. La parte clave es winston.format.printf, que recupera el ID de la solicitud (si está disponible) de AsyncLocalStorage. Comprobamos si asyncLocalStorage.getStore() existe para evitar errores al registrar fuera del contexto de una solicitud.
• Actualizamos el middleware para registrar la URL de la solicitud entrante.
• Actualizamos el manejador de la ruta y la función asíncrona para registrar mensajes usando el logger configurado.

Ahora, todos los mensajes de registro incluirán el ID de la solicitud, lo que facilitará el rastreo de solicitudes y la correlación de registros.

Enfoques alternativos: cls-hooked y Async Hooks

Antes de que AsyncLocalStorage estuviera disponible, librerías como cls-hooked se usaban comúnmente para la propagación de contexto asíncrono. cls-hooked utiliza Async Hooks (una API de Node.js de más bajo nivel) para lograr una funcionalidad similar. Aunque cls-hooked todavía es ampliamente utilizado, AsyncLocalStorage es generalmente preferido debido a su naturaleza incorporada y su rendimiento mejorado.

Async Hooks (async_hooks)

Async Hooks proporciona una API de más bajo nivel para rastrear el ciclo de vida de las operaciones asíncronas. Aunque AsyncLocalStorage está construido sobre Async Hooks, usar Async Hooks directamente suele ser más complejo y menos eficiente. Async Hooks son más apropiados para casos de uso muy específicos y avanzados donde se requiere un control detallado sobre el ciclo de vida asíncrono. Evita usar Async Hooks directamente a menos que sea absolutamente necesario.

¿Por qué preferir AsyncLocalStorage sobre cls-hooked?

• Incorporado: AsyncLocalStorage es parte del núcleo de Node.js, eliminando la necesidad de dependencias externas.
• Rendimiento: AsyncLocalStorage es generalmente más eficiente que cls-hooked debido a su implementación optimizada.
• Mantenimiento: Como módulo incorporado, AsyncLocalStorage es mantenido activamente por el equipo central de Node.js.

Consideraciones y limitaciones

Aunque AsyncLocalStorage es una herramienta poderosa, es importante ser consciente de sus limitaciones:

• Límites del contexto: AsyncLocalStorage solo propaga el contexto dentro del mismo contexto de ejecución. Si estás pasando datos entre diferentes procesos o servidores (por ejemplo, a través de colas de mensajes o gRPC), aún necesitarás serializar y deserializar explícitamente los datos del contexto.
• Fugas de memoria: El uso incorrecto de AsyncLocalStorage puede llevar potencialmente a fugas de memoria si los datos del contexto no se limpian adecuadamente. Asegúrate de usar asyncLocalStorage.run() correctamente y evita almacenar grandes cantidades de datos en AsyncLocalStorage.
• Complejidad: Aunque AsyncLocalStorage simplifica la propagación del contexto, también puede añadir complejidad a tu código si no se usa con cuidado. Asegúrate de que tu equipo entienda cómo funciona y siga las mejores prácticas.
• No es un reemplazo de variables globales: AsyncLocalStorage *no* es un reemplazo para las variables globales. Está diseñado específicamente para propagar el contexto dentro de una sola solicitud o transacción. Su uso excesivo puede llevar a un código fuertemente acoplado y dificultar las pruebas.

Mejores prácticas para usar AsyncLocalStorage

Para usar AsyncLocalStorage de manera efectiva, considera las siguientes mejores prácticas:

• Usa middleware: Utiliza middleware para inicializar AsyncLocalStorage y almacenar los datos del contexto al comienzo de cada solicitud.
• Almacena datos mínimos: Almacena solo los datos de contexto esenciales en AsyncLocalStorage para minimizar la sobrecarga de memoria. Evita almacenar objetos grandes o información sensible.
• Evita el acceso directo: Encapsula el acceso a AsyncLocalStorage detrás de APIs bien definidas para evitar el acoplamiento fuerte y mejorar la mantenibilidad del código. Crea funciones o clases auxiliares para gestionar los datos del contexto.
• Considera el manejo de errores: Implementa un manejo de errores para gestionar elegantemente los casos en los que AsyncLocalStorage no se inicializa correctamente.
• Prueba exhaustivamente: Escribe pruebas unitarias y de integración para asegurar que la propagación del contexto funciona como se espera.
• Documenta el uso: Documenta claramente cómo se está utilizando AsyncLocalStorage en tu aplicación para ayudar a otros desarrolladores a entender el mecanismo de propagación del contexto.

Integración con OpenTelemetry

OpenTelemetry es un marco de observabilidad de código abierto que proporciona APIs, SDKs y herramientas para recopilar y exportar datos de telemetría (por ejemplo, trazas, métricas, registros). AsyncLocalStorage puede integrarse sin problemas con OpenTelemetry para propagar automáticamente el contexto de la traza a través de operaciones asíncronas.

OpenTelemetry depende en gran medida de la propagación de contexto para correlacionar trazas entre diferentes servicios. Al usar AsyncLocalStorage, puedes asegurar que el contexto de la traza se propaga correctamente dentro de tu aplicación Node.js, permitiéndote construir un sistema de rastreo distribuido completo.

Muchos SDKs de OpenTelemetry utilizan automáticamente AsyncLocalStorage (o cls-hooked si AsyncLocalStorage no está disponible) para la propagación del contexto. Consulta la documentación del SDK de OpenTelemetry que hayas elegido para obtener detalles específicos.

Conclusión

AsyncLocalStorage es una herramienta valiosa para gestionar la propagación de contexto asíncrono en aplicaciones de JavaScript del lado del servidor. Al usarlo para el rastreo de solicitudes, autenticación, registro y otros casos de uso, puedes construir aplicaciones más robustas, observables y mantenibles. Aunque existen alternativas como cls-hooked y Async Hooks, AsyncLocalStorage es generalmente la opción preferida debido a su naturaleza incorporada, rendimiento y facilidad de uso. Recuerda seguir las mejores prácticas y ser consciente de sus limitaciones para aprovechar eficazmente sus capacidades. La capacidad de rastrear solicitudes y correlacionar eventos a través de operaciones asíncronas es crucial para construir sistemas escalables y confiables, especialmente en arquitecturas de microservicios y entornos distribuidos complejos. Usar AsyncLocalStorage ayuda a alcanzar este objetivo, lo que finalmente conduce a una mejor depuración, monitoreo del rendimiento y salud general de la aplicación.