Função EventWrite (evntprov.h)

Artigo
08/23/2023

Grava um evento ETW que usa a ID de atividade do thread atual.

Sintaxe

ULONG EVNTAPI EventWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Parâmetros

[in] RegHandle

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

[in] EventDescriptor

EVENT_DESCRIPTOR com informações de evento (metadados), incluindo ID, Versão, Nível, Palavra-chave, Canal, Opcode e Tarefa.

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.

[in] UserDataCount

Número de estruturas de EVENT_DATA_DESCRIPTOR no UserData. O número máximo é 128.

[in, optional] UserData

Uma matriz de estruturas EVENT_DATA_DESCRIPTOR UserDataCount que descrevem os dados a serem incluídos no evento. UserData poderá ser NULL se UserDataCount for zero.

Cada EVENT_DATA_DESCRIPTOR descreve um bloco de memória a ser incluído no evento. Os blocos especificados serão concatenados em ordem sem preenchimento ou alinhamento para formar o conteúdo do evento. Se estiver usando a decodificação baseada em manifesto, o conteúdo do evento deverá corresponder ao layout especificado no modelo associado ao evento no manifesto.

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 as E/Ss de disco não estão ocorrendo rápido o suficiente. Isso acontece quando o disco está lento e o tráfego de eventos é pesado. Eventualmente, não há mais buffers livres (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 relatando 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

A maioria dos provedores de eventos não chamará EventWrite diretamente. Em vez disso, a maioria dos provedores de eventos é implementada usando uma estrutura ETW que encapsula as chamadas para EventRegister, EventWrite e EventUnregister. Por exemplo, você pode escrever um manifesto de evento e, em seguida, usar o Compilador de Mensagens para gerar código C/C++ para os eventos ou pode usar TraceLogging para evitar a necessidade de um manifesto.

EventWrite roteará o evento para as sessões de rastreamento apropriadas com base na ProviderId (determinada do RegHandle), Nível, Palavra-chave e outras características do evento. Se nenhuma sessão de rastreamento estiver gravando esse evento, essa função não fará nada e retornará ERROR_SUCCESS.

Para reduzir o impacto no desempenho de eventos que não são registrados por nenhuma sessão de rastreamento, você pode chamar EventEnabled para determinar se qualquer sessão de rastreamento está gravando seu evento antes de preparar os dados e chamar EventWrite.

EventWrite define a ID de atividade do evento como a ID de atividade do thread atual. EventWrite não inclui uma ID de atividade relacionada no evento. Para especificar uma ID de atividade diferente ou adicionar uma ID de atividade relacionada, use EventWriteTransfer.

EventWrite é equivalente a EventWriteEx com 0 para Filter, 0 para Flags, NULL para ActivityId e NULL para RelatedActivityId.

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