Coletar logs de um arquivo de texto com o Agente do Azure Monitor

Artigo
11/14/2024

Os Logs de Texto Personalizados são uma das fontes de dados usadas em uma DCR (regra de coleta de dados). Os detalhes para a criação da DCR são fornecidos em Coleta de dados com o Agente do Azure Monitor. Este artigo fornece detalhes adicionais para o tipo de logs de texto.

Muitos aplicativos e serviços registrarão informações em arquivos de texto em vez de serviços de log padrão, como o Log de Eventos do Windows ou o Syslog. Esses dados podem ser coletados com Agente do Azure Monitor e armazenados em um workspace do Log Analytics com dados coletados de outras fontes.

Pré-requisitos

Workspace do Log Analytics em que você tem pelo menos direitos de colaborador.
Um DCE (ponto de extremidade de coleta de dados) na mesma região do workspace do Log Analytics. Consulte como configurar pontos de extremidade de coleta de dados com base em sua implantação para obter detalhes.
Uma DCR nova ou existente descrita em Coleta de dados com o Agente do Azure Monitor.

Operação básica

O diagrama a seguir mostra a operação básica de coleta de dados de log de um arquivo de texto.

O agente observa os arquivos de log que correspondem a um padrão de nome especificado no disco local.
Cada entrada no log é coletada e enviada para o Azure Monitor. O fluxo de entrada inclui toda a entrada de log em uma única coluna.
Se a transformação padrão for usada, toda a entrada de log será enviada para uma única coluna na tabela de destino.
Se uma transformação personalizada for usada, a entrada de log poderá ser analisada em várias colunas na tabela de destino.

Requisitos de arquivo de texto e práticas recomendadas

O arquivo que o Agente do Azure Monitor está monitorando deve atender aos seguintes requisitos:

O arquivo deve ser armazenado na unidade local do computador com o Agente do Azure Monitor no diretório que está sendo monitorado.
Cada registro deve ser delineado com um fim de linha.
O arquivo deve usar a codificação ASCII ou UTF-8. Não há suporte para outros formatos, como UTF-16.
Novos registros devem ser acrescentados ao final do arquivo e não substituir registros antigos. A substituição causará perda de dados.

Siga as seguintes recomendações para garantir que você não tenha problemas de perda de dados ou desempenho:

Crie um novo arquivo de log todos os dias para que você possa limpar arquivos antigos facilmente.
Limpe continuamente os arquivos de log no diretório monitorado. O acompanhamento de vários arquivos de log pode aumentar o uso da CPU e da memória do agente. Aguarde pelo menos dois dias para dar tempo suficiente para que todos os logs sejam processados.
Não renomeie um arquivo que corresponda ao padrão de verificação de arquivo para outro nome que também corresponda ao padrão de verificação de arquivo. Isso fará com que dados duplicados sejam ingeridos.
Não renomeie nem copie arquivos de log grandes que correspondam ao padrão de verificação de arquivo para o diretório monitorado. Se for necessário, não exceda 50 MB por minuto.

Fluxo de entrada

Observação

O suporte dual SIM que usa um registro de data e hora para delimitar eventos agora está disponível. Até que o suporte seja adicionado à interface do usuário do portal, use uma implantação de modelo de gerenciamento de recursos.

O fluxo de entrada de dados inclui as colunas na tabela a seguir.

Coluna	Type	Descrição
`TimeGenerated`	datetime	A hora em que o registro foi gerado. Esse valor será preenchido automaticamente com o tempo em que o registro for adicionado ao workspace do Log Analytics. Você pode substituir esse valor usando uma transformação para definir `TimeGenerated` para outro valor.
`RawData`	string	A entrada de log inteira em uma única coluna. Você pode usar uma transformação se quiser dividir esses dados em várias colunas antes de enviar para a tabela.
`FilePath`	string	Se você adicionar essa coluna ao fluxo de entrada na DCR, ela será preenchida com o caminho para o arquivo de log. Esta coluna não é criada automaticamente e não pode ser adicionada usando o portal. Você deve modificar manualmente o DCR criado pelo portal ou criar o DCR usando outro método em que você pode definir explicitamente o fluxo de entrada.
`Computer`	string	Se você adicionar esta coluna ao fluxo de entrada no DCR, ela será preenchida com o nome do computador com o arquivo de log. Esta coluna não é criada automaticamente e não pode ser adicionada usando o portal. Você deve modificar manualmente o DCR criado pelo portal ou criar o DCR usando outro método em que você pode definir explicitamente o fluxo de entrada.

Tabela personalizada

Antes de coletar dados de log de um arquivo de texto, você deve criar uma tabela personalizada no workspace do Log Analytics para receber os dados. O esquema de tabela deve corresponder aos dados que você está coletando ou adicionar uma transformação para garantir que o esquema de saída corresponda à tabela.

Aviso

Para evitar a perda de dados, é importante que você não use uma tabela de log personalizada existente que os agentes do MMA estão utilizando no momento. Depois que um agente do Azure Monitor gravar em uma tabela de log personalizada existente, agentes MMA não poderão mais gravar nessa tabela. Em vez disso, você deve criar uma nova tabela especificamente para agentes do Azure Monitor para garantir a transição suave de um agente para o próximo.

Por exemplo, você pode usar o seguinte script do PowerShell para criar uma tabela personalizada com RawData, FilePath, e Computer. Você não precisaria de uma transformação para essa tabela porque o esquema corresponde ao esquema padrão do fluxo de entrada.

$tableParams = @'
{
    "properties": {
        "schema": {
               "name": "{TableName}_CL",
               "columns": [
                    {
                        "name": "TimeGenerated",
                        "type": "DateTime"
                    }, 
                    {
                        "name": "RawData",
                        "type": "String"
                    },
                    {
                        "name": "FilePath",
                        "type": "String"
                    },
                    {
                        "name": "Computer",
                        "type": "String"
                    }
              ]
        }
    }
}
'@

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

Criar uma regra de coleta de dados para um arquivo de texto

Portal
Modelo do Resource Manager

Crie uma regra de coleta de dados, conforme descrito em Coletar dados com o Agente do Azure Monitor. Na etapa Coletar e entregar, selecione Logs de Texto Personalizados na lista suspensa tipo de fonte de dados.

Configuração	Descrição
Padrão do arquivo	Identifica o local e o nome dos arquivos de log no disco local. Use um caractere curinga para nomes de arquivo que variam, por exemplo, quando um novo arquivo é criada todos os dias com um novo nome. Você pode inserir vários padrões de arquivo separados por vírgulas. Exemplos: - C:\Logs\MyLog.txt - C:\Logs\MyLog.txt - C:\App01\AppLog.txt, C:\App02\AppLog.txt - /var/mylog.log - /var/mylog.log
Nome da tabela	Nome da tabela de destino no workspace do Log Analytics.
Delimitador de registro	Não usado atualmente, mas reservado para possível uso futuro, permitindo delimitadores diferentes do fim da linha (`/r/n`) com suporte no momento.
Transformação	Transformação de tempo de ingestão filtrar registros ou formatar os dados de entrada para a tabela de destino. Use `source` para deixar os dados de entrada inalterados.

Use o modelo do ARM a seguir para criar um DCR para coletar arquivos de log de texto, fazendo as alterações descritas nas seções anteriores. A tabela a seguir descreve os parâmetros que exigem valores ao implantar o modelo.

Configuração	Descrição
Padrão do arquivo	Identifica o local e o nome dos arquivos de log no disco local. Use um caractere curinga para nomes de arquivo que variam, por exemplo, quando um novo arquivo é criada todos os dias com um novo nome. Você pode inserir vários padrões de arquivo separados por vírgulas. Exemplos: - C:\Logs\MyLog.txt - C:\Logs\MyLog.txt - C:\App01\AppLog.txt, C:\App02\AppLog.txt - /var/mylog.log - /var/mylog.log
Nome da tabela	Nome da tabela de destino no workspace do Log Analytics.
Delimitador de registro	Não usado atualmente, mas reservado para possível uso futuro, permitindo delimitadores diferentes do fim da linha (`/r/n`) com suporte no momento.
Transformação	Transformação de tempo de ingestão filtrar registros ou formatar os dados de entrada para a tabela de destino. Use `source` para deixar os dados de entrada inalterados.
timeFormat	Os formatos de hora a seguir são aceitos. Use as citações no modelo do ARM. Não inclua o tempo de amostra que está entre parênteses. - “yyyy-MM-ddTHH:mm:ssk” (2024-10-29T18:28:34) - “YYYY-MM-DD HH:MM:SS” (2024-10-29 18:28:34) - “M/D/YYYY HH:MM:SS AM/PM” (10/29/2024 06:28:34 PM) - “Mês DD, AAAA HH:MM:SS” (29 de outubro de, 2024 18:28:34) - “yyMMdd HH:mm:ss” (241029 18:28:34) - “ddMMyy HH:mm:ss” (291024 18:28:34) - “MMM d HH:mm:ss” (Oct 29 18:28:34) - “dd/MMM/yyyy:HH:mm:ss zzz” (14/Oct/2024:18:28:34 -000)

Use o modelo ARM a seguir para criar ou modificar um DCR para coletar arquivos de log de texto. Além dos valores de parâmetro, talvez seja necessário modificar os seguintes valores no modelo:

columns: remova a coluna FilePath se você não quiser recolhê-la.
transformKql: modifique a transformação padrão se você quiser modificar ou filtrar o fluxo de entrada, por exemplo, para analisar a entrada de log em várias colunas. O esquema de saída da transformação deve corresponder ao esquema da tabela de destino.

Importante

Se você criar a DCR usando um modelo do ARM, ainda deverá associar a DCR aos agentes que a usarão. Você pode editar o DCR no portal do Azure e selecionar os agentes conforme descrito em Adicionar recursos. A seção de parâmetros no DCR é opcional quando você os substitui por cadeias de caracteres mais abaixo no JSON.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
              "description": "Unique name for the DCR. "
            }
        },
        "dataCollectionEndpointResourceId": {
            "type": "string",
            "metadata": {
              "description": "Resource ID of the data collection endpoint (DCE)."
            }
        },
        "location": {
            "type": "string",
            "metadata": {
              "description": "Region for the DCR. Must be the same location as the Log Analytics workspace. "
            }
        },
        "filePatterns": {
            "type": "string",
            "metadata": {
              "description": "Path on the local disk for the log file to collect. May include wildcards.Enter multiple file patterns separated by commas (AMA version 1.26 or higher required for multiple file patterns on Linux)."
            }
        },
        "tableName": {
            "type": "string",
            "metadata": {
              "description": "Name of destination table in your Log Analytics workspace. "
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
              "description": "Resource ID of the Log Analytics workspace with the target table."
            }
        },
        "timeFormat": {
            "type": "string"
            "metadata": {
                "discription": "The time format that you would like to use to split multi line imput"
            }
      }
    },
    "variables": {
      "tableOutputStream": "[concat('Custom-', parameters('tableName'))]"
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2022-06-01",
            "properties": {
                "dataCollectionEndpointId": "[parameters('dataCollectionEndpointResourceId')]",
                "streamDeclarations": {
                    "Custom-Text-stream": {
                        "columns": [
                            {
                                "name": "TimeGenerated",
                                "type": "datetime"
                            },
                            {
                                "name": "RawData",
                                "type": "string"
                            },
                            {
                                "name": "FilePath",
                                "type": "string"
                            },
                            {
                                "name": "Computer",
                                "type": "string"
                            }
                        ]
                    }
                },
                "dataSources": {
                    "logFiles": [
                        {
                            "streams": [
                                "Custom-Text-stream"
                            ],
                            "filePatterns": [
                                "[parameters('filePatterns')]"
                            ],
                            "format": "text",
                            "name": "Custom-Text-dataSource",
                            "settings": {
                               "text": {
                                      "recordStartTimestampFormat": "[parameters('timeFormat')]"
                               }
                            }
                        }
                    ]
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "workspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-Text-dataSource"
                        ],
                        "destinations": [
                            "workspace"
                        ],
                        "transformKql": "source",
                        "outputStream": "[variables('tableOutputStream')]"
                    }
                ]
            }
        }
    ]
}

Arquivos de log delimitados

Muitos arquivos de log de texto têm entradas delimitadas por um caractere, como uma vírgula. Para analisar esses dados em colunas separadas, use uma transformação com a função de divisão.

Por exemplo, considere um arquivo de texto com os seguintes dados delimitados por vírgula. Esses campos podem ser descritos como: Time, Code, Severity, Module e Message.

2024-06-21 19:17:34,1423,Error,Sales,Unable to connect to pricing service.
2024-06-21 19:18:23,1420,Information,Sales,Pricing service connection established.
2024-06-21 21:45:13,2011,Warning,Procurement,Module failed and was restarted.
2024-06-21 23:53:31,4100,Information,Data,Nightly backup complete.

A transformação a seguir analisa os dados em colunas separadas. Como split retorna dados dinâmicos, você deve usar funções como tostring e toint para converter os dados no tipo escalar correto. Você também precisa fornecer um nome para cada entrada que corresponda ao nome da coluna na tabela de destino. Observe que este exemplo fornece um valor TimeGenerated. Se isso não tiver sido fornecido, o tempo de ingestão será usado.

source | project d = split(RawData,",") | project TimeGenerated=todatetime(d[0]), Code=toint(d[1]), Severity=tostring(d[2]), Module=tostring(d[3]), Message=tostring(d[4])

Recuperar esses dados com uma consulta de log retornaria os seguintes resultados.

Solução de problemas

Siga as etapas a seguir se você não estiver coletando dados do log de texto que está esperando.

Verifique se os dados estão sendo gravados no arquivo de log que está sendo coletado.
Verifique se o nome e o local do arquivo de log correspondem ao padrão de arquivo especificado.
Verifique se o esquema da tabela de destino corresponde ao fluxo de entrada ou se você tem uma transformação que converterá o fluxo de entrada no esquema correto.
Consulte Verificar operação para verificar se o agente está operacional e se os dados estão sendo recebidos.

Próximas etapas

Saiba mais sobre:

Compartilhar via