Funções em consultas de log do 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 funções para fornecer soluções para diferentes clientes e também reutilizar a lógica de consulta em seu próprio ambiente. Este artigo descreve como usar funções e como criar o seu próprio.

Permissões necessárias

Ação	Permissões necessárias
Ver ou utilizar funções	Microsoft.OperationalInsights/workspaces/query/*/readpermissões para o espaço de trabalho do Log Analytics, conforme fornecido pela função interna do Log Analytics Reader, por exemplo.
Criar ou editar funções	microsoft.operationalinsights/workspaces/savedSearches/writepermissões para o espaço de trabalho do Log Analytics, conforme fornecido pela função interna Colaborador do Log Analytics, por exemplo.

Tipos de funções

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

• Funções da solução: as funções pré-criadas estão incluídas no Azure Monitor. Essas funções estão disponíveis em todos os espaços de trabalho do Log Analytics e não podem ser modificadas.

• Funções de espaço de trabalho: essas funções são instaladas em um espaço de trabalho específico do Log Analytics. Eles podem ser modificados e controlados pelo usuário.

Ver funções

Você pode exibir funções de solução e funções de espaço de trabalho no espaço de trabalho atual na guia Funções no painel esquerdo de um espaço de trabalho do Log Analytics. Use Filtro para filtrar as funções incluídas na lista. Use Agrupar por para alterar seu agrupamento. Insira uma cadeia de caracteres na caixa Pesquisar para localizar uma função específica. Passe o cursor sobre uma função para visualizar detalhes sobre ela, incluindo uma descrição e parâmetros.

Usar uma função

Use uma função em uma consulta digitando seu nome com valores para quaisquer parâmetros iguais aos que você digitaria em um comando. A saída da função pode ser retornada como resultados 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 espaço de trabalho também serão incluídas no IntelliSense à medida que você digita uma consulta.

Se uma consulta exigir parâmetros, forneça-os usando a sintaxe function_name(param1,param2,...).

Criar uma função

Portal

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

Crie uma função com o Log Analytics no portal do Azure selecionando Salvar e fornecendo as informações na tabela a seguir:

Definição	Descrição
Nome da função	Nome da função. O nome não pode incluir um espaço ou caracteres especiais. Também pode não começar com um sublinhado (_) porque esse caractere é reservado para funções de solução.
Categoria legada	Categoria definida pelo usuário para ajudar a filtrar e agrupar funções.
Guardar 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 obter mais informações, consulte Parâmetros de função.

Modelo do Resource Manager

O exemplo a seguir usa o modelo Microsoft.OperationalInsights workspaces/savedSearches para criar uma função. Para obter mais informações sobre modelos do Azure Resource Manager, consulte Compreender a estrutura e a sintaxe dos modelos ARM.

Para saber mais sobre como implantar recursos a partir de um modelo personalizado, vá para Implantar recursos com modelos ARM e portal do Azure.

Nota

Consulte Exemplos do Azure Resource Manager para o Azure Monitor para obter uma lista de exemplos disponíveis e orientações sobre como implantá-los 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

Você pode adicionar parâmetros a uma função para que possa fornecer valores para determinadas variáveis quando você chamá-la. Como resultado, a mesma função pode ser usada em consultas diferentes, cada uma fornecendo valores diferentes para os parâmetros. Os parâmetros são definidos pelas seguintes propriedades:

Definição	Descrição
Type	Tipo de dados para o valor.
Nome	Nome para o parâmetro. Esse nome deve ser usado na consulta para substituir pelo valor do parâmetro.
Default value	Valor a ser usado para o parâmetro se um valor não for fornecido.

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

Trabalhar com 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 de espaço de trabalho. Selecione Carregar o código da função para adicionar o código da função à consulta atual no editor.

Se você adicionar o código da função a uma consulta vazia ou à primeira linha de uma consulta existente, o nome da função será adicionado à guia. Uma função de espaço de trabalho permite a opção de editar os detalhes da função.

Editar uma função

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

Exemplo

A função de exemplo a seguir retorna todos os eventos no log de atividades do Azure desde uma data específica e que correspondem a 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âmetros. Em seguida, salve a função selecionando Salvar>salvar como função.

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

Forneça os seguintes valores para as propriedades da função:

Property	valor
Nome da função	AzureActivityByCategory
Categoria legada	Funções de demonstração

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

Type	Name	Valor predefinido
string	CategoriaParam	"Administrativo"
datetime	DataParam

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

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

Próximos passos

Consulte Operações de cadeia de caracteres para obter mais informações sobre como escrever consultas de log do Azure Monitor.