Criando consultas Get-WinEvent com FilterHashtable
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 key-value aceitos são mostrados na tabela a seguir e estão incluídos na documentação do Get-WinEvent FilterHashtable.
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__ .
Por exemplo, o script a seguir usa a propriedade Value__ .
$C = [System.Diagnostics.Eventing.Reader.StandardEventLevel]::Informational
Get-WinEvent -FilterHashtable @{
LogName='Application'
ProviderName='.NET Runtime'
Keywords=36028797018963968
ID=1023
Level=$C.Value__
}
