Funções nas consultas de log no Azure Monitor

Artigo
11/05/2024

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

Ação	Permissões necessárias
Exibir ou usar funções	As permissões `Microsoft.OperationalInsights/workspaces/query/*/read` para os workspaces do Log Analytics, conforme fornecidas pela função interna de Leitor do Log Analytics, por exemplo.
Criar ou editar funções	As permissões `microsoft.operationalinsights/workspaces/savedSearches/write` para os workspaces do Log Analytics, conforme fornecidas pela função interna de Colaborador do Log Analytics, 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.

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.

O exemplo a seguir usa o modelo Microsoft.OperationalInsights workspaces/savedSearches para criar uma função. Para obter mais informações de como criar modelos do Azure Resource Manager, confira Como entender a estrutura e a sintaxe de modelos do ARM.

Para saber mais sobre como implantar recursos de um modelo personalizado, acesse Implantar recursos com modelos do ARM e portal do Azure.

Observação

Consulte Amostras do Azure Resource Manager do Azure Monitor para obter uma lista de amostras disponíveis e diretrizes sobre como implantá-las em sua assinatura do Azure.

Arquivo de modelo

{
  "$schema": "
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"
,
  "contentVersion": "1.0.0.0",
  "resources": [
    {
      "type": "Microsoft.OperationalInsights/workspaces/savedSearches",
      "apiVersion": "2020-08-01",
      "name": "[concat(parameters('workspaceName'), '/', parameters('functionName'))]",
      "location": "[parameters('location')]",
      "properties": {
        "etag": "*",
        "displayName": "[parameters('functionDisplayName')]",
        "category": "[parameters('category')]",
        "query": "[parameters('query')]",
        "functionAlias": "[parameters('functionAlias')]",
        "version": 1
      }
    }
  ],
  "parameters": {
    "workspaceName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Log Analytics workspace"
      }
    },
    "functionName": {
      "type": "string",
      "metadata": {
        "description": "Name of the function"
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "Location of the Log Analytics workspace"
      }
    },
    "functionDisplayName": {
      "type": "string",
      "metadata": {
        "description": "Display name of the function"
      }
    },
    "category": {
      "type": "string",
      "metadata": {
        "description": "Category of the function"
      }
    },
    "query": {
      "type": "string",
      "metadata": {
        "description": "Kusto query for the function"
      }
    },
    "functionAlias": {
      "type": "string",
      "metadata": {
        "description": "Alias for the function"
      }
    }
  }
}

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.

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.

Compartilhar via