Introducción a EventSource
Este artículo se aplica a: ✔️ .NET Core 3.1 y versiones posteriores ✔️ .NET Framework 4.5 y versiones posteriores
En este tutorial se muestra cómo registrar un nuevo evento con System.Diagnostics.Tracing.EventSource, recopilar eventos en un archivo de seguimiento, ver el seguimiento y comprender los conceptos básicos de EventSource.
Nota
Muchas tecnologías que se integran con EventSource usan los términos "seguimientos" y "trazas" en lugar de "registro" y "registros". El significado es el mismo aquí.
Registro de un evento
El objetivo de EventSource es permitir que los desarrolladores de .NET escriban código como este para registrar un evento:
DemoEventSource.Log.AppStarted("Hello World!", 12);
Esta línea de código tiene un objeto de registro (DemoEventSource.Log), un método que representa el evento para registrar (AppStarted) y, opcionalmente, algunos parámetros de evento fuertemente tipados (HelloWorld! y 12). No hay niveles de detalle, identificadores de eventos, plantillas de mensaje ni nada más que no necesite estar en el sitio de llamada. Toda esta otra información sobre eventos se escribe definiendo una nueva clase derivada de System.Diagnostics.Tracing.EventSource.
Este es un ejemplo mínimo completo:
using System.Diagnostics.Tracing;
namespace EventSourceDemo
{
public static class Program
{
public static void Main(string[] args)
{
DemoEventSource.Log.AppStarted("Hello World!", 12);
}
}
[EventSource(Name = "Demo")]
class DemoEventSource : EventSource
{
public static DemoEventSource Log { get; } = new DemoEventSource();
[Event(1)]
public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
}
}
La clase DemoEventSource declara un método para cada tipo de evento que desea registrar. En este caso, el método AppStarted define un único evento denominado "AppStarted" (). Cada vez que el código invoca el método AppStarted, se registrará otro evento AppStarted en el seguimiento si el evento está habilitado. Estos son algunos de los datos que se pueden capturar con cada evento:
- Nombre del evento: nombre que identifica el tipo de evento registrado. El nombre del evento será idéntico al nombre del método, "AppStarted" en este caso.
- Id. de evento: identificador numérico que identifica el tipo de evento registrado. Esto cumple un papel similar al nombre, pero puede ayudar a procesar registros de manera automatizada rápidamente. El evento AppStarted tiene un identificador de 1, especificado en el EventAttribute.
- Nombre de origen: el nombre del EventSource que contiene el evento. Se usa como un espacio de nombres para eventos. Los nombres de evento y los identificadores solo deben ser únicos dentro del ámbito de su origen. Aquí el origen se denomina "Demo", especificado en el EventSourceAttribute en la definición de clase. El nombre de origen también se conoce normalmente como nombre de proveedor.
- Argumentos: todos los valores del argumento de método se serializan.
- Otra información: los eventos también pueden contener marcas de tiempo, identificadores de subproceso, identificadores de procesador, identificadores de actividad, seguimientos de pila y metadatos de eventos como plantillas de mensaje, niveles de detalle y palabras clave.
Para obtener más información y conocer los procedimientos recomendados sobre la creación de eventos, consulte Instrumentación del código para crear eventos de EventSource.
Recopilación y visualización de un archivo de seguimiento
No hay ninguna configuración necesaria en el código que describe en qué eventos se deben habilitar, dónde se deben enviar los datos registrados o en qué formato se deben almacenar los datos. Si ejecuta la aplicación ahora, no generará ningún archivo de seguimiento de forma predeterminada. EventSource usa el patrón publicación-suscripción, que requiere que los suscriptores indiquen los eventos que se deben habilitar y que se controle toda la serialización de los eventos suscritos. EventSource tiene integraciones para suscribirse desde el Seguimiento de eventos para Windows (ETW) y EventPipe (solo .NET Core). Los suscriptores personalizados también se pueden crear mediante la API de System.Diagnostics.Tracing.EventListener.
En esta demostración se muestra un ejemplo de EventPipe para aplicaciones de .NET Core. Para obtener más información sobre otras opciones, consulte Recopilación y visualización de seguimientos de EventSource. EventPipe es una tecnología de seguimiento abierta y multiplataforma integrada en el entorno de ejecución de .NET Core para proporcionar a los desarrolladores de .NET herramientas de recopilación de seguimiento y un formato de seguimiento compacto portátil (archivos*.nettrace). dotnet-trace es una herramienta de línea de comandos que recopila seguimientos de EventPipe.
- Descargue e instale dotnet-trace.
- Compile la aplicación de consola anterior. En esta demostración se supone que la aplicación se denomina EventSourceDemo.exe y está en el directorio actual. En la línea de comandos, ejecute:
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe
Esto debería mostrar una salida similar a la siguiente:
Provider Name Keywords Level Enabled By
Demo 0xFFFFFFFFFFFFFFFF Verbose(5) --providers
Launching: EventSourceDemo.exe
Process : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
Output File : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220303_001619.nettrace
[00:00:00:00] Recording trace 0.00 (B)
Press <Enter> or <Ctrl+C> to exit...
Trace completed.
Este comando ejecutó EventSourceDemo.exe con todos los eventos del eventSource "Demo" habilitado y genera el archivo de seguimiento EventSourceDemo.exe_20220303_001619.nettrace.
Al abrir el archivo en Visual Studio se muestran los eventos registrados.
En la vista de lista, puede ver que el primer evento es el evento Demo/AppStarted. La columna de texto tiene los argumentos guardados, la columna de marca temporal muestra el evento 27 ms después de que se inició el registro y, a la derecha, puede ver la pila de llamadas. Los demás eventos se habilitan automáticamente en cada seguimiento recopilado por dotnet-trace, aunque se pueden omitir y filtrar desde la vista en la interfaz de usuario si distraen. Estos eventos adicionales capturan cierta información sobre el proceso y el código con compilación JIT, lo que permite a Visual Studio reconstruir los seguimientos de la pila de eventos.
