Recopilación de registros de un archivo JSON con el agente de Azure Monitor
Registros JSON personalizados es uno de los orígenes de datos usados 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 texto y el tipo de registros JSON.
Muchas aplicaciones y servicios registrarán información en archivos JSON en lugar de servicios de registro estándar, como el registro de eventos de Windows o Syslog. Estos datos se pueden recopilar con agente de Azure Monitor y almacenarlos en un área de trabajo de Log Analytics con datos recopilados de otros orígenes.
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 JSON.
- El agente busca los archivos de registro que coincidan con un patrón de nombre especificado en el disco local.
- Cada entrada del registro se recopila y se envía a Azure Monitor. La secuencia entrante definida por el usuario se usa para analizar los datos de registro en columnas.
- Se usa una transformación predeterminada si el esquema de la secuencia entrante coincide con el esquema de la tabla de destino.
Procedimientos recomendados y requisitos de archivos JSON
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.
- El texto JSON debe estar contenido en una sola fila. No se admite el formato de cuerpo JSON. Vea el ejemplo a continuación.
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.
Tabla personalizada
Para poder recopilar datos de registro de un archivo JSON, debe crear una tabla personalizada en el área de trabajo de Log Analytics para recibir los datos. El esquema de tabla debe coincidir con las columnas de la secuencia entrante o debe agregar una transformación para asegurarse de que el esquema de salida coincide con la tabla.
Advertencia
No debe usar una tabla personalizada existente que haya usado el agente de Log Analytics. Los agentes heredados no podrán escribir en la tabla una vez que el primer agente de Azure Monitor escriba en ella. Cree una nueva tabla para que el agente de Azure Monitor la use para evitar la pérdida de datos del agente de Log Analytics.
Por ejemplo, puede usar el siguiente script de PowerShell para crear una tabla personalizada con varias columnas.
$tableParams = @'
{
"properties": {
"schema": {
"name": "{TableName}_CL",
"columns": [
{
"name": "TimeGenerated",
"type": "DateTime"
},
{
"name": "MyStringColumn",
"type": "string"
},
{
"name": "MyIntegerColumn",
"type": "int"
},
{
"name": "MyRealColumn",
"type": "real"
},
{
"name": "MyBooleanColumn",
"type": "bool"
},
{
"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
Creación de una regla de recopilación de datos para un archivo JSON
Nota:
La ingesta de archivos personalizados JSON basada en agente se encuentra actualmente en versión preliminar y aún no tiene una experiencia de interfaz de usuario completa en el portal. Aunque puede crear el DCR mediante el portal, debe modificarlo para definir las columnas de la secuencia entrante. En esta sección se incluyen detalles sobre cómo crear el DCR mediante una plantilla de ARM.
Esquema de flujo entrante
Nota:
La compatibilidad multilínea que usa una marca de tiempo de ISO 8601 para delimitar eventos se espera para mediados de octubre de 2024
Los archivos JSON incluyen un nombre de propiedad con cada valor y la secuencia entrante de DCR debe incluir una columna que coincida con el nombre de cada propiedad. Debe modificar la sección columns de la plantilla de ARM con las columnas del registro.
En la tabla siguiente se describen las columnas opcionales que puede incluir además de las columnas que definen los datos del archivo de registro.
| 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 si no se incluye en el flujo entrante. |
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. |
Transformación
La transformación modifica potencialmente el flujo entrante para filtrar los registros o modificar el esquema para que coincida con la tabla de destino. Si el esquema del flujo entrante es el mismo que la tabla de destino, puede usar la transformación predeterminada de source. Si no es así, modifique la sección transformKql de la plantilla de ARM con una consulta KQL que devuelva el esquema necesario.
Plantilla ARM
Use la siguiente plantilla de ARM para crear un DCR para recopilar archivos de registro de texto y realizar los cambios descritos en las secciones anteriores. En la tabla siguiente se describen los parámetros que requieren valores al implementar la plantilla.
| Configuración | Descripción |
|---|---|
| Nombre de la regla de recopilación de datos | Nombre único del DCR. |
| Id. de recurso del punto de conexión de recopilación de datos | Identificador de recurso del punto de conexión de recopilación de datos (DCE). |
| Location | Región del DCR. Debe ser la misma ubicación que el área de trabajo de Log Analytics. |
| Patrones 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 especificar varios patrones de archivo separados por comas (se requiere la versión AMA 1.26 o superior para varios patrones de archivo en Linux). Ejemplos: - C:\Logs\MyLog.json - C:\Logs\MyLog*.json - C:\App01\AppLog.json, C:\App02\AppLog.json - /var/mylog.json - /var/mylog*.json |
| Nombre de tabla | Nombre de la tabla de destino en el área de trabajo de Log Analytics. |
| id. de recurso del área de trabajo | Identificador de recurso del área de trabajo de Log Analytics con 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",
"apiVersion": "2022-06-01",
"name": "[parameters('dataCollectionRuleName')]",
"location": "[parameters('location')]",
"properties": {
"dataCollectionEndpointId": "[parameters('dataCollectionEndpointResourceId')]",
"streamDeclarations": {
"Custom-Json-stream": {
"columns": [
{
"name": "TimeGenerated",
"type": "datetime"
},
{
"name": "FilePath",
"type": "string"
},
{
"name": "MyStringColumn",
"type": "string"
},
{
"name": "MyIntegerColumn",
"type": "int"
},
{
"name": "MyRealColumn",
"type": "real"
},
{
"name": "MyBooleanColumn",
"type": "boolean"
}
]
}
},
"dataSources": {
"logFiles": [
{
"streams": [
"Custom-Json-stream"
],
"filePatterns": [
"[parameters('filePatterns')]"
],
"format": "json",
"name": "Custom-Json-stream"
}
]
},
"destinations": {
"logAnalytics": [
{
"workspaceResourceId": "[parameters('workspaceResourceId')]",
"name": "workspace"
}
]
},
"dataFlows": [
{
"streams": [
"Custom-Json-stream"
],
"destinations": [
"workspace"
],
"transformKql": "source",
"outputStream": "[variables('tableOutputStream')]"
}
]
}
}
]
}
Solución de problemas
Siga estos pasos si no recopila datos del registro JSON 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 secuencia entrante en el DCR coincide con el esquema en el archivo de registro.
- Compruebe que el esquema de la tabla de destino coincide con la secuencia entrante o que tiene una transformación que convertirá la secuencia entrante 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: