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". Aquí significan lo mismo.
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 que se va a 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 los 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 desee registrar. En este caso, el método AppStarted define un único evento llamado "AppStarted". Cada vez que el código invoque al 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 que se ha registrado. El nombre del evento será idéntico al nombre del método, "AppStarted" en este caso.
- Identificador del evento: identificador numérico que identifica el tipo de evento registrado. Esto sirve como un rol similar al del nombre, pero puede ayudar en el procesamiento rápido automatizado de registros. El evento AppStarted tiene un identificador con valor 1, especificado en EventAttribute.
- Nombre de origen: el nombre del elemento 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 llama "Demo", especificado en el elemento EventSourceAttribute en la definición de clase. El nombre de origen también se conoce normalmente como nombre de proveedor.
- Argumentos: todos los valores de argumento del 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 describa 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 se generará ningún archivo de seguimiento de manera 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). También se pueden crear suscriptores personalizados mediante la API System.Diagnostics.Tracing.EventListener.
Esta demostración 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 seguimientos y un formato de seguimiento compacto portátil (archivos *.nettrace). dotnet-trace es una herramienta de la 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 da por supuesto que la aplicación se llama 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 ha ejecutado EventSourceDemo.exe con todos los eventos del elemento 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 timestamp muestra que el evento se produjo 27 ms después de iniciar 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.
