Criar uma transformação no Azure Monitor

As transformações no Azure Monitor permitem filtrar ou modificar dados de entrada antes que eles sejam armazenados em um espaço de trabalho do Log Analytics. Eles são implementados como uma instrução KQL (Kusto Query Language) em uma regra de coleta de dados (DCR). Este artigo fornece orientação sobre como criar e testar uma consulta de transformação e adicioná-la a um DCR.

Nota

Se você não estiver familiarizado com o KQL ou criando consultas de log para dados do Azure Monitor, comece com Visão geral do Log Analytics no Azure Monitor e consultas de log no Azure Monitor.

Estrutura de consulta básica

Todas as consultas de transformação começam com source, que é uma tabela virtual que representa o fluxo de entrada. Em seguida, você pode usar qualquer operador KQL suportado para filtrar, modificar ou adicionar colunas aos dados como faria com qualquer outra tabela. A consulta é aplicada individualmente a cada entrada enviada pela fonte de dados.

A saída da consulta deve corresponder ao esquema da tabela de destino com as seguintes considerações:

• Você pode omitir quaisquer colunas que não devam ser preenchidas. A coluna ficará vazia para o registro na tabela de destino.
• Certifique-se de excluir todas as colunas que não estão incluídas na tabela de saída. Os dados serão aceitos sem erros, mas você será cobrado pela ingestão dos dados extras, mesmo que eles não estejam armazenados.
• A saída de cada transformação deve conter um carimbo de data/hora válido em uma coluna chamada TimeGenerated do tipo datetime. Se sua fonte de dados não incluir essa propriedade, você poderá adicioná-la na transformação com extend ou project.

Segue-se um exemplo de uma transformação que executa várias funções:

• Filtra os dados recebidos com uma where instrução.
• Adiciona uma nova coluna usando o extend operador .
• Formata a saída para corresponder às colunas da tabela de destino usando o project operador .

source  
| where severity == "Critical" 
| extend Properties = parse_json(properties)
| project
    TimeGenerated = todatetime(["time"]),
    Category = category,
    StatusDescription = StatusDescription,
    EventName = name,
    EventId = tostring(Properties.EventId)

Nota

Consulte Exemplos e cenários de regra de coleta de dados (DCR) no Azure Monitor para obter vários exemplos para diferentes cenários.

Criar a consulta de transformação

Antes de criar ou editar o DCR que incluirá sua transformação, você precisará criar e testar a consulta de transformação. Normalmente, você fará isso executando consultas de teste em dados existentes ou dados de teste. Quando você obtiver os resultados desejados, poderá substituir o nome da tabela e source colá-lo em seu DCR, conforme explicado abaixo em Adicionar transformação ao DCR.

Importante

As transformações não suportam todos os recursos do KQL. Consulte Recursos KQL suportados nas transformações do Azure Monitor para obter recursos e limitações com suporte.

Por exemplo, se você estiver criando uma transformação para filtrar eventos do Syslog, poderá começar com a seguinte consulta que pode ser executada no Log Analytics.

Syslog | where SeverityLevel != 'info'

Pode colar esta consulta no DCR e, em seguida, alterar o nome da tabela para source.

source | where SeverityLevel != 'info'

Use uma das seguintes estratégias para que os dados sejam usados para testar sua consulta.

• Se você já estiver coletando os dados que deseja transformar, poderá usar o Log Analytics para escrever uma consulta que filtre ou modifique os dados conforme necessário. Copie o texto da consulta e cole-o no DCR.
• Use o Log Analytics para escrever sua consulta usando o datatable operador para criar um conjunto de dados de exemplo que represente seus dados de entrada. Copie o texto da consulta sem o datatable operador e cole-o no DCR.
• Use o processo para criar uma nova tabela no portal do Azure e fornecer dados de exemplo. Use a interface incluída para criar e testar sua consulta de transformação. Copie o texto da consulta e cole no DCR ou conclua o processo e edite o DCR para copiar a consulta de transformação. Em seguida, você pode excluir a nova tabela se não precisar dela.

Adicionar transformação ao DCR

Depois de ter sua consulta de transformação, você pode adicioná-la a um DCR. Use as orientações em Criar e editar regras de coleta de dados (DCRs) no Azure Monitor para criar ou editar o DCR usando as informações desta seção para incluir a consulta de transformação na definição de DCR.

Nota

Algumas fontes de dados fornecerão um método usando o portal do Azure para adicionar uma transformação a um DCR. Por exemplo, coletar um texto de uma máquina virtual permite especificar uma consulta de transformação no portal do Azure. A maioria dos cenários de coleta de dados, no entanto, atualmente exige que você trabalhe diretamente com a definição de DCR para adicionar uma transformação. Esse é o processo descrito nesta seção.

A consulta de transformação é especificada na transformKql propriedade na seção Fluxos de Dados do DCR. Esta é a seção que emparelha uma fonte de dados com um destino. A transformação é aplicada ao fluxo de entrada do fluxo de dados antes de ser enviado para o destino. Ele só se aplicará a esse fluxo de dados mesmo que o mesmo fluxo ou destino seja usado em outros fluxos de dados.

Se a transformKql propriedade for omitida, ou se seu valor for simplesmente source, nenhuma transformação será aplicada e os dados de entrada serão enviados para o destino sem modificação.

Importante

A consulta de transformação deve estar em uma única linha, o DCR. Se você estiver criando a transformação no portal do Azure, poderá usar várias linhas para legibilidade e \n será incluído na consulta para cada nova linha.

No exemplo a seguir, não há nenhuma transformKql propriedade, portanto, os dados de entrada são enviados para o destino sem modificação.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

No exemplo a seguir, transformKql tem uma consulta simples de , para que os dados de sourceentrada sejam enviados para o destino sem modificação. Sua funcionalidade é idêntica ao exemplo anterior.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

No exemplo a seguir, transformKql tem uma consulta que filtra dados, portanto, apenas mensagens de erro são enviadas para o destino.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source | where message has 'error'", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

Criar DCR de transformação de espaço de trabalho

A regra de coleta de dados de transformação do espaço de trabalho (DCR) é um DCR especial que é aplicado diretamente a um espaço de trabalho do Log Analytics. Pode haver apenas um DCR de transformação de espaço de trabalho para cada espaço de trabalho, mas ele pode incluir transformações para qualquer número de tabelas.

Use um dos seguintes métodos para criar um DCR de transformação de espaço de trabalho para seu espaço de trabalho e adicionar uma ou mais transformações a ele.

Portal do Azure

Você pode criar um DCR de transformação de espaço de trabalho no portal do Azure adicionando uma transformação a uma tabela com suporte.

1. No menu Espaços de trabalho do Log Analytics no portal do Azure, selecione Tabelas. Clique à direita da tabela em que está interessado e selecione Criar transformação.

   

2. Se o DCR de transformação do espaço de trabalho ainda não tiver sido criado para esse espaço de trabalho, selecione a opção para criar um. Se já tiver sido criado, esse DCR já será selecionado. Cada espaço de trabalho só pode ter um DCR de transformação de espaço de trabalho.

   

3. Selecione Avançar para exibir dados de exemplo da tabela. Clique em Editor de transformação para definir a consulta de transformação.

   

4. Em seguida, você pode editar e executar a consulta de transformação para ver os resultados em relação aos dados reais da tabela. Continue modificando e testando a consulta até obter os resultados desejados.

5. Quando estiver satisfeito com a consulta, clique em Aplicar e, em seguida, em Avançar e Criar para salvar o DCR com sua nova transformação.

   

JSON

Os DCRs de transformação do espaço de trabalho são principalmente como qualquer outro DCR. Eles usam a mesma estrutura JSON para sua definição, e você pode criá-los e editá-los usando os mesmos comandos e estratégias descritos em Criar ou editar um DCR usando JSON. As diferenças são com a definição JSON:

• Ele deve incluir o kind parâmetro com um valor de WorkspaceTransforms.
• A dataSources secção deve estar vazia.
• A destinations seção deve incluir um e apenas um destino de espaço de trabalho do Log Analytics. Este é o espaço de trabalho onde a transformação será aplicada.
• A dataFlows seção deve incluir um fluxo de dados separado para cada tabela que terá uma transformação. Use uma where cláusula na consulta se apenas determinados registros devem ser transformados.

A seguir está um exemplo de definição JSON para um DCR de transformação de espaço de trabalho.

{
    "kind": "WorkspaceTransforms",
    "location": "eastus",
    "properties": {
        "dataSources": {},
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/71b36fb6-4fe4-4664-9a7b-245dc62f2930/resourcegroups/my-resource-group/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "MyWorkspace"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Microsoft-Table-LAQueryLogs"
                ],
                "destinations": [
                    "MyWorkspace"
                ],
                "transformKql": "source | where QueryText !contains 'LAQueryLogs'"
            },
            {
                "streams": [
                    "Microsoft-Table-Event"
                ],
                "destinations": [
                    "MyWorkspace"
                ],
                "transformKql": "source | project-away ParameterXml"
            }
        ],
        "provisioningState": "Succeeded"
    }
}

Otimize e monitore transformações

As transformações executam uma consulta KQL em relação a todos os registros coletados com o DCR, por isso é importante que sejam executadas de forma eficiente. O tempo de execução da transformação contribui para a latência geral de ingestão de dados, e as transformações que levam tempo excessivo para serem executadas podem afetar o desempenho do pipeline de coleta de dados e resultar em perda de dados. As transformações ideais não devem levar mais de 1 segundo para serem executadas. Consulte Otimizar consultas de log no Azure Monitor para obter orientação sobre como testar sua consulta antes de implementá-la como uma transformação e para obter recomendações sobre como otimizar consultas que não são executadas com eficiência.

Importante

Você pode ocorrer perda de dados se uma transformação demorar mais de 20 segundos.

Como as transformações não são executadas interativamente, é importante monitorá-las continuamente para garantir que estejam sendo executadas corretamente e não levem tempo excessivo para processar dados. Consulte Monitorar e solucionar problemas de coleta de dados DCR no Azure Monitor para obter detalhes sobre logs e métricas que monitoram a integridade e o desempenho das transformações. Isso inclui a identificação de quaisquer erros que ocorram no KQL e métricas para acompanhar sua duração de execução.

As métricas a seguir são coletadas automaticamente para transformações e devem ser revisadas regularmente para verificar se as transformações ainda estão sendo executadas conforme o esperado. Crie regras de alerta de métricas para ser notificado automaticamente quando uma dessas métricas exceder um limite.

• Logs Duração da transformação por minuto
• Registos Erros de transformação por minuto

Habilite os logs de erros DCR para rastrear quaisquer erros que ocorram em suas transformações ou outras consultas. Crie uma regra de alerta de log para ser notificado automaticamente quando uma entrada for gravada nesta tabela.

Orientação

Há vários métodos para criar transformações, dependendo do método de coleta de dados. A tabela a seguir lista orientações para diferentes métodos de criação de transformações.

Recolha de dados	Referência
API de ingestão de logs	Enviar dados para os Logs do Azure Monitor usando a API REST (portal do Azure) Enviar dados para os Logs do Azure Monitor usando a API REST (modelos do Azure Resource Manager)
Máquina virtual com agente do Azure Monitor	Adicionar transformação ao Log do Azure Monitor
Cluster do Kubernetes com insights de contêiner	Transformações de dados no Container insights
Hubs de Eventos do Azure	Tutorial: Ingerir eventos dos Hubs de Eventos do Azure para os Logs do Azure Monitor (Visualização Pública)

Próximos passos

• Crie uma regra de coleta de dados e uma associação a ela a partir de uma máquina virtual usando o agente do Azure Monitor.