Recopilación de registros de un archivo de texto con el agente de Azure Monitor

Los registros de texto personalizados son una de las fuentes de datos utilizadas en una regla de recopilación de datos (DCR). Los detalles para la creación de la DCR se proporcionan en Recopilación de datos con el agente de Azure Monitor. En este artículo se proporcionan detalles adicionales para el tipo de registros de texto.

Muchas aplicaciones y servicios registrarán información en archivos de texto en lugar de servicios de registro estándar, como registro de eventos de Windows o Syslog. Estos datos pueden recopilarse con el agente Azure Monitor y almacenarse en un área de trabajo de Log Analytics con datos recopilados de otras fuentes.

Requisitos previos

• Área de trabajo de Log Analytics en la que tiene al menos derechos de colaborador.
• Un punto de conexión de recopilación de datos (DCE) en la misma región que el área de trabajo de Log Analytics. Consulte Cómo configurar los puntos de conexión de recopilación de datos en función de su implementación para obtener más detalles.
• Un DCR nuevo o existente descrito en Recopilar datos con el agente de Azure Monitor.

Funcionamiento básico

En el diagrama siguiente se muestra la operación básica de recopilar datos de registro de un archivo de texto.

1. El agente busca los archivos de registro que coincidan con un patrón de nombre especificado en el disco local.
2. Cada entrada del registro se recopila y se envía a Azure Monitor. La secuencia recibida incluye toda la entrada de registro en una sola columna.
3. Si se usa la transformación predeterminada, toda la entrada de registro se envía a una sola columna de la tabla de destino.
4. Si se usa una transformación personalizada, la entrada de registro se puede analizar en varias columnas de la tabla de destino.

Requisitos y procedimientos recomendados de archivos de texto

El archivo que el agente de Azure Monitor está supervisando debe cumplir los siguientes requisitos:

• El archivo debe almacenarse en la unidad local de la máquina con el agente de Azure Monitor en el directorio que se está supervisando.
• Cada registro debe delimitarse con un final de línea.
• El archivo debe usar la codificación ASCII o UTF-8. No se admiten otros formatos, como UTF-16.
• Los nuevos registros deben anexarse al final del archivo y no sobrescribir los registros antiguos. La sobrescritura provocará la pérdida de datos.

Siga las siguientes recomendaciones para asegurarse de que no experimenta problemas de pérdida de datos o rendimiento:

• Cree un nuevo archivo de registro todos los días para que pueda limpiar fácilmente los archivos antiguos.
• Limpie continuamente los archivos de registro en el directorio supervisado. El seguimiento de muchos archivos de registro podría impulsar el uso de memoria y CPU del agente. Espere al menos 2 días para permitir un tiempo suficiente para que se procesen todos los registros.
• No cambie el nombre de un archivo que coincida con el patrón de examen de archivos por otro nombre que también coincida con el patrón de examen de archivos. Esto hará que se ingieren datos duplicados.
• No cambie el nombre ni copie archivos de registro grandes que coincidan con el patrón de examen de archivos en el directorio supervisado. Si fuera necesario, no supere los 50 MB por minuto.

Flujo de entrada

Nota:

Se espera soporte con varias líneas que usa una marca de tiempo ISO 8601 para eventos delimitados a mediados de octubre de 2024

El flujo de datos recibido incluye las columnas de la siguiente tabla.

Columna	Type	Descripción
TimeGenerated	datetime	Hora a la que se generó el registro. Este valor se rellenará automáticamente con la hora en que se agrega el registro al área de trabajo de Log Analytics. Puede invalidar este valor mediante una transformación para establecer TimeGenerated en otro valor.
RawData	string	Toda la entrada de registro en una sola columna. Puede usar una transformación si desea dividir estos datos en varias columnas antes de enviarlos a la tabla.
FilePath	string	Si agrega esta columna a la secuencia recibida en el DCR, se rellenará con la ruta de acceso al archivo de registro. Esta columna no se crea automáticamente y no se puede agregar mediante el portal. Debe modificar manualmente el DCR creado por el portal o crear el DCR mediante otro método, donde puede definir explícitamente la secuencia recibida.
Computer	string	Si agrega esta columna a la secuencia de entrada en el DCR, se rellenará con el nombre del equipo que tiene el archivo de registro. Esta columna no se crea automáticamente y no se puede agregar mediante el portal. Debe modificar manualmente el DCR creado por el portal o crear el DCR mediante otro método, donde puede definir explícitamente la secuencia recibida.

Tabla personalizada

Para poder recopilar datos de registro de un archivo de texto, debe crear una tabla personalizada en el área de trabajo de Log Analytics para recibir los datos. El esquema de tabla debe coincidir con los datos que está recopilando o debe agregar una transformación para asegurarse de que el esquema de salida coincide con la tabla.

Advertencia

No debe usar una tabla de registro personalizada existente que usen los agentes de MMA. Los agentes de MMA no podrán escribir en la tabla una vez que el primer agente AMA escribe en la tabla. Debe crear una nueva tabla para que AMA la use para evitar la pérdida de datos MMA.

Por ejemplo, puede usar el siguiente script de PowerShell para crear una tabla personalizada con RawData, FilePath y Computer. No necesitaría una transformación para esta tabla porque el esquema coincide con el esquema predeterminado de la secuencia recibida.

$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

Crear una regla de recopilación de datos para un archivo de texto

Portal

Cree una regla de recopilación de datos, como se describe en Recopilar datos con el agente de Azure Monitor. En el paso Recopilar y entregar, seleccione Registros de texto personalizados en la lista desplegable Tipo de origen de datos.

Configuración	Descripción
Patrón de archivo	Identifica la ubicación y el nombre de los archivos de registro en el disco local. Use un carácter comodín para los nombres de archivo que varían, por ejemplo, cuando se crea un nuevo archivo cada día con un nombre nuevo. Puede escribir varios patrones de archivo separados por comas. Ejemplos: - C:\Logs\MyLog.txt - C:\Logs\MyLog*.txt - C:\App01\AppLog.txt, C:\App02\AppLog.txt - /var/mylog.log - /var/mylog*.log
Nombre de tabla	Nombre de la tabla de destino en el área de trabajo de Log Analytics.
Delimitador de registros	Actualmente no se usa, pero está reservado para uso potencial futuro, lo que permite delimitadores distintos del final de línea admitido actualmente (/r/n).
Transformación	Transformación en tiempo de ingesta para filtrar registros o dar formato a los datos recibidos para la tabla de destino. Use source para dejar los datos entrantes sin cambios.

Plantilla de Resource Manager

Use la siguiente plantilla de ARM para crear o modificar un DCR para recopilar archivos de registro de texto. Además de los valores de parámetro, es posible que tenga que modificar los siguientes valores en la plantilla:

• columns: quite la columna FilePath si no desea recopilarla.
• transformKql: modifique la transformación predeterminada si desea modificar o filtrar la secuencia recibida, por ejemplo, para analizar la entrada de registro en varias columnas. El esquema de salida de la transformación debe coincidir con el esquema de la tabla de destino.

Importante

Si crea el DCR utilizando una plantilla de ARM, deberá asociar el DCR a los agentes que lo utilizarán. Puede editar el DCR en Azure Portal y seleccionar los agentes como se describe en Agregar recursos

{
    "$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."
            }
        }
    },
    "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"
                        }
                    ]
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "workspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-Text-dataSource"
                        ],
                        "destinations": [
                            "workspace"
                        ],
                        "transformKql": "source",
                        "outputStream": "[variables('tableOutputStream')]"
                    }
                ]
            }
        }
    ]
}

Archivos de registro delimitados

Muchos archivos de registro de texto tienen entradas que están delimitadas por un carácter como una coma. Para analizar estos datos en columnas independientes, use una transformación con la función dividir.

Por ejemplo, considere un archivo de texto con los siguientes datos delimitados por comas. Estos campos se pueden describir como: Time, Code, Severity,Module y 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.

La siguiente transformación analiza los datos en columnas independientes. Dado que split devuelve datos dinámicos, debe usar funciones como tostring y toint para convertir los datos en el tipo escalar correcto. También debe proporcionar un nombre para cada entrada que coincida con el nombre de columna de la tabla de destino. Tenga en cuenta que en este ejemplo se proporciona un valor TimeGenerated. Si no se proporcionó, se usaría el tiempo de ingesta.

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])

La recuperación de estos datos con una consulta de registro devolvería los siguientes resultados.

Solución de problemas

Siga los pasos siguientes si no recopila datos del registro de texto que espera.

• Compruebe que los datos se escriben en el archivo de registro que se recopila.
• Compruebe que el nombre y la ubicación del archivo de registro coinciden con el patrón de archivo especificado.
• Compruebe que el esquema de la tabla de destino coincide con la secuencia recibida o que tiene una transformación que convertirá la secuencia recibida en el esquema correcto.
• Consulte Comprobación de la operación para comprobar si el agente está operativo y se reciben datos.

Pasos siguientes

Más información sobre:

• Agente de Azure Monitor
• Reglas de recopilación de datos
• Procedimientos recomendados para la administración de costes en Azure Monitor