Criando consultas Get-WinEvent com FilterHashtable

Artigo
05/09/2024

Este exemplo só se aplica a plataformas Windows.

Para ler a postagem de blog original do Scripting Guy de 3 de junho de 2014, confira Use o FilterHashTable para filtrar log de eventos com o PowerShell.

Este artigo é um trecho da postagem do blog original e explica como usar o parâmetro FilterHashtable do cmdlet Get-WinEvent para filtrar logs de eventos. O cmdlet Get-WinEvent do PowerShell é um método poderoso de filtragem de logs de eventos e diagnósticos do Windows. Quando uma consulta Get-WinEvent usa o parâmetro FilterHashtable, seu desempenho é aprimorado.

Quando você trabalha com grandes logs de eventos, não é eficiente enviar objetos pelo pipeline para um comando Where-Object. Antes do PowerShell 6, o cmdlet Get-EventLog era outra opção para obter dados de log. Por exemplo, os comandos a seguir são ineficientes para filtrar os logs Microsoft-Windows-Defrag:

Get-EventLog -LogName Application | Where-Object Source -Match defrag

Get-WinEvent -LogName Application | Where-Object { $_.ProviderName -Match 'defrag' }

O comando a seguir usa uma tabela de hash que melhora o desempenho:

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='*defrag'
}

Postagens no blog sobre enumeração

Este artigo apresenta informações sobre como usar os valores enumerados em uma tabela de hash. Para obter mais informações sobre a enumeração, leia as postagens de blog de Scripting Guy. Para criar uma função que retorne valores enumerados, confira Enumerações e valores. Para obter mais informações, confira a série de postagens de blog sobre enumeração de Scripting Guy.

Pares chave-valor da tabela de hash

Para criar consultas eficientes, use o cmdlet Get-WinEvent com o parâmetro FilterHashtable. O FilterHashtable aceita uma tabela de hash como filtro para obter informações específicas de logs de eventos do Windows. Uma tabela de hash usa pares chave-valor. Para obter informações sobre tabelas de hash, confira about_Hash_Tables.

Se os pares chave-valor estiverem na mesma linha, eles deverão ser separados por um ponto e vírgula. Se cada par chave-valor estiver em uma linha separada, o ponto e vírgula não será necessário. Por exemplo, este artigo coloca pares chave-valor em linhas separadas e não usa ponto e vírgula.

Este exemplo usa vários parâmetros FilterHashtable dos pares chave-valor. A consulta completa inclui LogName, ProviderName, Palavras-chave, ID e Nível.

Os pares chave-valor aceitos são mostrados na tabela a seguir e incluídos na documentação do parâmetro Get-WinEventFilterHashtable.

A tabela a seguir exibe os nomes de chave, os tipos de dados e se os caracteres curinga são aceitos para um valor de dados.

Nome da chave	Tipo de dados de valor	Aceita caracteres curinga?
LogName	`<String[]>`	Sim
ProviderName	`<String[]>`	Sim
Caminho	`<String[]>`	Não
Palavras-chave	`<Long[]>`	Não
ID	`<Int32[]>`	Não
Nível	`<Int32[]>`	Não
StartTime	`<DateTime>`	Não
EndTime	`<DateTime>`	Não
UserID	`<SID>`	Não
Dados	`<String[]>`	Não
`<named-data>`	`<String[]>`	Não

A chave <named-data> representa um campo de dados de evento nomeado. Por exemplo, o evento 1008 do Perflib pode conter os seguintes dados de evento:

<EventData>
  <Data Name="Service">BITS</Data>
  <Data Name="Library">C:\Windows\System32\bitsperf.dll</Data>
  <Data Name="Win32Error">2</Data>
</EventData>

Você pode consultar esses eventos usando o seguinte comando:

Get-WinEvent -FilterHashtable @{LogName='Application'; 'Service'='Bits'}

Observação

A capacidade de consultar <named-data> foi adicionada no PowerShell 6.

Como criar uma consulta com uma tabela de hash

Para verificar os resultados e solucionar problemas, convém criar a tabela de hash com um par chave-valor de cada vez. A consulta obtém dados de log do Aplicativo. A tabela de hash é equivalente a Get-WinEvent -LogName Application.

Para começar, crie uma consulta Get-WinEvent. Use o par chave-valor do parâmetro FilterHashtable com a chave LogName e o valor Aplicativo.

Get-WinEvent -FilterHashtable @{
   LogName='Application'
}

Continue a criar a tabela de hash com a chave ProviderName. Geralmente, o ProviderName é o nome exibido no campo Fonte no Visualizador de Eventos do Windows. Por exemplo, .NET Runtime na captura de tela a seguir:

Imagem das fontes do Visualizador de Eventos do Windows

Atualize a tabela de hash e inclua o par chave-valor com a chave, ProviderName, e o valor, .NET Runtime.

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
}

Observação

Para alguns provedores de eventos, o ProviderName correto pode ser obtido observando a guia Detalhes em Propriedades do Evento. Por exemplo, eventos em que o campo Origem mostra Defrag, o ProviderName correto é Microsoft-Windows-Defrag.

Se sua consulta precisar obter dados de logs de eventos arquivados, use a chave Caminho. O valor Caminho especifica o caminho completo para o arquivo de log. Para obter mais informações, confira a postagem no blog do Scripting Guy, Use o PowerShell para analisar erros de log de eventos salvos.

Usando valores enumerados em uma tabela de hash

A chave Palavras-chave é a próxima na tabela de hash. O tipo de dados Palavras-chave é uma matriz do tipo de valor [long] que contém um número grande. Use o seguinte comando para encontrar o valor máximo de [long]:

[long]::MaxValue

9223372036854775807

Para a chave Palavras-chave, o PowerShell usa um número, não uma cadeia de caracteres, como Segurança. Embora sejam valores enumerados, o Visualizador de Eventos do Windows exibe as Palavras-chave como cadeias de caracteres. Na tabela de hash, se você usar a chave Palavras-chave com um valor de cadeia de caracteres, será exibida uma mensagem de erro.

Abra o Visualizador de Eventos do Windows e, no painel Ações, clique em Filtrar o registro atual. O menu suspenso Palavras-chave exibe as palavras-chave disponíveis, conforme mostrado na captura de tela a seguir:

Imagem das palavras-chave do Visualizador de Eventos do Windows

Use o seguinte comando para exibir os nomes das propriedades StandardEventKeywords.

[System.Diagnostics.Eventing.Reader.StandardEventKeywords] |
    Get-Member -Static -MemberType Property

   TypeName: System.Diagnostics.Eventing.Reader.StandardEventKeywords
Name             MemberType Definition
—-             ———- ———-
AuditFailure     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
AuditSuccess     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
CorrelationHint  Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
CorrelationHint2 Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
EventLogClassic  Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
None             Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
ResponseTime     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
Sqm              Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
WdiContext       Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
WdiDiagnostic    Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…

Os valores enumerados estão documentados no .NET Framework. Para obter mais informações, confira Enumeração StandardEventKeywords.

Os nomes e valores enumerados das Palavras-chave são os seguintes:

Nome	Valor
AuditFailure	4503599627370496
AuditSuccess	9007199254740992
CorrelationHint2	18014398509481984
EventLogClassic	36028797018963968
Sqm	2251799813685248
WdiDiagnostic	1125899906842624
WdiContext	562949953421312
ResponseTime	281474976710656
Nenhum	0

Atualize a tabela de hash e inclua o par chave-valor com a chave Palavras-chave e o valor de enumeração EventLogClassic, 36028797018963968.

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=36028797018963968
}

Valor da propriedade estática das palavras-chave (opcional)

A chave Palavras-chave é enumerada, mas é possível usar um nome de propriedade estático na consulta da tabela de hash. Em vez de usar a cadeia de caracteres retornada, o nome da propriedade deve ser convertido em um valor com a propriedade Value__ .

Por exemplo, o script a seguir usa a propriedade Value__ .

$C = [System.Diagnostics.Eventing.Reader.StandardEventKeywords]::EventLogClassic
Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=$C.Value__
}

Filtragem por ID do evento

Para obter dados mais específicos, os resultados da consulta são filtrados por ID do evento. O ID do evento é referenciado na tabela de hash como o ID chave e o valor é um ID de evento específico. O Visualizador de Eventos do Windows exibe o ID do evento. Este exemplo usa o ID do evento 1023.

Atualize a tabela de hash e inclua o par chave-valor com a chave, ID e o valor 1023.

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=36028797018963968
   ID=1023
}

Filtragem por nível

Para refinar ainda mais os resultados e incluir apenas os eventos de erros, use a chave Nível. Embora seja um valor enumerado, o Visualizador de Eventos do Windows exibe o Nível como valores de cadeias de caracteres. Na tabela de hash, se você usar a chave Nível com um valor de cadeia de caracteres, será exibida uma mensagem de erro.

O Nível tem valores como Erro, Aviso ou Informativo. Use o seguinte comando para exibir os nomes das propriedades StandardEventLevel.

[System.Diagnostics.Eventing.Reader.StandardEventLevel] |
    Get-Member -Static -MemberType Property

   TypeName: System.Diagnostics.Eventing.Reader.StandardEventLevel

Name          MemberType Definition
----          ---------- ----------
Critical      Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Critical {get;}
Error         Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Error {get;}
Informational Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Informational {get;}
LogAlways     Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel LogAlways {get;}
Verbose       Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Verbose {get;}
Warning       Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Warning {get;}

Os valores enumerados estão documentados no .NET Framework. Para obter mais informações, confira Enumeração de StandardEventKeywords.

Os nomes e valores enumerados de Nível são os seguintes:

Nome	Valor
Detalhado	5
Informativo	4
Aviso	3
Erro	2
Crítico	1
LogAlways	0

A tabela de hash para a consulta completa inclui a chave do Nível e o valor 2.

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=36028797018963968
   ID=1023
   Level=2
}

Propriedade estática de nível na enumeração (opcional)

A chave do Nível é enumerada, mas você pode usar um nome de propriedade estático na consulta da tabela de hash. Em vez de usar a cadeia de caracteres retornada, o nome da propriedade deve ser convertido em um valor com a propriedade Value__ .