Śledzenie zdarzeń C/C++ — Szybki start

W poniższej sekcji opisano podstawowe kroki wymagane do dodania funkcji TraceLogging do kodu trybu użytkownika C/C++.

Warunki wstępne

• Program Microsoft Visual Studio 2013 lub nowszy.
• Do napisania dostawcy trybu użytkownika jest wymagany zestaw Windows 10 Software Development Kit (SDK).
• Do zapisu dostawcy trybu jądra wymagany jest zestaw Sterowników Systemu Windows (WDK) dla systemu Windows 10.

Aby zebrać i zdekodować zdarzenia z tych przykładów, należy rozpocząć śledzenie przy użyciu narzędzia takiego jak tracelog lub traceview, uruchomić przykład, zatrzymać śledzenie przy użyciu narzędzia, takiego jak tracelog lub traceview, i zdekodować ślad przy użyciu narzędzia dekodowania, takiego jak tracefmt lub traceview. Jeśli na przykład mój dostawca został zdefiniowany przy użyciu identyfikatora GUID {0205c616-cf97-5c11-9756-56a2cee02ca7}, można wyświetlić zdarzenia z tych przykładów przy użyciu narzędzi zestawu Windows SDK tracelog i tracefmt w następujący sposób:

• tracelog -start MyTraceSession -f MyTraceFile.etl -guid #0205c616-cf97-5c11-9756-56a2cee02ca7
• Uruchom przykład.
• tracelog -stop MyTraceSession
• tracefmt -o MyTraceFile.txt MyTraceFile.etl
• notepad MyTraceFile.txt

SimpleTraceLoggingExample.h

Ten przykładowy nagłówek zawiera interfejsy API rejestrowania śledzenia i deklaruje z wyprzedzeniem dojście dostawcy, które będzie używane do rejestrowania zdarzeń. Każda klasa, która chce używać funkcji TraceLogging, będzie zawierać ten nagłówek, a następnie może rozpocząć rejestrowanie.

#pragma once

#include <windows.h> // Definitions required by TraceLoggingProvider.h
#include <TraceLoggingProvider.h> // The C/C++ TraceLogging API

// Forward-declare the g_hMyComponentProvider variable that you will use for tracing in this component
TRACELOGGING_DECLARE_PROVIDER(g_hMyComponentProvider);

Plik nagłówka zawiera TraceLoggingProvider.h, który definiuje interfejs API TraceLogging dla C/C++. Najpierw należy uwzględnić windows.h, ponieważ definiuje stałe używane przez TraceLoggingProvider.h.

Plik nagłówkowy deklaruje uchwyt dostawcy g_hMyComponentProvider, który przekażesz do interfejsów API TraceLogging, aby rejestrować zdarzenia. Ten uchwyt musi być dostępny dla dowolnego kodu, który chce używać funkcji TraceLogging.

TRACELOGGING_DECLARE_PROVIDER to makro, które tworzy uchwyt extern const TraceLoggingHProvider przy użyciu podanej nazwy, która w powyższym przykładzie jest g_hMyComponentProvider. Przydzielisz rzeczywistą zmienną uchwytu dostawcy w pliku kodu.

SimpleTraceLoggingExample.cpp

Poniższy przykład rejestruje dostawcę, rejestruje zdarzenie i wyrejestrowuje dostawcę.

#include "SimpleTraceLoggingExample.h"

// Define a handle to a TraceLogging provider
TRACELOGGING_DEFINE_PROVIDER(
    g_hMyComponentProvider,
    "SimpleTraceLoggingProvider",
    // {0205c616-cf97-5c11-9756-56a2cee02ca7}
    (0x0205c616,0xcf97,0x5c11,0x97,0x56,0x56,0xa2,0xce,0xe0,0x2c,0xa7));

void main()
{

    char sampleValue[] = "Sample value";

    // Register the provider
    TraceLoggingRegister(g_hMyComponentProvider);

    // Log an event
    TraceLoggingWrite(g_hMyComponentProvider, // handle to my provider
        "HelloWorldTestEvent",              // Event Name that should uniquely identify your event.
        TraceLoggingValue(sampleValue, "TestMessage")); // Field for your event in the form of (value, field name).

    // Stop TraceLogging and unregister the provider
    TraceLoggingUnregister(g_hMyComponentProvider);
}

Powyższy przykład zawiera plik SimpleTraceLoggingExample.h, który zawiera globalną zmienną dostawcy, która będzie używana przez kod do rejestrowania zdarzeń.

Makro TRACELOGGING_DEFINE_PROVIDER przydziela magazyn i definiuje zmienną obsługi dostawcy. Nazwa zmiennej podanej dla tego makra musi być zgodna z nazwą użytą w makrze TRACELOGGING_DECLARE_PROVIDER w pliku nagłówka.

Zarejestruj uchwyt dostawcy

Aby można było użyć uchwytu dostawcy do rejestrowania zdarzeń, należy wywołać TraceLoggingRegister, aby zarejestrować uchwyt dostawcy. Zazwyczaj odbywa się to w pliku main() lub DLLMain(), ale można to zrobić w dowolnym momencie, o ile poprzedza wszelkie próby zarejestrowania zdarzenia. Jeśli rejestrujesz zdarzenie przed zarejestrowaniem dojścia dostawcy, nie wystąpi błąd, ale zdarzenie nie zostanie zarejestrowane. Poniższy kod z powyższego przykładu rejestruje uchwyt dostawcy.

// Define the GUID to use in TraceLoggingProviderRegister
TRACELOGGING_DEFINE_PROVIDER(
    g_hMyComponentProvider,
    "SimpleTraceLoggingProvider",
    // {0205c616-cf97-5c11-9756-56a2cee02ca7}
    (0x0205c616,0xcf97,0x5c11,0x97,0x56,0x56,0xa2,0xce,0xe0,0x2c,0xa7));

void main()
{
    char sampleValue[] = "Sample value";

    // Register the provider
    TraceLoggingRegister(g_hMyComponentProvider);

Zarejestruj zdarzenie Tracelogging

Po zarejestrowaniu dostawcy poniższy kod rejestruje proste zdarzenie.

    // Log an event
    TraceLoggingWrite(g_hMyComponentProvider, // handle to my provider
        "HelloWorldTestEvent",              // Event Name that should uniquely identify your event.
        TraceLoggingValue(sampleValue, "TestMessage")); // Field for your event in the form of (value, field name).

Makro TraceLoggingWrite akceptuje maksymalnie dziewięćdziesiąt dziewięć argumentów. Nazwa zdarzenia jest przechowywana w formacie UTF-8. Nie można używać znaków '\0' osadzonych w nazwach zdarzeń lub nazwach pól. Nie ma żadnych innych ograniczeń dotyczących dozwolonych znaków, chociaż niektóre dekodatory zdarzeń lub procesory zdarzeń mogą mieć własne ograniczenia.

Każdy argument po nazwie zdarzenia musi być zamknięty w TraceLogging Wrapper Macro. Jeśli używasz języka C++, możesz użyć makra opakowującego TraceLoggingValue, aby automatycznie określić typ argumentu. Jeśli piszesz w języku C lub chcesz mieć większą kontrolę nad typem pola, musisz użyć makr pól specyficznych dla typu, takich jak TraceLoggingInt32, TraceLoggingUnicodeString, TraceLoggingStringitp.

Oprócz rejestrowania pojedynczych zdarzeń można również grupować zdarzenia według działań przy użyciu makr TraceLoggingWriteActivity lub TraceLoggingWriteStart/TraceLoggingWriteStop makr znalezionych w TraceLoggingActivity.h. Działania korelują zdarzenia i są przydatne w scenariuszach, które mają początek i koniec. Na przykład możesz użyć działania do mierzenia scenariusza, który rozpoczyna się od uruchomienia aplikacji, obejmuje czas potrzebny na udostępnienie ekranu powitalnego i kończy się, gdy początkowy ekran aplikacji stanie się widoczny.

Działania przechwytują pojedyncze zdarzenia i zagnieżdżają inne działania występujące między rozpoczęciem i końcem tego działania. Działania mają zakres poszczególnych procesów i muszą zostać przekazane z wątku do wątku w celu prawidłowego zagnieżdżania zdarzeń wielowątkowych.

Zakres uchwytu dostawcy jest ograniczony do modułu (.DLL, .EXE lub pliku .SYS), w którym został zdefiniowany. Uchwyt nie powinien być przekazywany do innych bibliotek DLL. Jeśli makro TraceLoggingWrite jest wywoływane w A.DLL przy użyciu uchwytu dostawcy zdefiniowanego w B.DLL, może to spowodować problemy. Najbezpieczniejszym i najbardziej wydajnym sposobem spełnienia tego wymagania jest po prostu zawsze bezpośrednio odwoływać się do dojścia dostawcy globalnego i nigdy nie przekazywać dojścia dostawcy jako parametru.

Wyrejestruj dostawcę

Przed odłączeniem składnika należy wyrejestrować dostawcę TraceLogging. Jest to szczególnie ważne w przypadku bibliotek DLL i sterowników. Awaria jest prawdopodobna, jeśli biblioteka DLL lub sterownik zwalnia bez wyrejestrowywania dostawcy.

Następujący kod wyrejestruje dostawcę:

// Stop TraceLogging and unregister the provider
TraceLoggingUnregister(g_hMyComponentProvider);

Zgodność

W zależności od konfiguracji element TraceLoggingProvider.h może być zgodny z poprzednimi wersjami (wynikowy program będzie uruchamiany w systemie Windows Vista lub nowszym) lub może być zoptymalizowany pod kątem nowszych wersji systemu operacyjnego. TraceLoggingProvider.h używa winVER (tryb użytkownika) i NTDDI_VERSION (tryb jądra) w celu określenia, czy powinna być zgodna z wcześniejszymi wersjami systemu operacyjnego, czy być zoptymalizowana pod kątem nowszych wersji systemu operacyjnego.

W przypadku trybu użytkownika, jeśli uwzględnisz <windows.h> przed ustawieniem WINVER, <windows.h> ustawi winVER na domyślną docelową wersję systemu operacyjnego zestawu SDK. Jeśli system WINVER jest ustawiony na 0x602 lub nowszy, TraceLoggingProvider.h optymalizuje zachowanie systemu Windows 8 lub nowszego, a aplikacja nie będzie działać we wcześniejszych wersjach systemu Windows. Jeśli potrzebujesz programu działającego na systemie Vista lub Windows 7, pamiętaj, aby ustawić WINVER na odpowiednią wartość przed dołączeniem <windows.h>.

Podobnie jeśli uwzględnisz <wdm.h> przed ustawieniem NTDDI_VERSION, <wdm.h> ustawi NTDDI_VERSION wartość domyślną. Jeśli NTDDI_VERSION jest ustawiona na 0x06040000 lub wyższą, TraceLoggingProvider.h optymalizuje jego zachowanie dla systemu Windows 10, a sterownik nie będzie działać we wcześniejszych wersjach systemu Windows.

To zachowanie można kontrolować, ustawiając TLG_HAVE_EVENT_SET_INFORMATION przed dołączeniem TraceLoggingProvider.h. Zapoznaj się z komentarzami w nagłówku TraceLoggingProvider.h, aby uzyskać szczegółowe informacje na temat makra TLG_HAVE_EVENT_SET_INFORMATION.

Podsumowanie i następne kroki

Aby zobaczyć, jak przechwytywać i wyświetlać dane TraceLogging przy użyciu narzędzi Windows Performance Tools (WPT), zobacz Nagrywanie i Wyświetlanie Zdarzeń TraceLogging.

Zobacz przykłady rejestrowania śladów języka C/C++, aby uzyskać więcej przykładów rejestrowania śladów języka C++.