Observabilidad con diagnostics_channel y AsyncLocalStorage

Así que hablemos de la observabilidad con Diagnostics Channel y el 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.

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

Así que los canales se crean en el nivel superior de tu archivo JavaScript llamando a la función channel y proporcionando un nombre para tu 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 el nombre de tu módulo generalmente debería incluirse en el nombre para evitar colisiones con canales de otras cosas. Una vez que tienes el objeto del canal, puedes comenzar a publicar en él. Esto es como 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 controlador cada vez por nombre cada vez que ocurre un evento, y hacer una llamada de publicación lo más cercana posible a cero costo cuando no hay oyentes.

Así que cada canal de diagnóstico debe seguir una convención de tener una estructura de objeto única por canal, y si tienes conjuntos de datos con formas diferentes para comunicar, es probable que esos deban ser canales separados. Así que al menos documenta los nombres y formas de tus canales. En cualquier lugar de la aplicación puedes llamar al canal nuevamente con el mismo nombre para adquirir el mismo canal y luego suscribirte a él. El orden de las llamadas al canal no importa. Cualquier lugar que lo llame primero creará el canal, y cada llamada subsiguiente lo recuperará. Incluso puedes suscribirte a canales para módulos que nunca se cargan y, por lo tanto, nunca tienen eventos publicados. Esto permite una completa desvinculación del código, permitiendo cosas como productos de trazado para observar pasivamente el comportamiento de tu módulo sin necesidad de ninguna conexión explícita entre módulos.

Así que veamos un ejemplo. Comenzamos definiendo nuestro canal nombrado en la parte superior del archivo. Luego escribimos nuestra función, sobre la cual queremos transmitir algunos datos. Típicamente cuando se llama, como cuando completa su set immediate interno, y llama a su callback, transmitirá los datos al canal con la función publish. Esto podría ser útil para todo tipo de cosas. Por ejemplo, podrías querer capturar métricas de cuántas veces hizo una cosa lo que se suponía que debía hacer. Incluso podría capturarse con el tiempo de finalización para graficar la actividad a lo largo del tiempo. Nada de esto necesita ser específicamente soportado por DoA Thing ya que el suscriptor puede decidir por sí mismo qué hacer con el mensaje o si quiere capturar alguna información de tiempo. Publish no tiene efecto a menos que haya suscriptores. No tiene costo a menos que haya suscriptores. A veces, construir el mensaje en sí puede ser costoso si la cosa se ejecutaría muy frecuentemente, por lo que se puede usar el has subscribers para omitir la construcción del mensaje por completo en situaciones críticas de rendimiento.

Entonces, ¿qué es el almacenamiento local asíncrono? Es como el ámbito léxico, pero siguiendo la ruta de llamada en lugar del ámbito de definición. El ámbito léxico nos permite recuperar datos del ámbito fuera de la función en sí. Lo estamos haciendo aquí cuando a llama a b, sin embargo, definimos thing en un ámbito interno, no hay forma de alcanzarlo en b. Lo obvio en este caso particular es simplemente pasarlo como un parámetro a b. Nada es accesible dentro de b. Pero, ¿qué pasa con situaciones más complicadas, como cuando no controlamos los pasos intermedios entre donde hemos definido la variable y donde queremos acceder a la variable aquí obtenemos b de algún otro módulo y toma un event emitter para activar un evento. No hay forma de pasar thing a través de su interfaz, así que ¿puedes averiguar cómo obtener thing en ese manejador de eventos de something? Tal vez puedas meterlo en global o podrías adjuntarlo al objeto emitter. ¿Qué pasa con la concurrencia? En cualquier caso, podría ser cambiado al valor incorrecto si otra llamada ocurre antes de que el evento sea emitido.

Esto significa que no importa cuánta complejidad haya entre los dos puntos siempre que se pueda dibujar un camino de llamada, callback o continuación entre los dos, el valor debería estar disponible. Para comenzar a pasar el valor, llamas al método run en el store y llamará a la función dada con ese valor como el estado actual del store hasta que la función termine y cualquier actividad asíncrona desencadenada dentro de ese ámbito también contendrá ese valor y luego para recuperar el valor del store puedes llamar al método get store más tarde.

Así que aquí tenemos un módulo para servir archivos estáticos, por lo que toma la carpeta de la cual servir función análoga, así que nota que devuelve una función de manejador de solicitudes para ser llamada más tarde por lo que está diseñado para ser llamado en el nivel superior fuera de la solicitud para producir el manejador de modo que no haya nada que pasar a través de ningún tipo de identidad de solicitud o de alguna manera cambiarlo para diferenciar solicitudes concurrentes. Así que sería muy difícil identificar en el registro qué par de mensajes de carga corresponde a qué mensaje de descarga si la ruta es la misma. Así que 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 estampar el ID de la solicitud en cada mensaje para que podamos correlacionar la solicitud exacta con cada mensaje de registro.

Así que ahora pongamos los dos juntos. Esta siguiente parte es un poco densa, pero este es un enfoque manual de nivel inferior que se está simplificando y llegaré a eso en un momento. Rastrear una sola acción puede expresarse con cinco eventos. Cuando la llamada comienza y termina, un equivalente inicio y fin asíncrono alrededor de callbacks y un evento para errores. El prefijo de rastreo y los sufijos de nombre de evento que puedes ver en los nombres son importantes. La parte del medio puede ser lo que quieras, como se mencionó anteriormente, es una buena idea incluir el nombre de tu módulo y el nombre del canal, por lo que module.function es un patrón de nomenclatura razonable, pero puedes seguir cualquier patrón de nomenclatura que te guste en la parte del medio siempre que seas consistente y lo documentes claramente. A cada uno de estos eventos se le da un canal separado, lo que permite escuchar selectivamente solo los eventos que son relevantes para el caso de uso particular. Y todos los eventos dentro de una sola acción comparten un único objeto de mensaje para permitir compartir datos entre los manejadores de eventos, por lo que el evento de fin recibirá el mismo objeto de mensaje que el evento de inicio si ambos provienen de la misma llamada rastreada. Si ocurre un error, se añadirá una propiedad de error al mensaje y se publicará el mensaje en el canal de error. Y también se añade una propiedad de resultado al fin síncrono o inicio asíncrono. Tendrá una propiedad de resultado. Y así, rastrear código asíncrono o rastrear código síncrono, los eventos de inicio y fin proporcionan un ámbito en el cual cualquier actividad síncrona o asíncrona se atribuirá al mensaje dado. En el caso de rastreo síncrono, no necesita asociar actividad asíncrona, pero proporcionará un objeto de mensaje compartido, lo que facilita correlacionar los eventos de una sola acción rastreable. Si la función de rastreo lanza un error, se añadirá 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 fin. Así que rastrear callbacks es lo mismo que con el rastreo síncrono. El rastreo de callbacks tiene un evento de inicio y fin alrededor de la llamada síncrona y captura errores lanzados. Pero además, los errores de callback también se capturan con eventos de error. Y la ejecución de callbacks está delimitada por los eventos de inicio y fin asíncronos. Esto es útil para restaurar el ámbito de span con almacenamiento local asíncrono si es necesario. Así que al igual que con el rastreo de callbacks, todo el código de rastreo síncrono se aplica igual. Las proyecciones de promesas se capturan y publican en el canal de error. Y el inicio asíncrono marca la finalización de la tarea asíncrona. Para mantener la consistencia con los callbacks, el fin asíncrono también se publica, aunque es semánticamente idéntico al inicio asíncrono en este caso.

Se activa inmediatamente. Debido a la naturaleza infinitamente encadenable de las promises, no hay un punto final distinto para promise, por lo que el async end se activa inmediatamente. Esto tiene sentido de todos modos, ya que las promises están destinadas a modelar un gráfico asíncrono, resolviendo y fusionándose de nuevo, como se expresa con async await. No habría nada que descienda internamente como lo hacen los callbacks, por lo que el gráfico se habría fusionado de nuevo con el código en espera.

Así que almacenar traces, ahora que estamos publicando traces en tracing channels, 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 fin lógicos desde la perspectiva del tracer, y captura cualquier metadato que necesite para identificar qué estaba haciendo la aplicación que produjo esto Así que, por ejemplo, un span para una solicitud HTTP probablemente contenga la URL del método. Aquí simplemente estamos pasando el mensaje tal cual. Pero de manera realista, un tracer haría algún procesamiento adicional.

El objeto span se almacena luego en async local storage usando enter with para estar disponible en la actividad asíncrona descendente como el parent binding mostrado en el evento start y restaurado en el evento end. Usar este método enter with no es realmente recomendado, pero así es como tenemos que hacer las cosas por el momento. Vienen cosas mejores, de las que hablaré en un momento. Pero entre los eventos async start y end, marcando el ámbito del callback, el span almacenado en el mensaje puede ser restaurado como el span actual. Esto no sería realmente necesario ya que async local storage está destinado a manejar esto, pero puede ser útil. Hay casos donde puede ocurrir pérdida de contexto, por lo que esto puede permitir restaurar manualmente el contexto si es necesario. Los tracers generalmente tendrán un marcador de end para cuando el span termine, pero varía cuándo sucederá eso. Algunos tracers considerarán, una vez que se complete el procesamiento de la tarea asíncrona en sí, entonces lo marcarán como hecho, pero algunos se considerarán a sí mismos como propietarios de su callback, y por lo tanto, cualquier cosa que suceda dentro del callback y descienda de eso también es propiedad, por lo que podría activar el evento end en el async end o el async start, o incluso podría pasarlo a través de todo un gráfico y no completar el span hasta que se complete todo el árbol de spans.

Un span es un contenedor para almacenar los datos sobre la ejecución actual junto con IDs para formar un gráfico. Típicamente, 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 el enlace de correlación. Cuando se activa el final, el span se informa al tracer. Como dije antes, dependiendo de la implementación del tracer, esto puede agregarse a un objeto de trace localmente y enviarse cuando se complete la solicitud, o puede transmitir los spans individuales inmediatamente. Depende del implementador.