Tutorial: adicionar uma transformação na regra de coleta de dados do workspace ao Azure Monitor usando os modelos do Resource Manager

  • Artigo

Este tutorial orienta você pela configuração de uma transformação de amostra em uma regra de coleta de dados de workspace usando modelos do Resource Manager. As transformações no Azure Monitor permitem que você filtre ou modifique os dados de entrada antes de serem enviados para seu destino. As transformações de workspace oferecem suporte para transformações em tempo de ingestão para fluxos de trabalho que ainda não usam o pipeline de ingestão de dados do Azure Monitor.

As transformações de workspace são armazenadas juntas em uma única DCR (regra de coleta de dados) para o workspace, chamada DCR do workspace. Cada transformação está associada a uma tabela específica. A transformação será aplicada a todos os dados enviados a essa tabela de qualquer fluxo de trabalho que não esteja usando um DCR.

Observação

Este tutorial usa modelos do Resource Manager e a API REST para configurar uma transformação de workspace. Confira Tutorial: Adicionar uma transformação na regra de coleta de dados do workspace ao Azure Monitor usando o portal do Azure para o mesmo tutorial usando o portal do Azure.

Neste tutorial, você aprenderá a:

  • Configure a transformação de workspace para uma tabela em um workspace do Log Analytics.
  • Gravar uma consulta de log para uma transformação de tempo de ingestão

Observação

Este tutorial usa o PowerShell do Azure Cloud Shell para fazer chamadas à API REST usando a API Tables do Azure Monitor e o portal do Azure para instalar modelos do Resource Manager. Você pode usar qualquer outro método para fazer essas chamadas.

Pré-requisitos

Para concluir este tutorial, você precisará do seguinte:

Visão geral do tutorial

Neste tutorial, você reduzirá o requisito de armazenamento para a tabela LAQueryLogs filtrando determinados registros. Você também removerá o conteúdo de uma coluna ao analisar os dados da coluna para armazenar uma parte dos dados em uma coluna personalizada. A tabela LAQueryLogs é criada quando você habilita a auditoria de consulta de log em um workspace, mas isso só é usado como exemplo para o tutorial. Você pode usar esse mesmo processo básico para criar uma transformação para qualquer tabela com suporte em um workspace do Log Analytics.

Habilitar logs de auditoria de consulta

Você precisa habilitar a auditoria de consulta para o workspace para criar a tabela LAQueryLogs com a qual trabalhará. Isso não é necessário para todas as transformações de tempo de ingestão. É apenas para gerar os dados de exemplo que essa transformação de exemplo usará.

  1. No menu Workspaces do Log Analytics no portal do Azure, selecione Configurações de diagnóstico e, em seguida, Adicionar configuração de diagnóstico.

    Captura de tela das configurações de diagnóstico.

  2. Forneça um nome para a configuração de diagnóstico e selecione o workspace para que os dados de auditoria sejam armazenados no mesmo workspace. Selecione a categoria Auditoria e clique em Salvar para salvar a configuração de diagnóstico e fechar a página de configuração de diagnóstico.

    Captura de tela da nova configuração de diagnóstico.

  3. Selecione Logs e, em seguida, execute algumas consultas para preencher LAQueryLogs com alguns dados. Essas consultas não precisam retornar dados.

    Captura de tela de consultas de log de amostra.

Esquema da tabela do Azure

Antes de criar a transformação, as duas alterações a seguir devem ser feitas na tabela:

  • A tabela deve ser habilitada para transformação de tworkspace. Isso é necessário para qualquer tabela que terá uma transformação, mesmo que a transformação não modifique o esquema da tabela.
  • Todas as colunas adicionais preenchidas pela transformação devem ser adicionadas à tabela.

Use a API Tables - Update para configurar a tabela com o código do PowerShell abaixo. Chamar a API habilita a tabela para transformações de workspace, independentemente de colunas personalizadas serem definidas. Neste exemplo, ela inclui uma coluna personalizada chamada Resources_CF, que será preenchida com a consulta de transformação.

Importante

Todas as colunas personalizadas adicionadas a uma tabela interna devem terminar em _CF. Colunas adicionadas a uma tabela personalizada (uma tabela com um nome que termina em _CL) não precisam ter esse sufixo.

  1. Clique no botão Cloud Shell no portal do Azure e verifique se o ambiente está definido como PowerShell.

    Captura de tela da abertura do Cloud Shell.

  2. Copie o código do PowerShell a seguir e substitua o parâmetro Path pelos detalhes do workspace.

    $tableParams = @'
{
    "properties": {
        "schema": {
            "name": "LAQueryLogs",
            "columns": [
                {
                    "name": "Resources_CF",
                    "description": "The list of resources, this query ran against",
                    "type": "string",
                    "isDefaultDisplay": true,
                    "isHidden": false
                }
            ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/LAQueryLogs?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

  3. Cole o código no prompt do Cloud Shell para executá-lo.

    Captura de tela do script no Cloud Shell.

  4. Você pode verificar se a coluna foi adicionada acessando o menu Workspaces do Log Analytics no portal do Azure. Selecione Logs para abrir o Log Analytics e, em seguida, expanda a tabela LAQueryLogs para exibir as colunas.

    Captura de tela do Log Analytics com nova coluna.

Definir consulta de transformação

Use o Log Analytics para testar a consulta de transformação, antes de adicioná-la a uma regra de coleta de dados.

  1. Abra o workspace no menu Workspaces do Log Analytics no portal do Azure e selecione Logs para abrir o Log Analytics.

  2. Execute a consulta a seguir para exibir o conteúdo da tabela LAQueryLogs. Observe o conteúdo da coluna RequestContext. A transformação recuperará o nome do workspace dessa coluna e removerá o restante dos dados.

    LAQueryLogs
| take 10

    Captura de tela da consulta inicial no Log Analytics.

  3. Modifique a consulta de acordo com o seguinte:

    LAQueryLogs
| where QueryText !contains 'LAQueryLogs'
| extend Context = parse_json(RequestContext)
| extend Workspace_CF = tostring(Context['workspaces'][0])
| project-away RequestContext, Context

    Isso faz as seguintes alterações:

    • Remova as linhas relacionadas à consulta da própria tabela LAQueryLogs para economizar espaço, pois essas entradas de log não são úteis.
    • Adicione uma coluna para o nome do workspace consultado.
    • Remova os dados da coluna RequestContext para economizar espaço.

    Captura de tela da consulta modificada no Log Analytics.

  4. Faça as seguintes alterações na consulta para usá-la na transformação:

    • Em vez de especificar um nome de tabela (LAQueryLogs, nesse caso) como a fonte de dados para essa consulta, use a palavra-chave source. Essa é uma tabela virtual que sempre representa os dados de entrada em uma consulta de transformação.
    • Remova os operadores que não têm suporte por consultas de transformação. Consulte Recursos de KQL com suporte para obter uma lista dos detalhes de operadores com suporte.
    • Nivele a consulta para uma única linha para que possa se ajustar ao JSON da DCR.

    Veja a seguir a consulta que você usará na transformação após essas modificações:

    source | where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''

Crie uma DCR (regra de coleta de dados)

Como essa é a primeira transformação no workspace, você precisa criar uma DCR de transformação do workspace. Se você criar transformações de workspace para outras tabelas no mesmo workspace, elas deverão ser armazenadas nesta mesma DCR.

  1. Na caixa de pesquisa do portal do Azure, digite modelo e selecione Implantar um modelo personalizado.

    Captura de tela para implantar modelo personalizado.

  2. Clique em Criar seu próprio modelo no editor.

    Captura de tela para criar modelo no editor.

  3. Cole o modelo do Resource Manager abaixo no editor e, em seguida, clique em Salvar. Esse modelo define a DCR e contém a consulta de transformação. Você não precisa modificar esse modelo, pois ele coletará os valores para seus parâmetros.

    Captura de tela para edição de modelo do Resource Manager. 

    {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Rule to create."
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "westus2",
            "allowedValues": [
                "westus2",
                "eastus2",
                "eastus2euap"
            ],
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2021-09-01-preview",
            "kind": "WorkspaceTransforms",
            "properties": {
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "clv2ws1"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Microsoft-Table-LAQueryLogs"
                        ],
                        "destinations": [
                            "clv2ws1"
                        ],
                        "transformKql": "source |where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''"
                    }
                ]
            }
        }
    ],
    "outputs": {
        "dataCollectionRuleId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
        }
    }
}

  4. Na tela Implantação personalizada, especifique uma Assinatura e um Grupo de recursos para armazenar a regra de coleta de dados e, em seguida, forneça os valores definidos no modelo. Isso inclui um Nome para a regra de coleta de dados e a ID de Recurso do Workspace que você coletou em uma etapa anterior. O Local deve ser o mesmo local do workspace. A Região já estará preenchida e será usada para o local da regra de coleta de dados.

    Captura de tela para editar valores de implantação personalizados.

  5. Clique em Examinar + criar e, em seguida, Criar ao examinar os detalhes.

  6. Quando a implantação for concluída, expanda a caixa Detalhes da implantação e clique na regra de coleta de dados para exibir os detalhes. Clique em Exibição JSON.

    Captura de tela para detalhes da regra de coleta de dados.

  7. Copie a ID de Recurso da regra de coleta de dados. Você usará isso na próxima etapa.

    Captura de tela da exibição JSON da regra de coleta de dados.

A etapa final para habilitar a transformação é vincular a DCR ao workspace.

Importante

Um workspace só pode ser conectado a uma única DCR e a DCR vinculada deve conter esse workspace como destino.

Use a API Workspaces - Update para configurar a tabela com o código do PowerShell abaixo.

  1. Clique no botão Cloud Shell para abrir o Cloud Shell novamente. Copie o código do PowerShell a seguir e substitua os parâmetros pelos valores do workspace e da DCR.

    $defaultDcrParams = @'
{
    "properties": {
        "defaultDataCollectionRuleResourceId": "/subscriptions/{subscription}/resourceGroups/{resourcegroup}/providers/Microsoft.Insights/dataCollectionRules/{DCR}"
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}?api-version=2021-12-01-preview" -Method PATCH -payload $defaultDcrParams

  2. Cole o código no prompt do Cloud Shell para executá-lo.

    Captura de tela do script para vincular o espaço de trabalho ao DCR.

Testar transformação

Aguarde cerca de 30 minutos para que a transformação entre em vigor e você poderá testá-la executando uma consulta na tabela. Somente os dados enviados para a tabela após a aplicação da transformação serão afetados.

Para este tutorial, execute algumas consultas de exemplo para enviar dados para a tabela LAQueryLogs. Inclua algumas consultas em LAQueryLogs para que você possa verificar se a transformação filtra esses registros. Observe se a saída tem a nova coluna Workspace_CF e se não há registros para LAQueryLogs.

Solução de problemas

Esta seção descreve diferentes condições de erro que você pode receber e como corrigi-las.

O IntelliSense no Log Analytics não reconhece novas colunas na tabela

O cache que direciona o IntelliSense pode levar até 24 horas para ser atualizado.

A transformação em uma coluna dinâmica não está funcionando

No momento, há um problema conhecido que afeta as colunas dinâmicas. Uma solução alternativa temporária é analisar explicitamente os dados de coluna dinâmicos usando parse_json(), antes de executar qualquer operação em relação a eles.

Próximas etapas