Criar consultas do Get-WinEvent com o FilterHashtable

Artigo
03/19/2024

Este exemplo só se aplica a plataformas Windows.

Para ler a postagem original do blog da Equipe de Scripts de 3 de junho de 2014, consulte Usar FilterHashTable para filtrar o log de eventos com o PowerShell.

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

Quando você trabalha com logs de eventos grandes, não é eficiente enviar objetos pelo pipeline para um Where-Object comando. Antes do PowerShell 6, o Get-EventLog cmdlet era outra opção para obter dados de log. Por exemplo, os seguintes comandos são ineficientes para filtrar os logs do 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 de blog sobre enumeração

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

Pares chave-valor da tabela de hash

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

Se os pares chave-valor estiverem na mesma linha, eles devem 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 pares chave-valor do parâmetro FilterHashtable. A consulta concluída inclui LogName, ProviderName, Keywords, ID e Level.

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

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

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

A <named-data> chave representa um campo de dados de evento nomeado. Por exemplo, o evento Perflib 1008 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'}

Nota

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

Criando uma consulta com uma tabela de hash

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

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

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

Continue a criar a tabela de hash com a chave ProviderName . Normalmente, o ProviderName é o nome que aparece no campo Source 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'
}

Nota

Para alguns provedores de eventos, o ProviderName correto pode ser obtido procurando na guia Detalhes em Propriedades do evento. Por exemplo, eventos em que o campo Source mostra Defrag, o ProviderName correto é Microsoft-Windows-Defrag.

Se sua consulta precisar obter dados de logs de eventos arquivados, use a tecla Caminho . O valor Path especifica o caminho completo para o arquivo de log. Para obter mais informações, consulte a postagem do blog da Equipe de Scripts , Usar o PowerShell para analisar logs de eventos salvos em busca de erros.

Usando valores enumerados em uma tabela de hash

Palavras-chave é a próxima chave na tabela de hash. O tipo de dados Palavras-chave é uma matriz do [long] tipo de valor que contém um grande número. Use o seguinte comando para localizar 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. O Visualizador de Eventos do Windows exibe as palavras-chave como cadeias de caracteres, mas são valores enumerados. Na tabela de hash, se você usar a chave Keywords com um valor de cadeia de caracteres, uma mensagem de erro será exibida.

Abra o Visualizador de Eventos do Windows e, no painel Ações, clique em Filtrar log 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 comando a seguir para exibir os nomes das StandardEventKeywords propriedades.

[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 são documentados no .NET Framework. Para obter mais informações, consulte Enumeração StandardEventKeywords .

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

Nome	Valor
AuditoriaFalha	4503599627370496
AuditSuccess	9007199254740992
CorrelaçãoDica2	18014398509481984
EventLogClassic	36028797018963968
M²	2251799813685248
WdiDiagnóstico	1125899906842624
WdiContext	562949953421312
Tempo de resposta	281474976710656
None	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
}

Palavras-chave: valor da propriedade estática (opcional)

A chave Keywords é enumerada, mas você pode usar um nome de propriedade estática 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 de Evento

Para obter dados mais específicos, os resultados da consulta são filtrados por ID do Evento. A ID do Evento é referenciada na tabela de hash como a ID da chave e o valor é uma ID de Evento específica. O Visualizador de Eventos do Windows exibe a ID do Evento. Este exemplo usa a Id de 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 eventos que são erros, use a tecla Level . O Visualizador de Eventos do Windows exibe o Level como valores de cadeia de caracteres, mas eles são valores enumerados. Na tabela de hash, se você usar a chave Level com um valor de cadeia de caracteres, uma mensagem de erro será exibida.

Level tem valores como Error, Warning ou Informational. Use o comando a seguir para exibir os nomes das StandardEventLevel propriedades.

[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 são documentados no .NET Framework. Para obter mais informações, consulte Enumeração StandardEventLevel.

Os nomes e valores enumerados da chave Level são os seguintes:

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

A tabela de hash para a consulta concluída inclui a chave, Level 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 Level é 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__ .