Compartilhar via

Criar uma transformação no Azure Monitor

  • Artigo

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

Observação

Se você não tiver familiaridade com KQL ou a criação de 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 todos os operadores KQL com suporte 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 todas as colunas que não devem ser preenchidas. A coluna estará vazia para o registro na tabela de destino.
  • Exclua as colunas que não estão incluídas na tabela de saída. Os dados serão aceitos sem erros, mas você receberá uma cobrança pela ingestão dos dados extras, mesmo que 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 a fonte de dados não incluir essa propriedade, você poderá adicioná-la na transformação com extend ou project.

Veja a seguir um exemplo de uma transformação que executa várias funções:

  • Filtra os dados de entrada com uma instrução where.
  • Adiciona uma nova coluna usando o operadorextend.
  • Formata a saída para corresponder às colunas da tabela de destino usando o operador project.
source  
| where severity == "Critical" 
| extend Properties = parse_json(properties)
| project
    TimeGenerated = todatetime(["time"]),
    Category = category,
    StatusDescription = StatusDescription,
    EventName = name,
    EventId = tostring(Properties.EventId)

Observação

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

Criar a consulta de transformação

Antes de criar ou editar a 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. Ao obter os resultados desejados, você pode substituir o nome da tabela por source e colá-lo em sua DCR, conforme explicado abaixo em Adicionar transformação à DCR.

Importante

As transformações não dão suporte a todos os recursos KQL. Consulte Recursos de KQL com suporte nas transformações do Azure Monitor para ver os recursos com suporte e as limitações.

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

Syslog | where SeverityLevel != 'info'

Você pode colar essa consulta em sua DCR e, em seguida, alterar o nome da tabela para source.

source | where SeverityLevel != 'info'

Use uma das estratégias a seguir para os dados que serão usados para testar sua consulta.

  • Se você já estiver coletando os dados que deseja transformar, poderá usar o Log Analytics para gravar uma consulta que filtra ou modifica os dados conforme necessário. Copie o texto da consulta e cole-o em sua DCR.
  • Use o Log Analytics para gravar sua consulta usando o operador datatable para criar um conjunto de dados de exemplo que represente seus dados de entrada. Copie o texto da consulta sem o operador datatable e cole-o em sua 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-o em sua DCR ou conclua o processo e edite a DCR para copiar a consulta de transformação. Em seguida, você poderá excluir a nova tabela se não precisar dela.

Adicionar transformação à DCR

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

Observação

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

A consulta de transformação é especificada na propriedade transformKql na seção Fluxos de Dados da DCR. Essa é 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. Ela só será aplicada a esse fluxo de dados, mesmo se o mesmo fluxo ou destino for usado em outros fluxos de dados.

Se a propriedade transformKql 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 da 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 propriedade transformKql, portanto, os dados de entrada são enviados ao destino sem modificação.

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

No exemplo a seguir, transformKql tem uma consulta simples de source, portanto, os dados de entrada são enviados ao 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 os dados, portanto, somente as mensagens de erro são enviadas ao destino.

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

Criar DCR de transformação do workspace

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

Use um dos métodos a seguir para criar uma DCR de transformação de workspace para seu workspace e adicionar uma ou mais transformações a ela.

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

  1. No menu Workspaces do Log Analytics no portal do Azure, selecione Tabelas. Clique à direita da tabela na qual você tem interesse e selecione Criar transformação.

    Captura de tela que mostra a opção de criar uma transformação para uma tabela no portal do Azure.

  2. Se a DCR de transformação do workspace ainda não tiver sido criada para esse workspace, selecione a opção para criar uma. Se já tiver sido criada, essa DCR já estará selecionada. Cada workspace só pode ter uma DCR de transformação de workspace.

    Captura de tela que mostra a criação de uma regra de coleta de dados.

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

    Captura de tela que mostra os dados de exemplo da tabela de logs.

  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, em Avançar e, em seguida, em Criar para salvar a DCR com sua nova transformação.

    Captura de tela que mostra o salvamento da transformação.

Otimizar e monitorar transformações

As transformações executam uma consulta KQL em relação a cada registro coletado com a DCR, portanto, é importante que elas sejam executadas com eficiência. O tempo de execução da transformação contribui para a latência de ingestão de dados geral 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 um segundo para serem executadas. Consulte Otimizar consultas de log no Azure Monitor para obter diretrizes sobre como testar sua consulta antes de implementá-la como uma transformação e recomendações sobre como otimizar consultas que não são executadas com eficiência.

Importante

Você poderá sofrer perda de dados se uma transformação levar mais de 20 segundos.

Como as transformações não são executadas interativamente, é importante monitorá-las de forma contínua para garantir que estejam sendo executadas de maneira correta e não estejam levando muito tempo 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 de transformações. Isso inclui identificar os erros que ocorrem no KQL e as métricas para acompanhar a duração de sua execução.

As seguintes métricas são coletadas automaticamente para transformações e devem ser revisadas regularmente para verificar se suas transformações ainda estão sendo executadas conforme o esperado. Crie regras de alerta de métrica para receber notificações automáticas quando uma dessas métricas exceder um limite.

  • Duração da Transformação de Logs por min
  • Erros de Transformação de Logs por min

Habilite logs de erros da DCR para rastrear erros que possam ocorrer em suas transformações ou outras consultas. Crie uma regra de alerta de log para receber notificações automáticas quando uma entrada for gravada nesta tabela.

Diretrizes

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

Coleta de dados Referência
API de ingestão de logs Enviar dados para logs do Azure Monitor usando a API REST (portal do Azure)
Enviar dados para 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ção de dados em insights de contêiner
Hubs de eventos do Azure Tutorial: ingerir eventos dos Hubs de Eventos do Azure nos Logs do Azure Monitor (Visualização Pública)

Próximas etapas