Compartir a través de

Recopilación y visualización de seguimientos de EventSource

  • Artículo

Este artículo se aplica a: ✔️.NET Core 3.1 y versiones posteriores ✔️ .NET Framework 4.5 y versiones posteriores

En la guía Getting Started (Introducción) se explica cómo crear un EventSource mínimo y recopilar eventos en un archivo de seguimiento. En este tutorial se muestra cómo diferentes herramientas pueden configurar qué eventos se recopilan en un seguimiento y, a continuación, ver los seguimientos.

Ejemplo de aplicación

Usará la siguiente aplicación de ejemplo que genera eventos para este tutorial. Compile una aplicación de consola de .NET que contenga el código siguiente:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
            DemoEventSource.Log.DebugMessage("Got here");
            DemoEventSource.Log.DebugMessage("finishing startup");
            DemoEventSource.Log.RequestStart(3);
            DemoEventSource.Log.RequestStop(3);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1, Keywords = Keywords.Startup)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
        [Event(2, Keywords = Keywords.Requests)]
        public void RequestStart(int requestId) => WriteEvent(2, requestId);
        [Event(3, Keywords = Keywords.Requests)]
        public void RequestStop(int requestId) => WriteEvent(3, requestId);
        [Event(4, Keywords = Keywords.Startup, Level = EventLevel.Verbose)]
        public void DebugMessage(string message) => WriteEvent(4, message);


        public class Keywords
        {
            public const EventKeywords Startup = (EventKeywords)0x0001;
            public const EventKeywords Requests = (EventKeywords)0x0002;
        }
    }
}

Configuración de los eventos que se van a recopilar

La mayoría de las herramientas de recopilación de eventos usan estas opciones de configuración para decidir qué eventos deben incluirse en un seguimiento:

  • Nombres de proveedor: se trata de una lista de uno o varios nombres EventSource. Solo se pueden incluir los eventos definidos en EventSources de esta lista. Para recopilar eventos de la clase DemoEventSource en la aplicación de ejemplo anterior, tendría que incluir el nombre de EventSource "Demo" en la lista de nombres de proveedor.
  • Nivel de detalle del evento: para cada proveedor, puede definir un nivel de detalle y los eventos con un nivel de detalle superior a ese nivel se excluirán del seguimiento. Si especificó que el proveedor "Demo" de la aplicación de ejemplo anterior debe recopilar en el nivel de detalle informativo, el evento DebugMessage se excluiría porque tiene un nivel superior. Especificar EventLevel LogAlways(0) es un caso especial que indica que se deben incluir eventos de cualquier nivel de detalle.
  • Palabras clave de evento: para cada proveedor puede definir un conjunto de palabras clave y solo se incluirán eventos etiquetados con al menos una de las palabras clave. En la aplicación de ejemplo anterior si especificó la palabra clave Startup, solo se incluirán los eventos AppStarted y DebugMessage. Si no se especifica ninguna palabra clave, se trata de un caso especial y significa que se deben incluir eventos con cualquier palabra clave.

Convenciones para describir la configuración del proveedor

Aunque cada herramienta determina su propia interfaz de usuario para establecer la configuración de seguimiento, hay una convención común que muchas herramientas usan al especificar la configuración como una cadena de texto. La lista de proveedores se especifica como una lista delimitada por punto y coma, y cada elemento de proveedor de la lista consta de nombre, palabras clave y nivel separados por dos puntos. Por ejemplo, "Demo:3:5" identifica el EventSource denominado "Demo" con la palabra clave bitmask 3 (el bit de Startup y el bit de Requests) y EventLevel 5, que es Verbose. Muchas herramientas también le permiten omitir el nivel y las palabras clave si no se desea ningún nivel o filtrado de palabras clave. Por ejemplo, "Demo::5" solo realiza el filtrado basado en el nivel, "Demo:3" solo realiza el filtrado basado en palabras clave y "Demo" no realiza ningún filtrado de palabras clave o nivel.

Visual Studio

El generador de perfiles de Visual Studio admite tanto la recopilación como la visualización de seguimientos. También puede ver los seguimientos recopilados de antemano por otras herramientas, como dotnet-trace.

Recopilación de un seguimiento

La mayoría de las herramientas de generación de perfiles de Visual Studio usan conjuntos predefinidos de eventos que sirven para un propósito determinado, como analizar el uso de CPU o las asignaciones. Para recopilar un seguimiento con eventos personalizados, usará la herramienta Visor de eventos.

  1. Para abrir el Generador de perfiles de rendimiento en Visual Studio, seleccione Alt+F2.

  2. Active la casilla Visor de eventos.

    Visor de eventos de Visual Studio

  3. Seleccione el icono de engranaje pequeño situado a la derecha del Visor de eventos para abrir la ventana de configuración.

    En la tabla siguiente Proveedores adicionales, agregue una fila para cada proveedor que desee configurar haciendo clic en la casilla Habilitado y, a continuación, escriba el nombre del proveedor, las palabras clave y el nivel. No es necesario escribir el GUID del proveedor; se calcula automáticamente.

    Configuración del Visor de eventos de Visual Studio

  4. Seleccione Aceptar para confirmar los valores de configuración.

  5. Seleccione Iniciar para empezar a ejecutar la aplicación y recopilar registros.

  6. Seleccione Detener recopilación o salga de la aplicación para detener la recopilación de registros y mostrar los datos recopilados.

Visualización de un seguimiento

Visual Studio puede ver los seguimientos que recopiló o puede ver los seguimientos recopilados en otras herramientas. Para ver los seguimientos de otras herramientas, use Archivo>Abrir y seleccione un archivo de seguimiento en el selector de archivos. El generador de perfiles de Visual Studio admite archivos .etl (formato estándar de ETW), archivos .nettrace (formato estándar de EventPipe) y archivos .diagsession (formato estándar de Visual Studio). Para obtener información sobre cómo trabajar con archivos de seguimiento en Visual Studio, consulte la documentación de Visual Studio.

Visor de eventos de Visual Studio, seguimiento ETW

Nota

Visual Studio recopila algunos eventos automáticamente de ETW o EventPipe, incluso si no estaban configurados explícitamente. Si ve eventos que no reconoce en la columna Nombre del proveedor o Nombre de evento y desea filtrarlos, use el icono de filtro a la derecha para seleccionar solo los eventos que desea ver.

PerfView

PerfView es una herramienta de rendimiento creada por el equipo de .NET que puede recopilar y ver seguimientos de ETW. También puede ver los archivos de seguimiento recopilados por otras herramientas en varios formatos. En este tutorial, recopilará un seguimiento ETW de la aplicación de demostración y, a continuación, examinará los eventos recopilados en el visor de eventos de PerfView.

Recopilación de un seguimiento

  1. Descargue PerfView desde la página de versiones. Este tutorial se realizó con PerfView versión 2.0.76, pero cualquier versión reciente debería funcionar.

  2. Abra PerfView.exe con permisos de administrador.

    Nota

    La recopilación de seguimiento de ETW siempre requiere permisos de administrador, pero si solo usa PerfView para ver un seguimiento preexistente, no se necesitan permisos especiales.

    Ventana principal de PerfView

  3. En el menú Collect (Recopilar), elija Run (Ejecutar). Se abrirá un nuevo cuadro de diálogo en el que escribirá la ruta de acceso a la aplicación de demostración.

    Cuadro de diálogo ejecutar de PerfView

  4. Para configurar qué eventos se recopilan, expanda Opciones avanzadas en la parte inferior del cuadro de diálogo. En el cuadro de texto Proveedores adicionales, escriba proveedores con el formato de texto convencional descrito anteriormente. En este caso, va a escribir "Demo:1:4", lo que significa bit de palabra clave 1 (eventos Startup) y detalle 4 (Informational).

    Configuración avanzada del cuadro de diálogo ejecutar de PerfView

  5. Para iniciar la aplicación y empezar a recopilar el seguimiento, seleccione el botón Ejecutar comando. Cuando se cierra la aplicación, el seguimiento PerfViewData.etl se guarda en el directorio actual.

Visualización de un seguimiento

  1. En el cuadro de texto desplegable de la ventana principal de la esquina superior izquierda, seleccione el directorio que contiene el archivo de seguimiento. A continuación, haga doble clic en el archivo de seguimiento en la vista de árbol siguiente.

    Ventana principal de PerfView: selección de un seguimiento

  2. Para abrir el visor de eventos, haga doble clic en el elemento Eventos que aparece en la vista de árbol debajo del archivo de seguimiento.

    Visor de eventos de PerfView

  3. Todos los tipos de eventos del seguimiento se muestran en la lista de la izquierda. Haga doble clic en un tipo de evento, como Demo\AppStarted, para mostrar todos los eventos de ese tipo en la tabla de la derecha.

    Visor de eventos de PerfView: eventos AppStarted

Saber más

Para obtener más información sobre el uso de PerfView, consulte los tutoriales de vídeo de PerfView.

dotnet-trace

dotnet-trace es una herramienta de línea de comandos multiplataforma que puede recopilar seguimientos de aplicaciones de .NET Core mediante el seguimiento EventPipe . No admite la visualización de datos de seguimiento, pero otras herramientas como PerfView o Visual Studio pueden ver los seguimientos que recopila. dotnet-trace también admite la conversión de sus seguimientos de formato .nettrace predeterminados en otros formatos, como Chromium o Speedscope.

Recopilación de un seguimiento

  1. Descargue e instale dotnet-trace.

  2. En la línea de comandos, ejecute el comando dotnet-trace collect:

    E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe

    Esto debería mostrar una salida similar a la siguiente:

    E:\temp\EventSourceDemo\bin\Debug\net6.0> dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe

Provider Name                           Keywords            Level               Enabled By
Demo                                    0x0000000000000001  Informational(4)    --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_20220317_021512.nettrace

[00:00:00:00]   Recording trace 0.00     (B)
Press <Enter> or <Ctrl+C> to exit...

Trace completed.

    dotnet-trace usa el formato de texto convencional para describir la configuración del proveedor en el argumento --providers. Para ver más opciones sobre cómo realizar seguimientos mediante dotnet-trace, consulte la documentación de dotnet-trace.

EventListener

System.Diagnostics.Tracing.EventListener es una API de .NET que se puede usar desde el proceso para recibir devoluciones de llamada para eventos generados por System.Diagnostics.Tracing.EventSource. Esta API se puede usar para crear herramientas de registro personalizadas o para analizar los eventos en la memoria sin serializarlos nunca.

Para usar EventListener, declare un tipo que deriva de EventListener, invoque EnableEvents para suscribirse a los eventos de cualquier EventSource de interés e invalide OnEventWritten, al que se llamará cada vez que haya un nuevo evento disponible. A menudo resulta útil invalidar OnEventSourceCreated para detectar qué objetos EventSource existen, pero esto no es necesario. A continuación se muestra una implementación de ejemplo de EventListener que imprime en la consola cuando se reciben mensajes:

  1. Agregue este código a la aplicación de demostración.

    class ConsoleWriterEventListener : EventListener
{
    protected override void OnEventSourceCreated(EventSource eventSource)
    {
        if(eventSource.Name == "Demo")
        {
            EnableEvents(eventSource, EventLevel.Informational);
        }
    }

    protected override void OnEventWritten(EventWrittenEventArgs eventData)
    {
        Console.WriteLine(eventData.TimeStamp + " " + eventData.EventName);
    }
}

  2. Modifique el método Main para crear una instancia del nuevo agente de escucha.

    public static void Main(string[] args)
{
    ConsoleWriterEventListener listener = new ConsoleWriterEventListener();

    DemoEventSource.Log.AppStarted("Hello World!", 12);
    DemoEventSource.Log.DebugMessage("Got here");
    DemoEventSource.Log.DebugMessage("finishing startup");
    DemoEventSource.Log.RequestStart(3);
    DemoEventSource.Log.RequestStop(3);
}

  3. Compile y ejecute la aplicación. Anteriormente, no tenía ninguna salida, pero ahora escribe los eventos en la consola:

    3/24/2022 9:23:35 AM AppStarted
3/24/2022 9:23:35 AM RequestStart
3/24/2022 9:23:35 AM RequestStop