Recopilación de archivos JSON de una máquina virtual con Azure Monitor

2025-04-21

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. Si estos datos se almacenan en formato JSON, Azure Monitor puede recopilarlos en una regla de recopilación de datos (DCR) con un origen de datos de registros JSON personalizados .

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 JSON.

Nota:

Para trabajar directamente con la definición de DCR o para implementar con otros métodos como plantillas de ARM, consulte Ejemplos de reglas de recopilación de datos (DCR) en Azure Monitor.

Prerrequisitos

Además de los requisitos previos enumerados en Recopilación de datos del cliente de máquina virtual con Azure Monitor, necesita una tabla personalizada en un área de trabajo de Log Analytics para recibir los datos. Consulte la tabla del área de trabajo de Log Analytics para obtener más información sobre los requisitos de esta tabla.

Configuración del origen de datos de archivo JSON personalizado

Cree el DCR mediante el proceso de Recopilación de datos del cliente de máquina virtual con Azure Monitor. En la pestaña Recopilar y entregar del DCR, seleccione Registros JSON personalizados en la lista desplegable Tipo de origen de datos .

Las opciones disponibles en la configuración registros JSON personalizados se describen en la tabla siguiente.

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 la tabla	Nombre de la tabla de destino en el área de trabajo de Log Analytics.
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. Consulte Transformación para obtener un ejemplo.
Esquema JSON	Propiedades que se van a recopilar del archivo de registro JSON y que se envían a la tabla de destino. La única propiedad necesaria es `TimeGenerated`. Si el archivo JSON no proporciona este valor, se usará el tiempo de ingesta. Las otras columnas descritas en la tabla del área de trabajo de Log Analytics que no son necesarias también se pueden incluir y se rellenarán automáticamente. Cualquier otra propiedad rellenará las columnas de la tabla con el mismo nombre. Asegúrese de que las propiedades que coinciden con las columnas de tabla usan el mismo tipo de datos que la columna correspondiente. La imagen anterior muestra un esquema JSON para el archivo JSON de ejemplo que se muestra en los requisitos de archivo JSON y los procedimientos recomendados

Agregar destinos

Los registros JSON personalizados solo se pueden enviar a un área de trabajo de Log Analytics donde se almacena en la tabla personalizada que cree. Agregue un destino de tipo Registros de Azure Monitor y seleccione un área de trabajo de Log Analytics. Solo puede agregar una sola área de trabajo a un DCR para un origen de datos de registro JSON personalizado. Si necesita varios destinos, cree varias DCR. Tenga en cuenta que esto enviará datos duplicados a cada uno, lo que dará lugar a un costo adicional.

Procedimientos recomendados y requisitos de archivos JSON

El archivo que recopila el agente de Azure Monitor debe cumplir los siguientes requisitos:

El archivo debe almacenarse en la unidad local del equipo del agente en el directorio que se está supervisando.
Cada entrada debe ser LÍNEA JSON (también conocida como JSONL o NDJSON), que es una sola fila de JSON y se delimita con un final de línea. No se admite el formato de cuerpo JSON. Vea el ejemplo a continuación.
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.

A continuación se muestra un ejemplo de un archivo de registro JSON típico que Azure Monitor puede recopilar. Esto incluye los campos: Time, Code, Severity,Module y Message.

{"Time":"2025-03-07 13:17:34","Code":1423,"Severity":"Error","Module":"Sales","Message":"Unable to connect to pricing service."}
{"Time":"2025-03-07 13:18:23","Code":1420,"Severity":"Information","Module":"Sales","Message":"Pricing service connection established."}
{"Time":"2025-03-07 15:45:13","Code":2011,"Severity":"Warning","Module":"Procurement","Message":"Module failed and was restarted."}
{"Time":"2025-03-07 15:53:31","Code":4100,"Severity":"Information","Module":"Data","Message":"Daily backup complete."}

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

No destine más de 10 directorios para archivos de registro. Sondear demasiados directorios conduce a un rendimiento deficiente.
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 del área de trabajo de Log Analytics

El agente busca cualquier archivo JSON en el disco local que coincida con el patrón de nombre especificado. Cada entrada se recopila a medida que se escribe en el registro y, a continuación, se analiza antes de enviarse a la tabla especificada en un área de trabajo de Log Analytics. La tabla personalizada en el área de trabajo de Log Analytics que recibirá los datos debe existir antes de crear la DCR (Regla de Recopilación de Datos).

Las columnas de la tabla que coincidan con el nombre de un campo de los datos json analizados se rellenarán con el valor de la entrada de registro. En la tabla siguiente se describen las columnas necesarias y opcionales de la tabla del área de trabajo, además de las columnas identificadas en los datos JSON.

Columna	Tipo	¿Obligatorio?	Descripción
`TimeGenerated`	fecha y hora	Sí	Esta columna contiene la hora en que se generó el registro y es necesaria en todas las tablas. 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 un valor de la entrada de registro.
`Computer`	cuerda / cadena	No	Si la tabla incluye esta columna, se rellenará con el nombre del equipo desde el que se recopiló la entrada de registro.
`FilePath`	cuerda / cadena	No	Si la tabla incluye esta columna, se rellenará con la ruta de acceso al archivo de registro desde el que se recopiló la entrada de registro.

En el ejemplo siguiente se muestra una consulta que devuelve los datos de una tabla creada para el archivo JSON de ejemplo mostrado anteriormente. Se recopiló mediante un DCR con el esquema JSON de ejemplo mostrado anteriormente. Dado que los datos JSON no incluyen una propiedad para TimeGenerated, se usa el tiempo de ingesta. Las Computer columnas y FilePath también se rellenan automáticamente.

Creación de una tabla personalizada

Si la tabla de destino aún no existe, debe crearla antes de crear el DCR. Consulte Creación de una tabla personalizada para distintos métodos para crear una tabla. Por ejemplo, puede usar el siguiente script de PowerShell para crear una tabla personalizada para recibir los datos del archivo JSON de ejemplo anterior. En este ejemplo también se agregan las columnas opcionales.

$tableParams = @'
{
    "properties": {
        "schema": {
               "name": "{TableName}_CL",
               "columns": [
                    {
                        "name": "TimeGenerated",
                        "type": "dateTime"
                    }, 
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "FilePath",
                        "type": "string"
                    },
                    {
                        "name": "Time",
                        "type": "dateTime"
                    },
                    {
                        "name": "Code",
                        "type": "int"
                    },
                    {
                        "name": "Severity",
                        "type": "string"
                    },
                    {
                        "name": "Module",
                        "type": "string"
                    },
                    {
                        "name": "Message",
                        "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

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 transformKql sección de la plantilla de ARM con una consulta KQL que devuelva el esquema necesario.

Por ejemplo, en el ejemplo anterior, la entrada de registro tiene un Time campo que contiene la hora en que se creó la entrada de registro. En lugar de almacenarlo como una columna independiente en la tabla de destino, puede usar la siguiente transformación para asignar el valor de la Time propiedad a TimeGenerated.

source | extend TimeGenerated = todatetime(Time) | project-away Time

Esto daría lugar a la siguiente consulta de registro. Observe que la Time columna está en blanco y el valor de esa propiedad se usa para TimeGenerated.

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 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 el agente de Azure Monitor.
Más información sobre las reglas de recopilación de datos.