Funções nas consultas de log no Azure Monitor

Uma função é uma consulta de log no Azure Monitor que pode ser usada em outras consultas de log, como se fosse um comando. Você pode usar as funções para oferecer soluções a diferentes clientes e reutilizar a lógica de consulta no seu próprio ambiente. Este artigo descreve como usá-las e como criar as suas.

Permissões necessárias

• Para exibir ou usar as funções, você precisa de permissões Microsoft.OperationalInsights/workspaces/query/*/read para o espaço de trabalho do Log Analytics, conforme fornecido pela função interna Leitor da Análise de Logs, por exemplo.

• Para criar ou editar funções, você precisa de permissões microsoft.operationalinsights/workspaces/savedSearches/write para o espaço de trabalho do Log Analytics, conforme fornecido pela função interna Leitor da Análise de Logs, por exemplo.

Tipos de funções

Há dois tipos de funções no Azure Monitor:

• Funções de solução: são predefinidas e vêm incluídas no Azure Monitor. Estão disponíveis em todos os workspaces do Log Analytics e não podem ser modificadas.
• Funções de workspace: são instaladas em um workspace específico do Log Analytics. Os usuários podem alterar e controlá-las.

Exibir funções

Você pode ver funções de solução e de workspace na guia Funções, que fica no painel esquerdo de um workspace do Log Analytics. Use Filtrar para filtrar as funções incluídas na lista. Use Agrupar por para alterar o agrupamento. Insira uma cadeia de caracteres na caixa Pesquisar para localizar uma função específica. Passe o mouse sobre uma função para ver detalhes sobre ela, incluindo uma descrição e os parâmetros.

Use uma função

Para usar uma função em uma consulta, digite o nome dela com valores para qualquer parâmetro, assim como você digitaria em um comando. A saída da função pode ser retornada como resultado ou canalizada para outro comando.

Adicione uma função à consulta atual clicando duas vezes em seu nome ou passando o mouse sobre ela e selecionando Usar no editor. As funções no workspace também são incluídas no IntelliSense à medida que você digita uma consulta.

Se uma consulta precisa de parâmetros, use a sintaxe function_name(param1,param2,...) para informá-los.

Criar uma função

Para criar uma função da consulta atual no editor, selecione Salvar>Salvar como função.

Para criar uma função com o Log Analytics no portal do Azure, clique em Salvar. Depois, dê as informações na seguinte tabela:

Configuração	Descrição
Nome da função	Nome da função. O nome não pode ter espaço ou caracteres especiais. Também não pode começar com um sublinhado (_), porque esse caractere é reservado para funções de solução.
Categoria herdada	Categoria definida pelo usuário para ajudar a filtrar e agrupar funções.
Salvar como grupo de computadores	Salve a consulta como um grupo de computadores.
Parâmetros	Adicione um parâmetro para cada variável na função que requer um valor quando ela é usada. Para saber mais, confira Parâmetros de função.

Parâmetros de função

Ao chamar uma função, você pode adicionar parâmetros a ela para informar valores de determinadas variáveis. Como resultado, é possível usar a mesma função em consultas diferentes. Cada uma informa valores diferentes para os parâmetros. São as seguintes propriedades que definem os parâmetros:

Configuração	Descrição
Type	Tipo de dados para o valor.
Nome	Nome do parâmetro. É necessário usar esse nome na consulta para substitui-lo pelo valor do parâmetro.
Valor padrão	Valor a ser usado no parâmetro se um valor não for fornecido.

Os parâmetros são ordenados conforme são criados. Aqueles que não têm valor padrão são posicionados na frente dos que têm.

Observação

Os recursos clássicos do Application Insights não suportam funções parametrizadas. Se você tiver um recurso do Application Insights baseado em espaço de trabalho, poderá criar funções parametrizadas no espaço de trabalho do Log Analytics. Para obter informações sobre como migrar seu recurso Application Insights Clássico para um recurso baseado em espaço de trabalho, confira Migrar para os recursos do Application Insights baseados em espaço de trabalho.

Trabalhar com o código de função

Você pode exibir o código de uma função para obter informações sobre como ela funciona ou para modificar o código de uma função do workspace. Selecione Carregar o código de função para adicionar o código de função à consulta atual no editor.

Se você adiciona o código de função a uma consulta vazia ou à primeira linha de uma consulta existente, o nome da função é adicionado à guia. Uma função de workspace habilita a edição dos detalhes da função.

Editar uma função

Edite as propriedades ou o código de uma função criando uma consulta. Passe o mouse sobre o nome da função e selecione Carregar código da função. Faça as alterações desejadas no código e selecione Salvar. Depois, selecione Editar detalhes da função. Faça as alterações desejadas nas propriedades e nos parâmetros da função e selecione Salvar.

Exemplo

A função de amostra a seguir retorna todos os eventos que estejam no log de atividades do Azure desde uma determinada data e que coincidam com uma categoria específica.

Comece com a consulta a seguir usando valores codificados para verificar se a consulta funciona conforme o esperado.

AzureActivity
| where CategoryValue == "Administrative"
| where TimeGenerated > todatetime("2021/04/05 5:40:01.032 PM")

Em seguida, substitua os valores codificados por nomes de parâmetro. Depois, salve a função selecionando Salvar>Salvar como função.

AzureActivity
| where CategoryValue == CategoryParam
| where TimeGenerated > DateParam

Insira os seguintes valores nas propriedades da função:

Propriedade	Valor
Nome da função	AzureActivityByCategory
Categoria herdada	Funções de demonstração

Defina os seguintes parâmetros a seguir antes de salvar a função:

Tipo	Nome	Valor padrão
string	CategoryParam	"Administrativo"
DATETIME	DateParam

Crie uma consulta e exiba a nova função passando o mouse sobre ela. Examine a ordem dos parâmetros. Eles devem ser especificados na ordem a seguir quando você usa a função.

Selecione Usar no editor para adicionar a nova função a uma consulta. Depois, adicione valores para os parâmetros. Não é necessário especificar um valor para CategoryParam porque ele tem um valor padrão.

Próximas etapas

Confira Operações da cadeia de caracteres para saber mais sobre como gravar consultas de log do Azure Monitor.