TraceLogging Wrapper Macros

  • Artigo

As macros TraceLoggingWrite e TraceLoggingWriteActivity emitem eventos TraceLogging configurados de acordo com os parâmetros de macro. Cada uma dessas macros aceita um conjunto de parâmetros necessários seguido por até 99 parâmetros opcionais. Cada parâmetro opcional configura o evento ou adiciona um campo ao evento. Cada parâmetro opcional deve ser uma das macros TraceLogging Wrapper descritas nesta página.

Por exemplo:

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

Neste exemplo, g_hProvider e "MyEvent1" são os parâmetros necessários. Eles especificam o provedor a ser usado para o evento e o nome do evento. Cada um dos parâmetros restantes é uma macro wrapper. Os TraceLoggingLevel parâmetros e TraceLoggingKeyword configuram o evento. Os TraceLoggingString parâmetros e TraceLoggingHResult adicionam campos ao evento.

Macros de Configuração de Eventos

As macros a seguir configuram o evento.

Se uma macro de configuração específica não for fornecida no TraceLoggingWrite, um padrão será usado para esse evento. Por exemplo, se nenhum parâmetro TraceLoggingLevel for usado para um evento, o evento usará um nível padrão de 5 (VERBOSE).

  • TraceLoggingLevel define o nível do evento. O nível é um valor de 8 bits que indica a gravidade do evento. Os níveis de 1 (WINEVENT_LEVEL_CRITICAL) a 5 (WINEVENT_LEVEL_VERBOSE) são definidos em <winmeta.h>. Se não for especificado, o evento usará como padrão o nível 5 (VERBOSE). Level é uma parte importante do roteamento e filtragem de eventos ETW, portanto, todos os eventos devem ter um nível significativo diferente de zero.
  • TraceLoggingKeyword define o palavra-chave do evento. Um palavra-chave é um valor de 64 bits com cada bit indicando uma categoria à qual o evento pertence. Os 48 bits baixos do palavra-chave são definidos pelo proprietário do provedor, enquanto os 16 bits altos do palavra-chave são definidos pela Microsoft. Por exemplo, você pode decidir que todos os provedores com o nome "MyCompany.MyComponent" usarão palavra-chave 0x1 para significar "Rede". Se não for especificado, o evento usará como padrão palavra-chave 0x0 (Nenhum). A palavra-chave é uma parte importante do roteamento e filtragem de eventos ETW, portanto, todos os eventos devem ter uma palavra-chave significativa diferente de zero.
  • TraceLoggingOpcode define o opcode do evento. O opcode é um valor de 8 bits que indica semântica especial para o evento, por exemplo, que o evento registra o início (WINEVENT_OPCODE_START) ou o fim (WINEVENT_OPCODE_STOP) de uma atividade ETW (um grupo de eventos relacionados). Se não for especificado, o evento usará como padrão opcode 0 (WINEVENT_OPCODE_INFO) indicando que nenhuma semântica especial é necessária.
  • TraceLoggingChannel define o canal do evento. O canal é um valor de 8 bits usado para várias finalidades. Se não for especificado, o evento usará como padrão o canal 11 (WINEVENT_CHANNEL_TRACELOGGING). A maioria dos eventos não precisa alterar o canal do evento e não deve usar TraceLoggingChannel.
  • TraceLoggingEventTag define a marca do evento. A marca é um valor de 28 bits com semântica definida pelo provedor. Por exemplo, um provedor pode definir 0x1000000 de bits de marca para indicar que o evento potencialmente contém informações de identificação pessoal e deve receber tratamento especial de ferramentas de processamento de eventos específicas do provedor. Se não for especificado, a marca será padronizada como 0.
  • TraceLoggingDescription define a descrição do evento. A descrição é um literal de cadeia de caracteres com uma descrição legível do evento. Isso serve como um comentário sobre a finalidade do evento e a descrição também é registrada como uma anotação nos PDB (símbolos de depuração) do componente. Se não for especificado, a descrição usará como padrão "".
  • TraceLoggingCustomAttribute adiciona uma anotação chave-valor aos símbolos de depuração do componente (PDB).

Macros de campo

O TraceLogging dá suporte a muitas macros wrapper para adicionar campos a um evento. Cada campo é um par nome-valor. Por exemplo, TraceLoggingInt32(argc, "ArgCount") adicionaria um campo INT32 chamado "ArgCount" com o valor argc.

A maioria das macros wrapper de campo aceita parâmetros semelhantes:

  • Valor: Uma expressão que será avaliada em runtime para determinar os dados a serem incluídos no campo. A maioria das macros wrapper de campo usa um único parâmetro para especificar o valor, mas algumas macros exigem vários parâmetros para o valor do campo, por exemplo, um ponteiro e um comprimento. Os parâmetros de valor são sempre necessários.
    • Em alguns casos, o valor do campo é especificado como pszValue; nesse caso, é um ponteiro para uma cadeia de caracteres terminada em 0 a ser incluída no campo. pszValue pode ser NULL; nesse caso, o valor do campo será uma cadeia de caracteres ""vazia .
    • Em alguns casos, o valor do campo é especificado como pchValue. Nesse caso, é um ponteiro para uma cadeia de caracteres cchValue a ser incluída no campo. pchValue poderá ser NULL somente se cchValue for 0.
    • Em alguns casos, o valor do campo é especificado como pValue com um tamanho determinado automaticamente (sem parâmetro cbValue ), nesse caso, é um ponteiro para o valor a ser incluído no campo. pValue pode não ser NULL.
    • Em alguns casos, o valor do campo é especificado como pValue com um parâmetro cbValue para especificar o tamanho (em bytes) dos dados a serem incluídos no campo. pValue poderá ser NULL somente se cbValue for 0.
  • Nome: Um literal de cadeia de caracteres (constante de tempo de compilação) com o nome a ser usado para o campo. A maioria das macros de wrapper de campo não exige um parâmetro de nome. Se você omitir o parâmetro name, o nome do campo será determinado com base no texto do pré-processador do valor da macro, pszValue, pchValue ou parâmetro pValue . Por exemplo, TraceLoggingInt32(x[4] + y) é equivalente a TraceLoggingInt32(x[4] + y, "x[4] + y"). Ambos adicionariam um campo chamado "x[4] + y" ao evento com um valor determinado pela avaliação da expressão x[4] + y.
  • Descrição: Um literal de cadeia de caracteres (constante de tempo de compilação) com uma descrição a ser usada para o campo. Isso é usado principalmente como um lugar conveniente para colocar um comentário para o campo, mas a descrição também é registrada como uma anotação nos símbolos de depuração do componente (PDB). A descrição é opcional. Se o parâmetro de descrição for omitido, a descrição do campo usará como padrão "".
  • Tag: Um inteiro de 28 bits (constante de tempo de compilação) com semântica definida pelo provedor. Por exemplo, um provedor pode definir 0x2 de marca para indicar que o campo contém um número de telefone e deve receber tratamento especial de ferramentas de processamento de eventos específicas do provedor. Se o parâmetro de marca for omitido, a marca do campo usará como padrão 0.

Por exemplo, as seguintes invocações de macro wrapper têm o mesmo efeito:

  • TraceLoggingInt32(argc)
  • TraceLoggingInt32(argc, "argc")
  • TraceLoggingInt32(argc, "argc", "")
  • TraceLoggingInt32(argc, "argc", "", 0)

Escalares

  • TraceLoggingValue(value, [name, ...]):

    Adiciona um campo com um tipo que é deduzido automaticamente do tipo do parâmetro value. (Somente C++)

  • TraceLoggingInt8(value, [name, ...]):

    Adiciona um campo com um valor INT8.

  • TraceLoggingUInt8(value, [name, ...]):

    Adiciona um campo com um valor UINT8.

  • TraceLoggingInt16(value, [name, ...]):

    Adiciona um campo com um valor INT16.

  • TraceLoggingUInt16(value, [name, ...]):

    Adiciona um campo com um valor UINT16.

  • TraceLoggingInt32(value, [name, ...]):

    Adiciona um campo com um valor INT32.

  • TraceLoggingUInt32(value, [name, ...]):

    Adiciona um campo com um valor UINT32.

  • TraceLoggingInt64(value, [name, ...]):

    Adiciona um campo com um valor INT64.

  • TraceLoggingUInt64(value, [name, ...]):

    Adiciona um campo com um valor UINT64.

  • TraceLoggingIntPtr(value, [name, ...]):

    Adiciona um campo com um valor INT_PTR (inteiro com sinal com o mesmo tamanho de um ponteiro).

  • TraceLoggingUIntPtr(value, [name, ...]):

    Adiciona um campo com um valor de UINT_PTR (inteiro sem sinal com o mesmo tamanho de um ponteiro).

  • TraceLoggingLong(value, [name, ...]):

    Adiciona um campo com um valor LONG (int longo assinado, 32 bits em plataformas Windows).

  • TraceLoggingULong(value, [name, ...]):

    Adiciona um campo com um valor ULONG (int longo sem sinal, 32 bits em plataformas Windows).

  • TraceLoggingHexInt8(value, [name, ...]):

    Adiciona um campo com um valor INT8 com uma dica de formatação hexadecimal.

  • TraceLoggingHexUInt8(value, [name, ...]):

    Adiciona um campo com um valor UINT8 com uma dica de formatação hexadecimal.

  • TraceLoggingHexInt16(value, [name, ...]):

    Adiciona um campo com um valor INT16 com uma dica de formatação hexadecimal.

  • TraceLoggingHexUInt16(value, [name, ...]):

    Adiciona um campo com um valor UINT16 com uma dica de formatação hexadecimal.

  • TraceLoggingHexInt32(value, [name, ...]):

    Adiciona um campo com um valor INT32 com uma dica de formatação hexadecimal.

  • TraceLoggingHexUInt32(value, [name, ...]):

    Adiciona um campo com um valor UINT32 com uma dica de formatação hexadecimal.

  • TraceLoggingHexInt64(value, [name, ...]):

    Adiciona um campo com um valor INT64 com uma dica de formatação hexadecimal.

  • TraceLoggingHexUInt64(value, [name, ...]):

    Adiciona um campo com um valor UINT64 com uma dica de formatação hexadecimal.

  • TraceLoggingHexIntPtr(value, [name, ...]):

    Adiciona um campo com um valor INT_PTR com uma dica de formatação hexadecimal.

  • TraceLoggingHexUIntPtr(value, [name, ...]):

    Adiciona um campo com um valor UINT_PTR com uma dica de formatação hexadecimal.

  • TraceLoggingHexLong(value, [name, ...]):

    Adiciona um campo com um valor LONG com uma dica de formatação hexadecimal.

  • TraceLoggingHexULong(value, [name, ...]):

    Adiciona um campo com um valor ULONG com uma dica de formatação hexadecimal.

  • TraceLoggingFloat32(value, [name, ...]):

    Adiciona um campo com um valor FLOAT (ponto flutuante de 32 bits).

  • TraceLoggingFloat64(value, [name, ...]):

    Adiciona um campo com um valor DOUBLE (ponto flutuante de 64 bits).

  • TraceLoggingBoolean(value, [name, ...]):

    Adiciona um campo com um valor booliano de 8 bits (Win32 BOOLEAN ou C++ bool).

  • TraceLoggingBool(value, [name, ...]):

    Adiciona um campo com um valor booliano de 32 bits (Win32 BOOL).

  • TraceLoggingChar(value, [name, ...]):

    Adiciona um campo com um char valor (inteiro de 8 bits com dica de formatação de cadeia de caracteres, normalmente tratado como página de código 1252).

  • TraceLoggingChar16(value, [name, ...]):

    Adiciona um campo com um char16_t valor (inteiro de 16 bits com dica de formatação de cadeia de caracteres, normalmente tratado como UCS-2).

  • TraceLoggingWChar(value, [name, ...]):

    Adiciona um campo com um wchar_t valor (o mesmo que char16_t em plataformas Windows).

  • TraceLoggingPointer(value, [name, ...]):

    Adiciona um campo com um void* valor (valor do tamanho do ponteiro com uma dica de formatação hexadecimal).

  • TraceLoggingCodePointer(value, [name, ...]):

    Adiciona um campo com um void* valor (valor do tamanho do ponteiro com uma dica de formatação de ponteiro de código).

  • TraceLoggingPid(value, [name, ...]):

    Adiciona um campo com um valor INT32 com uma dica de formatação de ID de processo.

  • TraceLoggingTid(value, [name, ...]):

    Adiciona um campo com um valor INT32 com uma dica de formatação de ID de thread.

  • TraceLoggingIPv4Address(value, [name, ...]):

    Adiciona um campo com um valor UINT32 com uma dica de formatação IPv4 (ordem de bytes de rede).

  • TraceLoggingIPv6Address(pValue, [name, ...]):

    Adiciona um campo com um valor binário de 16 bytes com uma dica de formatação IPv6.

  • TraceLoggingPort(value, [name, ...]):

    Adiciona um campo com um valor UINT16 com uma dica de formatação de porta IP (ordem de bytes de rede).

  • TraceLoggingSocketAddress(pValue, cbValue, [name, ...]):

    Adiciona um campo com um valor SOCKADDR .

  • TraceLoggingWinError(value, [name, ...]):

    Adiciona um campo com um valor UINT32 com uma dica de formatação de código de erro Win32.

  • TraceLoggingNTStatus(value, [name, ...]):

    Adiciona um campo com um valor NTSTATUS (LONG) com uma dica de formatação de código de erro WinNT.

  • TraceLoggingHResult(value, [name, ...]):

    Adiciona um campo com um valor HRESULT (LONG) com uma dica de formatação HRESULT do Windows.

  • TraceLoggingFileTime(value, [name, ...]):

    Adiciona um campo com um valor FILETIME . Quando usado no código C, o value parâmetro deve ser uma expressão lvalue.

  • TraceLoggingFileTimeUtc(value, [name, ...]):

    Adiciona um campo com um valor FILETIME com uma dica de formatação de fuso horário UTC. Quando usado no código C, o value parâmetro deve ser uma expressão lvalue.

  • TraceLoggingSystemTime(value, [name, ...]):

    Adiciona um campo com um valor SYSTEMTIME . Quando usado no código C, o value parâmetro deve ser uma expressão lvalue.

  • TraceLoggingSystemTimeUtc(value, [name, ...]):

    Adiciona um campo com um valor SYSTEMTIME com uma dica de formatação de fuso horário UTC. Quando usado no código C, o value parâmetro deve ser uma expressão lvalue.

  • TraceLoggingGuid(value, [name, ...]):

    Adiciona um campo com um valor GUID . Quando usado no código C, o value parâmetro deve ser uma expressão lvalue.

  • TraceLoggingString(pszValue, [name, ...]):

    Adiciona um campo com uma cadeia de caracteres terminada char em 0 (normalmente tratada como página de código 1252). Se pszValue for NULL, uma cadeia de caracteres "" vazia será usada como o valor do campo.

  • TraceLoggingUtf8String(pszValue, [name, ...]):

    Adiciona um campo com uma cadeia de caracteres terminada char em 0 com uma dica de formatação UTF-8. Se pszValue for NULL, uma cadeia de caracteres "" vazia será usada como o valor do campo.

  • TraceLoggingString16(pszValue, [name, ...]):

    Adiciona um campo com uma cadeia de caracteres terminada char16_t em 0 (UTF-16). Se pszValue for NULL, uma cadeia de caracteres u"" vazia será usada como o valor do campo.

  • TraceLoggingWideString(pszValue, [name, ...]):

    Adiciona um campo com uma cadeia de caracteres terminada wchar_t em 0 (UTF-16 no Windows). Se pszValue for NULL, uma cadeia de caracteres L"" vazia será usada como o valor do campo.

  • TraceLoggingCountedString(pchValue, cchValue, [name, ...]):

    Adiciona um campo com uma cadeia de caracteres contada char (normalmente tratada como página de código 1252). pchValue poderá ser NULL somente se cchValue for 0.

  • TraceLoggingCountedUtf8String(pchValue, cchValue, [name, description, tag]):

    Adiciona um campo com uma cadeia de caracteres contada char com uma dica de formatação UTF-8. pchValue poderá ser NULL somente se cchValue for 0.

  • TraceLoggingCountedString16(pchValue, cchValue, [name, ...]):

    Adiciona um campo com uma cadeia de caracteres contada char16_t (UTF-16). pchValue poderá ser NULL somente se cchValue for 0.

  • TraceLoggingCountedWideString(pchValue, cchValue, [name, description, tag]):

    Adiciona um campo com uma cadeia de caracteres contada wchar_t (UTF-16 no Windows). pchValue poderá ser NULL somente se cchValue for 0.

  • TraceLoggingAnsiString(pValue, [name, ...]):

    Adiciona um campo com um valor ANSI_STRING . O ponteiro pValue não deve ser NULL.

  • TraceLoggingUnicodeString(pValue, [name, ...]):

    Adiciona um campo com um valor UNICODE_STRING . O ponteiro pValue não deve ser NULL.

  • TraceLoggingSid(pValue, [name, ...]):

    Adiciona um campo com um valor sid . O ponteiro pValue não deve ser NULL e deve apontar para um SID inicializado corretamente (Revision e SubAuthorityCount devem ser válidos).

  • TraceLoggingBinary(pValue, cbValue, [name, ...]):

    Adiciona um campo com dados binários.

  • TraceLoggingBinaryEx(pValue, cbValue, outType, [name, ...]):

    Adiciona um campo com dados binários com a dica de formatação especificada por outType.

  • TraceLoggingBinaryBuffer(pValue, StructType, [name, ...]):

    Adiciona um campo com dados binários. pValue deve ser um ponteiro não NULL para um StructType struct. pValue->Buffer deve apontar para o início dos dados e pValue->Length deve ser o número de bytes de dados a serem incluídos no campo.

  • TraceLoggingBinaryBufferEx(pValue, StructType, outType, name, description, tag):

    Adiciona um campo com dados binários com a dica de formatação especificada por outType. pValue deve ser um ponteiro não NULL para um StructType struct. pValue->Buffer deve apontar para o início dos dados e pValue->Length deve ser o número de bytes de dados a serem incluídos no campo.

  • TraceLoggingCustom(pValue, cbValue, protocol, bSchema, cbSchema, [name, ...]):

    Adiciona um campo com dados binários que foram serializados de acordo com um protocolo de serialização. As informações de decodificação constante em tempo de compilação serão incluídas junto com o evento para permitir a desserialização pelo decodificador de eventos.

Estruturas

Você pode usar a macro TraceLoggingStruct(fieldCount, name, [...]) para criar uma estrutura nomeada (grupo de campos). O parâmetro fieldCount indica quantos dos campos subsequentes devem ser contados como parte da estrutura. As estruturas podem ser aninhadas, caso em que cada estrutura aninhada e seus campos contidos contam como um único campo com a finalidade de definir o struct pai.

Matrizes

Você pode criar um campo que contém uma matriz de valores escalares (únicos). Por exemplo, você adiciona uma matriz de GUIDs como um único campo em seu evento.

Observação

Embora o protocolo TraceLogging dê suporte a matrizes de todos os tipos, TraceLoggingProvider.h fornece apenas macros wrapper para matrizes de valores simples, por exemplo, ele fornece macros para matrizes de INT32 e GUID, mas não fornece macros para matrizes de cadeia de caracteres ou matrizes de estruturas. É possível criar eventos com matrizes de valores complexos realizando marshaling dos dados em um buffer e, em seguida, usando as TraceLoggingPacked macros descritas abaixo.

O TraceLogging dá suporte a matrizes de comprimento fixo e de comprimento variável.

  • Use a Array macro nos casos em que o comprimento da matriz não é conhecido em tempo de compilação e pode ser diferente sempre que o evento é gerado.
  • Use a FixedArray macro nos casos em que o comprimento da matriz é conhecido em tempo de compilação (ou seja, quando o comprimento da matriz é uma constante). Isso comunica ao consumidor do evento que todos os eventos com um nome de evento específico terão o mesmo número de itens no campo de matriz.

Todas as macros de matriz exigem que os parâmetros pValues e cValues sejam especificados, com pValues apontando para o início do conteúdo da matriz e cValues definidos como o número de itens na matriz. pValues só poderão ser NULL se cValues for 0.

Opcionalmente, todas as macros de matriz aceitam parâmetros de nome, descrição e marca , conforme descrito para as macros escalares. Se name não for especificado, o nome do campo será determinado a partir do texto do pré-processador de pValues. Se a descrição não for especificada, a descrição do campo será "". Se a marca não for especificada, a marca de campo será 0.

Observação

Para garantir que o ETW não remova seus eventos, evite criar eventos com matrizes grandes. O ETW não dá suporte a eventos maiores que 64 KB. Esses eventos serão descartados silenciosamente pelo ETW. Além disso, eventos maiores que o BufferSize da sessão do consumidor também serão descartados pelo ETW. O tamanho do evento é baseado na soma dos cabeçalhos, metadados do evento (provedor, eventos e nomes de campo) e dados (valores de campo).

  • TraceLoggingInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingUIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingLongArray(pValues, cValues, [name, ...])
  • TraceLoggingLongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingULongArray(pValues, cValues, [name, ...])
  • TraceLoggingULongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingHexIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexLongArray(pValues, cValues, [name, ...])
  • TraceLoggingHexLongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexULongArray(pValues, cValues, [name, ...])
  • TraceLoggingHexULongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFloat32Array(pValues, cValues, [name, ...])
  • TraceLoggingFloat32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFloat64Array(pValues, cValues, [name, ...])
  • TraceLoggingFloat64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingBooleanArray(pValues, cValues, [name, ...])
  • TraceLoggingBooleanFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingBoolArray(pValues, cValues, [name, ...])
  • TraceLoggingBoolFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingCharArray(pValues, cValues, [name, ...])
  • TraceLoggingCharFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingChar16Array(pValues, cValues, [name, ...])
  • TraceLoggingChar16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingWCharArray(pValues, cValues, [name, ...])
  • TraceLoggingWCharFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingPointerArray(pValues, cValues, [name, ...])
  • TraceLoggingPointerFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingCodePointerArray(pValues, cValues, [name, ...])
  • TraceLoggingCodePointerFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeUtcArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeUtcFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeUtcArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeUtcFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingGuidArray(pValues, cValues, [name, ...])
  • TraceLoggingGuidFixedArray(pValues, cValues, [name, ...])

Macros empacotadas

TraceLoggingProvider.h fornece apenas macros de campo para tipos de campo blittable, ou seja, campos em que cada macro de campo corresponde a um único campo e uma única região contígua de memória com o valor do campo.

TraceLoggingProvider.h não fornece suporte direto para casos mais complexos, como:

  • Registrar em log uma matriz de um tipo de comprimento variável, como uma matriz de cadeias de caracteres.
  • Registrando em log uma matriz de estruturas.
  • Passando vários campos para ETW por meio de um único buffer para reduzir a sobrecarga de registro em log de eventos.

Para dar suporte a esses cenários, TraceLoggingProvider.h define várias TraceLoggingPacked macros que permitem manipular diretamente a definição de evento (metadados) e os valores de campo (dados) do evento.

Aviso

As TraceLoggingPacked macros são complicadas de usar corretamente e exigem uma boa compreensão de como os eventos traceLogging são criados. Se usados incorretamente, eles resultarão em eventos corrompidos que não decodificam corretamente.

Para obter detalhes sobre o uso dessas macros, consulte os comentários no cabeçalho TraceLoggingProvider.h.

  • TraceLoggingPackedField(pValue, cbValue, inType, [name, description, tags]):

    Adiciona dados de campo (pValue, cbValue) e metadados de campo (nome, inType).

  • TraceLoggingPackedFieldEx(pValue, cbValue, inType, outType, [name, ...]):

    Adiciona dados de campo (pValue, cbValue) e metadados de campo (nome, inType) juntamente com uma dica de formatação (outType).

  • TraceLoggingPackedMetadata(inType, [name, ...]):

    Adiciona metadados de campo (nome, inType) sem adicionar dados de campo. Os dados de campo correspondentes devem ser adicionados por meio de TraceLoggingPackedData.

  • TraceLoggingPackedMetadataEx(inType, outType, [name, ...]):

    Adiciona metadados de campo (nome, inType) e uma dica de formatação (outType) sem adicionar dados de campo. Os dados de campo correspondentes devem ser adicionados por meio de TraceLoggingPackedData.

  • TraceLoggingPackedStruct(fieldCount, name, [...]):

    Adiciona metadados de campo (nome, fieldCount) para um struct.

  • TraceLoggingPackedStructArray(fieldCount, [name, ...]):

    Adiciona metadados de campo (nome, fieldCount) para uma matriz de comprimento variável de struct. O comprimento da matriz deve ser especificado por meio de TraceLoggingPackedData.

  • TraceLoggingPackedData(pValue, cbValue):

    Adiciona dados de campo a um evento sem adicionar metadados de campo. Os metadados correspondentes devem ser adicionados por meio das macros de metadados.

  • TraceLoggingPackedDataEx(pValue, cbValue, dataDescType):

    Adiciona dados de campo a um evento sem adicionar metadados de campo, usando um específico Type no EVENT_DATA_DESCRIPTOR para os dados. Os metadados correspondentes devem ser adicionados por meio das macros de metadados.