Compartilhar via

Função EventWriteString (evntprov.h)

  • Artigo

Grava um evento ETW que contém uma cadeia de caracteres como seus dados. Essa função não deve ser usada.

Sintaxe

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

Parâmetros

[in] RegHandle

Identificador de registro do provedor. O identificador vem de EventRegister. O evento gerado usará a ProviderId associada ao identificador.

[in] Level

Um número de 8 bits usado para descrever a gravidade ou a importância de um evento.

Importante

ProviderId, Level e Keyword são os principais meios para filtrar eventos. Outros tipos de filtragem são possíveis, mas têm uma sobrecarga muito maior. Sempre atribua um nível diferente de zero e palavra-chave a cada evento.

Consulte EVENT_DESCRIPTOR para obter detalhes sobre o nível de evento.

[in] Keyword

Uma máscara de bits de 64 bits usada para indicar a associação de um evento em um conjunto de categorias de eventos.

Importante

ProviderId, Level e Keyword são os principais meios para filtrar eventos. Outros tipos de filtragem são possíveis, mas têm uma sobrecarga muito maior. Sempre atribua um nível diferente de zero e palavra-chave a cada evento.

Consulte EVENT_DESCRIPTOR para obter detalhes sobre a palavra-chave do evento.

[in] String

Cadeia de caracteres terminada em NUL para gravar como os dados do evento.

Valor retornado

Retorna ERROR_SUCCESS se tiver êxito ou um código de erro. Os códigos de erro possíveis incluem o seguinte:

  • ERROR_INVALID_PARAMETER: um ou mais dos parâmetros não são válidos.
  • ERROR_INVALID_HANDLE: o identificador de registro do provedor não é válido.
  • ERROR_ARITHMETIC_OVERFLOW: o tamanho do evento é maior que o máximo permitido (64 KB – cabeçalho).
  • ERROR_MORE_DATA: o tamanho do buffer de sessão é muito pequeno para o evento.
  • ERROR_NOT_ENOUGH_MEMORY: ocorre quando os buffers preenchidos estão tentando liberar para o disco, mas os IOs de disco não estão acontecendo rápido o suficiente. Isso acontece quando o disco está lento e o tráfego de eventos é pesado. Eventualmente, não há mais buffers gratuitos (vazios) e o evento é descartado.
  • STATUS_LOG_FILE_FULL: o arquivo de reprodução em tempo real está cheio. Os eventos não são registrados na sessão até que um consumidor em tempo real consuma os eventos do arquivo de reprodução.

O código de erro destina-se principalmente ao uso em cenários de depuração e diagnóstico. A maioria dos códigos de produção deve continuar a ser executada e continuar a relatar eventos mesmo que um evento ETW não possa ser gravado, portanto, os builds de versão geralmente devem ignorar o código de erro.

Comentários

Essa API não é útil e não deve ser usada.

  • A maioria das ferramentas de análise do ETW não dá suporte corretamente a eventos somente cadeia de caracteres sem um manifesto.
  • Sem um manifesto, informações importantes sobre o evento (por exemplo, o nome do provedor, a ID do evento e o nome do evento) não estão disponíveis para que os eventos resultantes sejam difíceis de usar mesmo quando a ferramenta de análise dá suporte a eventos somente cadeia de caracteres.
  • Com um manifesto, essa função se comporta quase exatamente como o código de um evento baseado em manifesto com um único campo de cadeia de caracteres. No entanto, o evento baseado em manifesto é mais compatível com as ferramentas de análise de rastreamento. Além disso, o código gerado por MC.exe para um evento com um único campo de cadeia de caracteres é mais eficiente do que a função EventWriteString .

Em vez de usar essa API, considere as seguintes alternativas:

  • Use TraceLoggingProvider.h para gravar eventos que são bem compatíveis com as ferramentas de análise do ETW, funcionam sem um manifesto e incluem metadados como nome do provedor e nome do evento.
  • Escreva um manifesto de instrumentação. Crie um evento simples com um único valor de cadeia de caracteres terminada em NUL. Você pode escrever e coletar eventos mesmo sem um manifesto. Você só precisará do manifesto para decodificar o rastreamento coletado.

EventWriteString grava um evento com uma carga de dados que consiste na cadeia de caracteres especificada. Essa API é quase equivalente ao seguinte código:

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

O evento resultante é o mesmo que qualquer outro evento gerado pelo EventWrite , exceto que o evento resultante tem o sinalizador EVENT_HEADER_FLAG_STRING_ONLY definido (consulte EVENT_HEADER para obter informações sobre sinalizadores de evento).

Observe que o evento é gravado com ID, Versão, Opcode, Tarefa e Canal definidos como 0.

Observe que o evento usa a ID de atividade do thread atual.

As ferramentas de análise do ETW que estão cientes do sinalizador EVENT_HEADER_FLAG_STRING_ONLY podem extrair o valor da cadeia de caracteres mesmo quando o decodificador não consegue localizar nenhuma outra informação de decodificação para o provedor de eventos. No entanto, sem um manifesto, as ferramentas não poderão determinar o nome do provedor do evento.

Requisitos

   
Cliente mínimo com suporte Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho evntprov.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

EventWrite

TraceLoggingProvider.h