Criar consultas do Get-WinEvent com o FilterHashtable
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-WinEvent FilterHashtable.
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__ .
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__
}
