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) si tiene previsto usar vínculos privados de Azure Monitor. El punto de conexión de recopilación de datos debe estar 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.

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 entrante definida por el usuario se usa para analizar los datos de registro en columnas.
3. 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 debería usar una tabla personalizada existente usada por los agentes de MMA. Los agentes de MMA no podrán escribir en la tabla una vez que el primer agente de AMA escriba en la tabla. Debería crear una nueva tabla para que el AMA la use para evitar la pérdida de datos del MMA.

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"
                    }
              ]
        }
    }
}
'@

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. Vea la pestañaplantilla de Resource Manager para obtener más información sobre cómo crear el DCR necesario.

Flujo de entrada

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. Si crea el DCR mediante Azure Portal, las columnas de la tabla siguiente se incluirán en la secuencia entrante y debe modificar manualmente el DCR o crearlo mediante otro método en el que pueda definir explícitamente la secuencia entrante.

Columna	Type	Descripción
TimeGenerated	datetime	Hora en que se generó el registro.
RawData	string	Esta columna estará vacía para un registro JSON.
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 entrante.

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 JSON 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.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.
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 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: Modifique con la lista de columnas del registro JSON que está recopilando.
• transformKql: Modifique la transformación predeterminada si el esquema de la secuencia entrante no coincide con el esquema de la tabla de destino. 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. "
            }
        },
        "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."
            }
        },
        "dataCollectionEndpointResourceId": {
		"type": "string",
		"metadata": {  "description": "Resource ID of the Data Collection Endpoint to be used with this rule."
		}
	  }
    },
    "variables": {
      "tableOutputStream": "[concat('Custom-', parameters('tableName'))]]"
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location":  "[parameters('location')]",
            "apiVersion": "2022-06-01",
            "properties": {
                "streamDeclarations": {
                    "Custom-JSONLog-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-dataSource"
                        }
                    ]
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId":  "[parameters('workspaceResourceId')]",
                            "name": "workspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-JSONLog-stream"
                        ],
                        "destinations": [
                            "workspace"
                        ],
                        "transformKql": "source",
                        "outputStream": "[variables('tableOutputStream')]"
                    }
                ]
                "dataCollectionEndpointId" : "[parameters('dataCollectionEndpointResourceId')]"
            }
        }
    ]
}

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:

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