Partilhar via

Tutorial: Adicionar transformação na regra de coleta de dados do espaço de trabalho ao Azure Monitor usando modelos do Gerenciador de Recursos

  • Artigo

Este tutorial orienta você pela configuração de uma transformação de exemplo em uma regra de coleta de dados de espaço de trabalho usando modelos do Gerenciador de Recursos. As transformações no Azure Monitor permitem filtrar ou modificar dados de entrada antes que eles sejam enviados para seu destino. As transformações do espaço de trabalho fornecem suporte para transformações de 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 do espaço de trabalho são armazenadas juntas em uma única regra de coleta de dados (DCR) para o espaço de trabalho, chamada DCR do espaço de trabalho. Cada transformação está associada a uma tabela específica. A transformação é aplicada a todos os dados enviados para esta tabela a partir de qualquer fluxo de trabalho que não use um DCR.

Nota

Este tutorial usa modelos do Gerenciador de Recursos e a API REST para configurar uma transformação de espaço de trabalho. Consulte Tutorial: Adicionar transformação na regra de coleta de dados do espaço de trabalho ao Azure Monitor usando o portal do Azure para obter o mesmo tutorial usando o portal do Azure.

Neste tutorial, irá aprender a:

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

Nota

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

Pré-requisitos

Para concluir este tutorial, precisa do seguinte:

Visão geral do tutorial

Neste tutorial, você reduzirá o requisito de armazenamento para a LAQueryLogs tabela filtrando determinados registros. Você também removerá o conteúdo de uma coluna enquanto analisa 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 espaço de trabalho, mas isso só é usado como um exemplo para o tutorial. Você pode usar esse mesmo processo básico para criar uma transformação para qualquer tabela suportada em um espaço de trabalho do Log Analytics.

Habilitar logs de auditoria de consulta

Você precisa habilitar a auditoria de consulta para seu espaço de trabalho para criar a tabela com a LAQueryLogs qual você 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 de espaços de trabalho do Log Analytics no portal do Azure, selecione Configurações de diagnóstico e Adicionar configuração de diagnóstico.

    Captura de ecrã das definições de diagnóstico.

  2. Forneça um nome para a configuração de diagnóstico e selecione o espaço de trabalho para que os dados de auditoria sejam armazenados no mesmo espaço de trabalho. 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 execute algumas consultas para preencher LAQueryLogs com alguns dados. Essas consultas não precisam retornar nenhum dado.

    Captura de tela de consultas de log de exemplo.

Atualizar esquemas de tabelas

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

  • A tabela deve estar habilitada para transformação do espaço de trabalho. Isso é necessário para qualquer tabela que terá uma transformação, mesmo que a transformação não modifique o esquema da tabela.
  • Quaisquer 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 do espaço de trabalho, independentemente de as colunas personalizadas estarem ou não definidas. Neste exemplo, ele 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. As 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 seguinte código do PowerShell e substitua o parâmetro Path pelos detalhes do seu espaço de trabalho.

    $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 de espaço de trabalho do Log Analytics no portal do Azure. Selecione Logs para abrir o Log Analytics e expanda a LAQueryLogs tabela para exibir suas colunas.

    Captura de ecrã do Log Analytics com nova coluna.

Definir transformation query

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

  1. Abra seu espaço de trabalho no menu de espaços de trabalho do Log Analytics no portal do Azure e selecione Logs para abrir o Log Analytics.

  2. Execute a seguinte consulta para exibir o LAQueryLogs conteúdo da tabela. Observe o conteúdo da RequestContext coluna. A transformação recuperará o nome do espaço de trabalho desta coluna e removerá o restante dos dados nela.

    LAQueryLogs
| take 10

    Captura de ecrã da consulta inicial no Log Analytics.

  3. Modifique a consulta para 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:

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

    Captura de ecrã 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 neste caso) como a fonte de dados para esta consulta, use a source palavra-chave. Esta é uma tabela virtual que sempre representa os dados de entrada em uma consulta de transformação.
    • Remova todos os operadores que não são suportados por consultas de transformação. Consulte Recursos KQL suportados para obter uma lista detalhada dos operadores suportados.
    • Nivele a consulta em uma única linha para que ela possa caber no JSON DCR.

    A seguir está 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 = ''

Criar regra de coleta de dados (DCR)

Como essa é a primeira transformação no espaço de trabalho, você precisa criar um DCR de transformação do espaço de trabalho. Se você criar transformações de espaço de trabalho para outras tabelas no mesmo espaço de trabalho, elas deverão ser armazenadas nesse mesmo DCR.

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

    Captura de tela para implantar o 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 Gerenciador de Recursos abaixo no editor e clique em Salvar. Este modelo define o DCR e contém a consulta de transformação. Você não precisa modificar esse modelo, pois ele coletará valores para seus parâmetros.

    Captura de ecrã para editar o modelo do Gestor de Recursos. 

    {
    "$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 um grupo Assinatura e Recursos para armazenar a regra de coleta de dados e forneça os valores definidos no modelo. Isso inclui um Nome para a regra de coleta de dados e a ID do Recurso de Espaço de Trabalho que você coletou em uma etapa anterior. O local deve ser o mesmo local do espaço de trabalho. A Região já estará preenchida e é utilizada para a localização da regra de recolha de dados.

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

  5. Clique em Rever + criar e, em seguida, em Criar quando rever os detalhes.

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

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

  7. Copie a ID do recurso para a regra de coleta de dados. Você usará isso na próxima etapa.

    Captura de ecrã para a vista JSON da regra de recolha de dados.

A etapa final para habilitar a transformação é vincular o DCR ao espaço de trabalho.

Importante

Um espaço de trabalho só pode ser conectado a um único DCR, e o DCR vinculado deve conter esse espaço de trabalho como um 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 seguinte código do PowerShell e substitua os parâmetros por valores para seu espaço de trabalho e 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.

Transformação de teste

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

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

Resolução de Problemas

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

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

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

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

Atualmente, há um problema conhecido que afeta as colunas dinâmicas. Uma solução temporária é analisar explicitamente os dados dinâmicos da coluna usando parse_json() antes de executar quaisquer operações contra eles.

Próximos passos