Active Support es una parte del núcleo de Rails que proporciona extensiones del lenguaje Ruby, utilidades y otras cosas. Una de las cosas que incluye es una API de instrumentación que se puede usar dentro de una aplicación para medir ciertas acciones que ocurren dentro del código Ruby, como las que están dentro de una aplicación Rails o el propio framework. Sin embargo, no está limitado a Rails. Se puede usar de manera independiente en otros scripts Ruby si se desea.
En esta guía, aprenderás cómo usar la API de instrumentación de Active Support para medir eventos dentro de Rails y otro código Ruby.
Después de leer esta guía, sabrás:
Qué puede proporcionar la instrumentación.
Cómo agregar un suscriptor a un hook.
Los hooks dentro del framework Rails para instrumentación.
Cómo construir una implementación de instrumentación personalizada.
La API de instrumentación proporcionada por Active Support permite a los desarrolladores proporcionar hooks a los que otros desarrolladores pueden engancharse. Hay varios de estos dentro del framework Rails. Con esta API, los desarrolladores pueden optar por ser notificados cuando ocurren ciertos eventos dentro de su aplicación u otra pieza de código Ruby.
Por ejemplo, hay un hook proporcionado dentro de Active Record que se llama cada vez que Active Record utiliza una consulta SQL en una base de datos. Este hook podría suscribirse y usarse para rastrear el número de consultas durante una cierta acción. Hay otro hook alrededor del procesamiento de una acción de un controlador. Esto podría usarse, por ejemplo, para rastrear cuánto tiempo ha tomado una acción específica.
Incluso puedes crear tus propios eventos dentro de tu aplicación a los que luego puedes suscribirte.
Usa ActiveSupport::Notifications.subscribe con un bloque para escuchar cualquier notificación. Dependiendo de la cantidad de argumentos que tome el bloque, recibirás diferentes datos.
La primera forma de suscribirse a un evento es usar un bloque con un solo argumento. El argumento será una instancia de ActiveSupport::Notifications::Event.
Si te preocupa la precisión de started y finished para calcular un tiempo transcurrido preciso, entonces usa ActiveSupport::Notifications.monotonic_subscribe. El bloque dado recibiría los mismos argumentos que arriba, pero started y finished tendrán valores con un tiempo monotónico preciso en lugar de tiempo de reloj de pared.
También puedes suscribirte a eventos que coincidan con una expresión regular. Esto te permite suscribirte a múltiples eventos a la vez. Aquí tienes cómo suscribirte a todo desde ActionController:
ActiveSupport::Notifications.subscribe(/action_controller/)do|event|# inspecciona todos los eventos de ActionControllerend
Dentro del framework Ruby on Rails, hay una serie de hooks proporcionados para eventos comunes. Estos eventos y sus cargas útiles se detallan a continuación.
Este evento se emite cuando se ha iniciado una transacción.
Clave
Valor
:transaction
Objeto de transacción
:connection
Objeto de conexión
Por favor, ten en cuenta que Active Record no crea la transacción real de la base de datos hasta que es necesario:
ActiveRecord::Base.transactiondo# Estamos dentro del bloque, pero no se ha activado ningún evento todavía.# La siguiente línea hace que Active Record inicie la transacción.User.count# Evento activado aquí.end
Recuerda que las llamadas anidadas ordinarias no crean nuevas transacciones:
ActiveRecord::Base.transactiondo|t1|User.count# Dispara un evento para t1.ActiveRecord::Base.transactiondo|t2|# La siguiente línea no dispara un evento para t2, porque la única# transacción real de base de datos en este ejemplo es t1.User.first.touchendend
Sin embargo, si se pasa requires_new: true, también obtienes un evento para la transacción anidada. Esto podría ser un punto de guardado bajo el capó:
ActiveRecord::Base.transactiondo|t1|User.count# Dispara un evento para t1.ActiveRecord::Base.transaction(requires_new: true)do|t2|User.first.touch# Dispara un evento para t2.endend
Este evento se emite cuando una transacción de base de datos termina. El estado de la transacción se puede encontrar en la clave :outcome.
Clave
Valor
:transaction
Objeto de transacción
:outcome
:commit, :rollback, :restart, o :incomplete
:connection
Objeto de conexión
En la práctica, no puedes hacer mucho con el objeto de transacción, pero aún puede ser útil para rastrear la actividad de la base de datos. Por ejemplo, rastreando transaction.uuid.
Agregar tus propios eventos es fácil también. Active Support se encargará de
todo el trabajo pesado por ti. Simplemente llama a ActiveSupport::Notifications.instrument con un name, payload, y un bloque.
La notificación se enviará después de que el bloque regrese. Active Support generará los tiempos de inicio y fin,
y agregará el ID único del instrumentador. Todos los datos pasados a la llamada instrument harán
que lleguen a la carga útil.
Aquí tienes un ejemplo:
ActiveSupport::Notifications.instrument"my.custom.event",this: :datado# haz tus cosas personalizadas aquíend
También puedes llamar a instrument sin pasar un bloque. Esto te permite aprovechar la
infraestructura de instrumentación para otros usos de mensajería.
Deberías seguir las convenciones de Rails al definir tus propios eventos. El formato es: event.library.
Si tu aplicación está enviando Tweets, deberías crear un evento llamado tweet.twitter.
Comentarios
Se te anima a ayudar a mejorar la calidad de esta guía.
Por favor contribuye si ves algún error tipográfico o errores fácticos.
Para comenzar, puedes leer nuestra sección de contribuciones a la documentación.
También puedes encontrar contenido incompleto o cosas que no están actualizadas.
Por favor agrega cualquier documentación faltante para main. Asegúrate de revisar
Guías Edge primero para verificar
si los problemas ya están resueltos o no en la rama principal.
Revisa las Guías de Ruby on Rails
para estilo y convenciones.
Si por alguna razón detectas algo que corregir pero no puedes hacerlo tú mismo, por favor
abre un issue.
Y por último, pero no menos importante, cualquier tipo de discusión sobre la
documentación de Ruby on Rails es muy bienvenida en el Foro oficial de Ruby on Rails.