Função EventWriteEx (evntprov.h)
Grava um evento ETW com uma ID de atividade, uma ID de atividade relacionada opcional, filtros de sessão e opções especiais.
Sintaxe
ULONG EVNTAPI EventWriteEx(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG64 Filter,
[in] ULONG Flags,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[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] Filter
Um valor de máscara de bits de 64 bits. Cada bit definido indica que esse evento deve ser excluído de uma sessão de rastreamento específica.
O parâmetro Filter é usado com provedores de eventos que executam a filtragem de eventos personalizada com base no FilterData de EnableCallback.
Defina Filtro como zero se você não der suporte a filtros de evento personalizados ou se o evento deve ser gravado em todas as sessões de rastreamento. Caso contrário, defina Filtrar como o OR bit a bit dos identificadores de sessões que NÃO devem receber o evento.
[in] Flags
Defina Sinalizadores como zero para manipulação normal de eventos.
Defina Sinalizadores como uma combinação de valores de EVENT_WRITE_FLAG para manipulação de eventos especiais.
EVENT_WRITE_FLAG_INPRIVATE (0x2)
Indica que esse evento deve ser excluído de qualquer agente que tenha definido a opção EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE .
[in, optional] ActivityId
Um ponteiro opcional para uma ID de atividade de 128 bits para esse evento. Se isso não for NULL, EventWriteEx usará o valor especificado para a ID de atividade do evento. Se for NULL, EventWriteEx usará a ID de atividade do thread atual.
As ferramentas de processamento de rastreamento podem usar a ID de atividade do evento para organizar eventos em grupos chamados atividades. Para obter informações adicionais sobre a ID da atividade, consulte EventActivityIdControl.
[in, optional] RelatedActivityId
Um ponteiro opcional para uma ID de atividade de 128 bits que é o pai da atividade desse evento. Se isso não for NULL, EventWriteEx usará o valor especificado para a ID de atividade relacionada do evento. Se for NULL, o evento não terá uma ID de atividade relacionada. A ID da atividade relacionada geralmente é definida no evento START da atividade (o primeiro evento da atividade, registrado com Opcode = START).
As ferramentas de processamento de rastreamento podem usar a ID de atividade relacionada do evento para determinar a relação entre as atividades, por exemplo, a atividade relacionada é o pai da atividade recém-iniciada. Para obter informações adicionais sobre a ID da atividade relacionada, consulte EventActivityIdControl.
[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.
Retornar valor
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
A maioria dos provedores de eventos não chamará EventWriteEx diretamente. Em vez disso, a maioria dos provedores de eventos é implementada usando uma estrutura ETW que encapsula as chamadas para EventRegister, EventWriteEx e EventUnregister. Por exemplo, você pode escrever um manifesto de evento e 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.
EventWriteEx roteará o evento para as sessões de rastreamento apropriadas com base no ProviderId (determinado 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 EventWriteEx.
Um provedor pode definir filtros que uma sessão usa para filtrar eventos com base em dados de evento. Os filtros principais são baseados no nível e nas palavras-chave. Os provedores de eventos podem dar suporte a filtros mais complexos. O provedor de eventos pode receber informações de filtro do parâmetro FilterData de EnableCallback. O provedor pode avaliar o filtro e usar o parâmetro Filter de EventWriteEx para indicar que determinadas sessões de rastreamento não passaram pelo filtro e, portanto, não devem receber o evento.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 7 [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 R2 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | evntprov.h |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |