Observabilidad con diagnostics_channel y AsyncLocalStorage

Entonces hablemos de observabilidad con Diagnostics Channel y almacenamiento local asíncrono. Hola a todos. Soy Steven. He estado involucrado en el núcleo de Node.js en un grupo de trabajo de diagnóstico durante muchos años. Trabajo en Datadog construyendo herramientas de diagnóstico y mis pronombres son él-él.

Primero que nada, ¿qué es Diagnostics Channel? Diagnostics Channel es un canal de eventos global de alto rendimiento para transmitir de manera pasiva datos sobre la ejecución actual. Es muy parecido a un emisor de eventos, pero está diseñado específicamente para ser lo más económico posible cuando no se está escuchando activamente. La idea es que los usuarios se sientan cómodos transmitiendo muchas cosas sin preocuparse por el costo, si la mayoría de las veces no se va a observar.

Los canales se crean en el nivel superior de su archivo JavaScript llamando a la función del canal y proporcionando un nombre para su canal. Comparten un espacio de nombres global para permitir adquirir el mismo canal en cualquier lugar de la aplicación sin necesidad de compartir explícitamente el objeto del canal, y generalmente se debe incluir el nombre de su módulo en el nombre para evitar colisiones con canales de otras cosas. Una vez que tenga el objeto del canal, puede comenzar a publicar en él. Esto es similar a la función emit en un emisor de eventos, pero al crear objetos de canal con anticipación permite varias optimizaciones, como evitar buscar el identificador por nombre cada vez que ocurre un evento, y hacer una llamada de publicación lo más económica posible cuando no hay oyentes.

Cada canal de diagnóstico debe seguir una convención de tener una estructura de objeto única por canal, y si tiene conjuntos de datos con formas diferentes para comunicarse, es probable que esos deberían ser canales separados. Al menos documente los nombres y formas de sus canales. En cualquier lugar de la aplicación, puede llamar al canal nuevamente con el mismo nombre para adquirir el mismo canal y luego suscribirse a él. El orden de las llamadas al canal no importa. El lugar que lo llame primero creará el canal y cada llamada posterior lo recuperará. Incluso puede suscribirse a canales de módulos que nunca se cargan y, por lo tanto, nunca tienen eventos publicados. Esto permite el desacoplamiento completo del código, lo que permite que productos de trazado observen de manera pasiva el comportamiento de su módulo sin necesidad de ninguna conexión explícita entre módulos.

Veamos un ejemplo. Comenzamos definiendo nuestro canal con nombre en la parte superior del archivo. Luego escribimos nuestra función, que queremos transmitir algunos datos sobre. Normalmente, cuando se llama, como cuando completa su setImmediate interno y llama a su devolución de llamada, transmitirá los datos al canal con la función de publicación. Esto podría ser útil para muchas cosas. Por ejemplo, es posible que desee capturar métricas de cuántas veces hizo una cosa lo que se suponía que debía hacer. Incluso se podría capturar con el tiempo de finalización para trazar la actividad a lo largo del tiempo. Ninguno de estos necesita ser específicamente compatible con DoA Thing, ya que el suscriptor puede decidir por sí mismo qué hacer con el mensaje o si desea capturar alguna información de tiempo. La publicación no tiene ningún efecto a menos que haya suscriptores. No tiene ningún costo a menos que haya suscriptores. A veces, la construcción del mensaje en sí puede ser costosa si la cosa se ejecuta muy frecuentemente, por lo que el hecho de que haya suscriptores se puede usar para omitir completamente la construcción del mensaje en situaciones críticas de rendimiento.

Esto significa que no importa cuánta complejidad haya entre los dos puntos, siempre y cuando se pueda trazar una ruta de llamada, devolución de llamada o continuación entre los dos, el valor debería estar disponible. Para comenzar a pasar el valor, llame al método run en la tienda y llamará a la función dada con ese valor como estado actual de la tienda hasta que la función finalice. Cualquier actividad asíncrona desencadenada dentro de ese alcance también contendrá ese valor. Luego, para recuperar el valor de la tienda, puede llamar al método get store más tarde.

Aquí tenemos un módulo para servir archivos estáticos, por lo que toma la carpeta para servir de manera análoga a una función. Observa que devuelve una función controladora de solicitudes para ser llamada más tarde. Está diseñado para ser llamado en el nivel superior fuera de la solicitud para producir el controlador, por lo que no hay nada que pasar a través de una identidad de solicitud o de ninguna manera cambiarlo para diferenciar las solicitudes concurrentes. Sería muy difícil identificar en el registro qué mensaje de carga se corresponde con qué mensaje de descarga si la ruta es la misma. Con el almacenamiento local asíncrono, podemos almacenar un ID que podemos recuperar en la función de registro que proporcionamos, aunque la función de registro esté definida fuera de la solicitud. Ahora podemos marcar el ID de la solicitud en cada mensaje para poder correlacionar la solicitud exacta con cada mensaje de registro.

Ahora pongamos las dos cosas juntas. Esta próxima parte es un poco densa, pero es un enfoque manual de nivel inferior que se está simplificando y lo explicaré en un momento. El rastreo de una acción única se puede expresar con cinco eventos. Cuando comienza y termina la llamada, hay eventos de inicio y finalización asíncronos equivalentes alrededor de las devoluciones de llamada y un evento para errores. Los prefijos de rastreo y los sufijos de los nombres de eventos que se pueden ver en los nombres son importantes. La parte central puede ser cualquier cosa que desee, como se mencionó anteriormente, es una buena idea incluir el nombre de su módulo y el nombre del canal, por lo que `módulo.función` es un patrón de nomenclatura razonable, pero puede seguir cualquier patrón de nomenclatura que desee, siempre y cuando sea consistente y esté documentado claramente. Cada uno de estos eventos se asigna a un canal separado, lo que permite escuchar selectivamente solo los eventos relevantes para el caso de uso particular. Y todos los eventos dentro de una sola acción comparten un solo objeto de mensaje para permitir compartir datos entre los controladores de eventos, por lo que el evento de finalización recibirá el mismo objeto de mensaje que el evento de inicio si ambos provienen de la misma llamada rastreada. Si se produce un error, se agregará una propiedad de error al mensaje y se publicará en el canal de errores. Y también se agrega una propiedad de resultado a la finalización sincrónica o al inicio asíncrono. El rastreo de código asíncrono o sincrónico proporciona un alcance en el que cualquier actividad sincrónica o asíncrona se atribuirá al mensaje dado. En el caso del rastreo sincrónico, no es necesario asociar la actividad asíncrona, pero proporcionará un objeto de mensaje compartido, lo que facilita la correlación de los eventos de una sola acción rastreable. Si la función de rastreo genera un error, se agregará al objeto de mensaje y se publicará un evento de error. Y el valor de retorno también se almacena en el objeto de mensaje y se puede ver en el evento de finalización.

Aunque es semánticamente idéntico al inicio asíncrono en este caso. Se activa inmediatamente. Debido a la naturaleza encadenable infinita de las promesas, no hay un punto final distinto para la promesa, por lo que el final asíncrono se activa de inmediato. Esto tiene sentido de todos modos, ya que las promesas están destinadas a modelar un gráfico asíncrono, resolviendo y fusionando nuevamente, como se expresa con async await. No habría nada que descienda internamente como lo hacen las devoluciones de llamada, por lo que el gráfico se habría fusionado de nuevo en el código en espera. Entonces, al almacenar trazas, ahora que estamos publicando trazas en canales de rastreo, necesitamos transformar esos datos en algo que represente de manera significativa esa colección de eventos del ciclo de vida. Esto se llama típicamente un span, que contiene los metadatos que marcan el inicio y el final lógicos desde la perspectiva del rastreador, y captura cualquier metadato que necesite para identificar lo que la aplicación estaba haciendo que produjo esto. Por ejemplo, un span para una solicitud HTTP probablemente contendría el método y la URL. Aquí simplemente estamos pasando el mensaje tal cual. Pero en realidad, un rastreador haría algún procesamiento adicional. El objeto span se almacena en el almacenamiento local asíncrono utilizando enter with para que esté disponible en la actividad asíncrona descendente como el enlace principal mostrado en el evento de inicio y se restaure en el evento de finalización. El uso de este método enter with no es realmente recomendado, pero así es como tenemos que hacer las cosas en este momento. Vienen cosas mejores, de las que hablaré en un momento. Pero entre los eventos de inicio y finalización asíncronos, marcando el ámbito de la devolución de llamada, el span almacenado en el mensaje se puede restaurar como el span actual. Esto no sería realmente necesario ya que el almacenamiento local asíncrono está destinado a manejar esto, pero puede ser útil. Hay casos en los que se puede perder el contexto, por lo que esto puede permitir restaurar manualmente el contexto si es necesario. Los rastreadores generalmente tienen un marcador de finalización para cuando el span finaliza, pero varía cuándo sucede eso. Algunos rastreadores considerarán, una vez que se haya completado el procesamiento de la tarea asíncrona en sí, entonces lo marcarán como finalizado, pero algunos considerarán que son propietarios de su devolución de llamada y, por lo tanto, cualquier cosa que ocurra dentro de la devolución de llamada y que descienda desde ella también es propiedad, por lo que podría activar el evento de finalización en el final asíncrono o el inicio asíncrono, o incluso podría pasarlo a través de todo un gráfico y no completar el span hasta que se completen todos los árboles de spans.

El span se mantiene hasta que se completen todos los árboles de spans. Un span es un contenedor para almacenar los datos sobre la ejecución actual junto con IDs para formar un gráfico. Normalmente, los spans tienen su propio ID único y luego un ID único separado para su gráfico para correlacionarlos más tarde. Mantener un objeto span padre directamente puede causar fugas de memoria y complicar la transmisión de eventos, por lo que generalmente se prefiere usar IDs para la correlación. Cuando se activa el final, el span se informa al rastreador. Como dije antes, dependiendo de la implementación del rastreador, esto puede agregarse a un objeto de traza localmente y enviarse cuando se complete la solicitud, o puede transmitir los spans individuales de inmediato. Depende del implementador. Sin embargo, se está volviendo más fácil. Por lo tanto, administrar todos esos canales y garantizar un comportamiento correcto es complicado. Por lo tanto, hay una API de nivel superior que se encarga de eso internamente. Construye y expone los canales con los nombres correctos para ti, pero también proporciona varias funciones para envolver la funcionalidad de trazado en una interfaz mucho más amigable. Echemos un vistazo. Primero, tenemos TraceSync. Maneja automáticamente los eventos de inicio y error, y es bastante fácil de usar. Le das una función y la invocará de inmediato con los eventos de inicio y finalización, antes y después. También puedes pasarle un valor para 'this' y cualquier argumento que desees pasar, lo cual es útil para evitar cierres innecesarios, y también capturará y pasará el valor de retorno, lo que te permite reemplazar directamente una llamada de función existente por una envuelta en eventos de trazado. A continuación, tenemos TraceCallback, que, además de manejar los eventos de inicio, finalización y error, también activa automáticamente los eventos de inicio y finalización asíncronos alrededor de la devolución de llamada y captura los errores y resultados de la devolución de llamada, por lo que se debe proporcionar la posición de la devolución de llamada y puede ser indexada positivamente desde cero o negativamente desde el final de la lista de argumentos, pero el valor predeterminado es menos uno para seguir el patrón típico de devolución de llamada en Node.js. Al igual que con TraceSync, 'this' y la lista de argumentos se pasan como valores de retorno. Las API basadas en devoluciones de llamada generalmente no tienen un valor de retorno real. Y un canal de trazado para promesas, por último, tenemos TracePromise, al igual que TraceCallback, todos los eventos se manejan automáticamente. Las entradas y salidas se pasan de la misma manera que otras funciones de trazado. Y al igual que en el ejemplo manual mostrado anteriormente, el final asíncrono se publica inmediatamente después del inicio asíncrono, ya que no hay un final claro para la continuación de la promesa. Y luego, para vincular el canal de diagnóstico o estos nuevos canales de trazado al almacenamiento local asíncrono, también hay bindStore y runStores que vendrán pronto. El método runStores se utiliza para sugerir que las tiendas pueden establecer su estado a partir de los datos proporcionados durante la función proporcionada. Se utiliza en un canal con nombre de la misma manera que se publicaría y también publicaremos los datos de entrada en ese canal después de establecer el estado en cualquier tienda vinculada. Y el método bindStore se puede utilizar para aceptar esos datos sugeridos, transformándolos opcionalmente de alguna manera antes de establecerlos en el estado de la tienda dada durante la duración de la función proporcionada a runStores. Como en este ejemplo, la tienda de URL contendrá la URL que se pasa en ese objeto durante runStores. Por lo tanto, la combinación de los dos permite coordinar la decisión de almacenar datos de contexto en una tienda en particular o en cualquier número de tiendas a través del canal de diagnóstico en lugar de tener que pasar tiendas a través de editores de eventos. Otra forma de abordar esta API sería hacer que tu módulo tenga una función a la que debas llamar para pasar una tienda y eso solo requiere un esfuerzo adicional y es complicado si deseas tener multiinquilinato y todas esas cosas. Esto te lo proporciona de forma gratuita. Y todas las funciones de trazado en un canal de trazado también envuelven la ejecución de sus funciones dadas con runStores, lo que permite almacenar automáticamente un objeto span para cada traza. Esto es útil porque si bien los canales de trazado en objetos de contexto están disponibles en el código directo, es posible que no estén disponibles en el código al que la función trazada llama. Por lo tanto, puede ser útil utilizar el almacenamiento local asíncrono para propagar los objetos de contexto o un span producido a partir de él a cualquier ejecución anidada. Sí, así es como se ve el futuro del trazado de aplicaciones Node.js. Gracias por escuchar y por favor, habla conmigo si tienes preguntas sobre cómo agregar canales de trazado aquí en los módulos.