Introdução às consultas de log no Azure Monitor

Neste tutorial, você aprenderá a escrever consultas de log no Azure Monitor. O artigo mostra como:

• Entender a estrutura de consulta.
• Classificar os resultados da consulta.
• Filtrar resultados da consulta.
• Especificar um intervalo de tempo.
• Selecionar quais campos serão incluídos nos resultados.
• Definir e usar campos personalizados.
• Agregar e agrupar resultados.

Para obter um tutorial sobre como usar o Log Analytics no portal do Azure, confira Introdução ao Log Analytics do Azure Monitor.

Para obter mais informações sobre consultas de log no Azure Monitor, confira Visão geral de consultas de log no Azure Monitor.

Veja uma versão em vídeo deste tutorial:

Permissões necessárias

Você deve ter permissões Microsoft.OperationalInsights/workspaces/query/*/read para os workspaces do Log Analytics que você consulta, conforme fornecido pela função interna Leitor do Log Analytics, por exemplo.

Escrever uma nova consulta

As consultas podem começar com um nome de tabela ou com o comando search. É melhor iniciar com um nome de tabela porque ele define um escopo claro da consulta. Isso também aprimora o desempenho da consulta e a relevância dos resultados.

Consultas baseadas em tabela

O Azure Monitor organiza os dados de log em tabelas, cada uma composta por várias colunas. Todas as tabelas e colunas são mostradas no painel de esquema no Log Analytics, no portal do Analytics. Identifique uma tabela que você está interessado e, em seguida, vamos ver alguns dados:

SecurityEvent
| take 10

A consulta acima retorna 10 resultados da tabela SecurityEvent, sem nenhuma ordem específica. Esse modo comum de dar uma olhada rápida em uma tabela ajuda a entender a estrutura e o conteúdo. Vamos examinar como ele é criado:

• A consulta é iniciada com o nome da tabela SecurityEvent, que define o escopo da consulta.

• O caractere de barra vertical (|) separa os comandos, portanto, a saída do primeiro comando é a entrada do próximo. Você pode adicionar qualquer número de elementos conectados.

• Após o caractere de barra vertical vem o operador take.

  Poderíamos executar a consulta mesmo sem adicionar | take 10. O comando ainda seria válido, mas ele poderia retornar até 30 mil resultados.

Take

Use o operador take para ver uma pequena amostra de registros retornando os registros até o número especificado. Os resultados selecionados são arbitrários e são exibidos em nenhuma ordem específica. Se você precisar retornar resultados em uma ordem específica, use os operadores sort e top.

Consultas de pesquisa

As consultas de pesquisa são menos estruturadas. Elas são mais adequadas para encontrar registros que incluem um valor específico em uma das colunas:

search in (SecurityEvent) "Cryptographic"
| take 10

Esta consulta pesquisa a tabela SecurityEvent em busca de registros que contenham a frase "Criptográfico.“ Desses registros, 10 registros são devolvidos e exibidos. Se você omitir a parte in (SecurityEvent) e executar apenas search "Cryptographic", a pesquisa percorrerá todas as tabelas. O processo demoraria mais e seria menos eficiente.

Classificar e superior

Esta seção descreve os operadores sort e top os respectivos argumentos desc e asc. Embora take seja útil para obter alguns registros, não é possível selecionar nem classificar os resultados em qualquer ordem específica. Para ter uma exibição ordenada, use sort e top.

Desc e asc

Desc

Use o argumento desc para classificar registros em ordem decrescente. Decrescente é a ordem de classificação padrão para sort e top e, portanto, você geralmente pode omitir o argumento desc.

Por exemplo, os dados retornados pelas duas seguintes consultas são classificados pela coluna TimeGenerated, em ordem decrescente:

• SecurityEvent	
  | sort by TimeGenerated desc
  

• SecurityEvent	
  | sort by TimeGenerated
  

Asc

Para fazer a classificação em ordem ascendente, especifique asc.

Sort

Você pode usar o operador sort. sort classifica os resultados da consulta pela coluna especificada. No entanto, sort não limita o número de registros retornados pela consulta.

Por exemplo, a consulta a seguir retorna todos os registros disponíveis para a tabela SecurityEvent, que tem até, no máximo, 30.000 registros e os classifica pela coluna TimeGenerated.

SecurityEvent	
| sort by TimeGenerated

A consulta anterior pode retornar um excesso de resultados. Além disso, os resultados também pode levar algum tempo para serem retornados. A consulta classifica a tabela SecurityEvent inteira pela coluna TimeGenerated. O portal do Analytics limita a exibição a apenas 30 mil registros. Essa abordagem não é ideal. A melhor maneira de obter apenas os registros mais recentes é usar o operador top.

TOP

Use o operador top para classificar a tabela inteira no lado do servidor e retornar apenas os principais registros.

Por exemplo, a seguinte consulta retorna os dez registros mais recentes:

SecurityEvent
| top 10 by TimeGenerated

A saída se parece com este exemplo.

O operador where: filtragem de acordo com uma condição

Filtros, conforme indicado pelo seu nome, filtram os dados por uma condição específica. A filtragem é a maneira mais comum de limitar os resultados da consulta a informações relevantes.

Para adicionar um filtro a uma consulta, use o operador where seguido por uma ou mais condições. Por exemplo, a consulta a seguir retorna apenas registros de SecurityEvent em que Level equals _8:

SecurityEvent
| where Level == 8

Ao escrever condições de filtro, você pode usar as seguintes expressões:

Para filtrar por várias condições, você pode usar uma das seguintes abordagens:

Usar and, conforme mostrado aqui:

SecurityEvent
| where Level == 8 and EventID == 4672

Redirecionar vários elementos where, um após o outro, conforme mostrado aqui:

SecurityEvent
| where Level == 8 
| where EventID == 4672

Especifique um intervalo de tempo

Você pode especificar um intervalo de tempo usando o seletor de tempo ou um filtro de tempo.

Usar o seletor de tempo

O seletor de tempo é mostrado próximo ao botão Executar e indica que você está consultando registros somente das últimas 24 horas. Esse intervalo de tempo padrão é aplicado a todas as consultas. Para obter registros somente da última hora, selecione Última hora e execute a consulta novamente.

Adicionar um filtro de tempo à consulta

Você também pode definir seu próprio intervalo de tempo adicionando um filtro de tempo à consulta. A adição de um filtro de tempo substitui o intervalo de tempo selecionado no seletor de tempo.

É melhor colocar o filtro de tempo logo após o nome da tabela:

SecurityEvent
| where TimeGenerated > ago(30m) 
| where toint(Level) >= 10

No filtro de tempo anterior, ago(30m) corresponde a "30 minutos atrás". Essa consulta retorna registros apenas dos últimos 30 minutos (expressos como, por exemplo, 30 m). Outras unidades de tempo incluem dias (por exemplo, 2d) e segundos (por exemplo, 10s).

Usar project e extend para selecionar e computar colunas

Use project para selecionar colunas específicas a serem incluídas nos resultados:

SecurityEvent 
| top 10 by TimeGenerated 
| project TimeGenerated, Computer, Activity

O exemplo anterior gera a seguinte saída:

Você também pode usar project para renomear colunas e definir novos. O próximo exemplo usa project para fazer o seguinte:

• Selecione apenas o Computer e TimeGenerated colunas originais.
• Exibir a coluna Activity como EventDetails.
• Criar uma nova coluna chamada EventCode. A função substring() é usada para obter apenas os quatro primeiros caracteres do campo Activity.

SecurityEvent
| top 10 by TimeGenerated 
| project Computer, TimeGenerated, EventDetails=Activity, EventCode=substring(Activity, 0, 4)

Use extend para manter todas as colunas originais no conjunto de resultados e definir outras. A consulta a seguir usa extend para adicionar a coluna EventCode. Essa coluna pode não ser exibida no final dos resultados da tabela. Você precisaria expandir os detalhes de um registro para vê-la.

SecurityEvent
| top 10 by TimeGenerated
| extend EventCode=substring(Activity, 0, 4)

Usar summarize para agregar grupos de linhas

Use summarize para identificar grupos de registros de acordo com uma ou mais colunas e para aplicar agregações a eles. O uso mais comum de summarize é a count, que retorna o número de resultados em cada grupo.

A consulta a seguir examina todos os Perf registros de última hora, agrupa-os por ObjectNamee conta os registros em cada grupo:

Perf
| where TimeGenerated > ago(1h)
| summarize count() by ObjectName

Às vezes, faz sentido para definir grupos por várias dimensões. Cada combinação exclusiva desses valores define um grupo separado:

Perf
| where TimeGenerated > ago(1h)
| summarize count() by ObjectName, CounterName

Outro uso comum é realizar cálculos matemáticos ou estatísticos em cada grupo. O exemplo a seguir calcula o CounterValue médio para cada computador:

Perf
| where TimeGenerated > ago(1h)
| summarize avg(CounterValue) by Computer

Infelizmente, os resultados dessa consulta não têm sentido, pois combinamos diferentes contadores de desempenho. Para tornar os resultados mais significativos, calcule a média separadamente para cada combinação de CounterName e Computer:

Perf
| where TimeGenerated > ago(1h)
| summarize avg(CounterValue) by Computer, CounterName

Resumir por uma coluna de hora

O agrupamento dos resultados também pode ser baseado em uma coluna de hora ou em outro valor contínuo. O simples resumo de by TimeGenerated, criaria grupos para cada milissegundo ao longo do intervalo de tempo, pois esses são valores exclusivos.

Para criar grupos com base em valores contínuos, é melhor dividir o intervalo em unidades gerenciáveis usando bin. A consulta a seguir analisa Perf registros que medem a memória livre (Available MBytes) em um computador específico. Ela calcula o valor médio de cada período de uma hora nos últimos sete dias:

Perf 
| where TimeGenerated > ago(7d)
| where Computer == "ContosoAzADDS2" 
| where CounterName == "Available MBytes" 
| summarize avg(CounterValue) by bin(TimeGenerated, 1h)

Para esclarecer a saída, você pode selecioná-la para ser exibida como um gráfico de tempo que mostre a memória disponível ao longo do tempo.

Perguntas frequentes

Esta seção fornece respostas para perguntas comuns.

Por que estou vendo registros duplicados nos logs do Azure Monitor?

Ocasionalmente, pode haver registros duplicados nos logs do Azure Monitor. Normalmente, essa duplicação depende de uma das duas condições a seguir:

• Os componentes no pipeline têm novas tentativas para garantir a entrega confiável no destino. De vez em quando, essa capacidade pode resultar em duplicatas para um pequeno percentual de itens de telemetria.
• Se os registros duplicados vierem de uma máquina virtual, você pode ter os agentes do Log Analytics e do Azure Monitor instalados. Se você ainda precisar do agente do Log Analytics instalado, configure o workspace do Log Analytics para não coletar mais dados que também estão sendo coletados pela regra de coleta de dados usada pelo Agente do Azure Monitor.

Próximas etapas

• Para saber mais sobre como usar dados de cadeia de caracteres em uma consulta de log, confira Trabalhar com cadeias de caracteres nas consultas de log no Azure Monitor.
• Para saber mais sobre como agregar dados em uma consulta de log, confira Agregações avançadas nas consultas de log no Azure Monitor.
• Para saber como unir dados de várias tabelas, confira Junções nas consultas de log do Azure Monitor.
• Obtenha a documentação sobre toda a Linguagem de Consulta Kusto na referência da linguagem KQL.