Crear una transformación en Azure Monitor

Transformaciones en Azure Monitor filtran o modifican los datos de entrada antes de almacenarlos en un área de trabajo de Log Analytics. Implemente las transformaciones como una instrucción del Lenguaje de consulta Kusto (KQL) en una regla de recopilación de datos (DCR). En este artículo se proporcionan instrucciones sobre cómo crear y probar una consulta de transformación y agregarla a un DCR.

Estructura básica de la consulta

Todas las consultas de transformación comienzan con source, que es una tabla virtual que representa el flujo de entrada. A continuación, puede usar cualquier operador KQL compatible para filtrar, modificar o agregar columnas a los datos como lo haría con cualquier otra tabla. La consulta se aplica individualmente a cada entrada enviada por el origen de datos.

La salida de la consulta debe coincidir con el esquema de la tabla de destino con las consideraciones siguientes:

• Omita las columnas que no quiera guardar para ahorrar costes. Al omitir una columna, esa columna está vacía para cada registro de la tabla de destino.
• Excluya las columnas que no estén en la tabla de salida. Se aceptan columnas adicionales sin errores, pero se paga por la ingesta de datos que no están almacenados.
• Incluya una marca de tiempo válida en una columna denominada TimeGenerated de tipo datetime. Si el origen de datos no incluye esta propiedad, agréguela mediante extend o project.

La siguiente transformación es un ejemplo que realiza tres funciones:

• Filtra los datos entrantes mediante una where instrucción .
• Agrega una nueva columna Properties mediante el extend operador con la parse_json función para analizar los valores JSON de la columna entrante properties .
• Da formato a la salida de transformación para que coincida exactamente con las columnas de la tabla de destino mediante el project operador .

source
| where severity == "Critical" 
| extend Properties = parse_json(properties)
| project
    TimeGenerated = todatetime(["time"]),
    Category = category,
    StatusDescription = StatusDescription,
    EventName = name,
    EventId = tostring(Properties.EventId)

Para obtener varios ejemplos de distintos escenarios, consulte Ejemplos y escenarios de reglas de recopilación de datos (DCR) en Azure Monitor.

Crear la consulta de transformación

Antes de agregar una transformación a un DCR, cree y pruebe la consulta en Log Analytics. Cuando la consulta devuelva los resultados esperados, reemplace el nombre de la tabla por source y agréguelo a su DCR, tal y como se describe en Agregar transformación a DCR.

Por ejemplo, para filtrar eventos de Syslog, comience con esta consulta en Log Analytics:

Syslog | where SeverityLevel != 'info'

A continuación, reemplace el nombre de la tabla por source en el DCR:

source | where SeverityLevel != 'info'

Agregar la transformación al DCR

Después de crear la consulta de transformación, agréguela a un DCR siguiendo estos pasos:

1. Obtenga la definición de DCR actual. Abra la definición de DCR en la interfaz de usuario y seleccione la vista JSON o exporte el JSON mediante el CLI de Azure:

   az monitor data-collection rule show --name {dcrName} --resource-group {resourceGroupName} > dcr.json
   

   Para obtener más información, vea Crear y editar reglas de recopilación de datos (DCR) en Azure Monitor.

2. Busque la sección dataFlows del DCR. En esta sección se empareja un origen de datos con un destino.

3. Agregue la transformKql propiedad JSON al flujo de datos que desea transformar. Establezca su valor en su consulta de transformación en una sola línea. La transformación se aplica a la secuencia entrante antes de enviarla al destino. Solo se aplica a ese flujo de datos, incluso si se usa la misma secuencia o destino en otros flujos de datos.

4. Guarde e implemente el DCR actualizado:

   az monitor data-collection rule update --name {dcrName} --resource-group {resourceGroupName} --body @dcr.json
   

   Para ver otros métodos, consulte Crear y editar reglas de recopilación de datos (DCR) en Azure Monitor.

Si omite la propiedad transformKql, o si establece su valor en source, no se aplica ninguna transformación. Los datos entrantes se envían al destino sin modificaciones.

En el ejemplo siguiente, no hay ninguna transformKql propiedad, por lo que los datos entrantes se envían al destino sin modificaciones.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

En el ejemplo siguiente, transformKql tiene una consulta sencilla de source, por lo que los datos entrantes se envían al destino sin modificaciones. Su funcionalidad es idéntica al ejemplo anterior.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

En el ejemplo siguiente, transformKql tiene una consulta que filtra los datos, por lo que solo se envían mensajes de error al destino.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source | where message has 'error'", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

Creación de una transformación de varias fases (versión preliminar)

Las transformaciones multietapa usan la sección transformations de un DCR para definir canalizaciones basadas en procesadores a las que los orígenes y flujos de datos hacen referencia mediante la propiedad transform. A diferencia de las transformaciones de una sola fase que usan transformKql, las transformaciones de varias fases se ejecutan en el lado cliente (antes de que los datos salgan del agente) o el lado de ingesta (antes de que los datos lleguen al área de trabajo) o ambos.

• Transformaciones del lado cliente : se ejecuta en el agente antes de enviar los datos. Estas transformaciones reducen el volumen de datos en el origen y pueden filtrar, analizar o enriquecer los datos antes de la transmisión.
• Transformaciones del lado de ingesta: se ejecutan en el servicio una vez que llegan los datos, pero antes de su almacenamiento. Estas transformaciones pueden aplicar expresiones KQL y enriquecer aún más los datos.

En una canalización de varias fases, un procesador es un paso de procesamiento con nombre que se ejecuta en secuencia, como el filtrado, el análisis, el enriquecimiento o la aplicación de KQL. El procesador de encabezados declara el formato de entrada de la canalización (por ejemplo, header.Syslog para los datos de syslog).

Para obtener detalles conceptuales, consulte Transformaciones de varias fases. Para obtener la referencia de esquema completa, consulte Estructura DCR: Transformaciones.

Creación de una transformación de varias fases

Cree una transformación de varias fases mediante el portal de Azure o mediante programación.

En el ejemplo siguiente se crea un DCR con una transformación del lado cliente que filtra los datos de syslog para mantener solo eventos de autenticación y una transformación del lado de la ingesta que aplica KQL a la secuencia antes de almacenarla.

La definición de DCR incluye estas secciones clave:

• streamDeclarations : define el esquema de los flujos personalizados usados entre las fases de procesamiento.
• dataSources : configura el origen de datos con una propiedad transform que hace referencia a la transformación del lado cliente por nombre.
• destinations : donde se envían los datos
• dataFlows - asigna flujos a destinos con una propiedad opcional transform para el procesamiento durante la ingesta
• transformations : define las canalizaciones de procesador con nombre a las que hacen referencia los orígenes de datos y los flujos de datos.

Compruebe las DCR comprobando en el portal de Azure en Monitor>Data Collection Rules.

{
    "location": "eastus",
    "properties": {
        "streamDeclarations": {
            "Custom-FilteredSyslog": {
                "columns": [
                    { "name": "TimeGenerated", "type": "datetime" },
                    { "name": "Facility", "type": "string" },
                    { "name": "Message", "type": "string" },
                    { "name": "Host", "type": "string" },
                    { "name": "SeverityNumber", "type": "int" }
                ]
            }
        },
        "dataSources": {
            "syslog": [
                {
                    "name": "syslogAuth",
                    "facilityNames": ["auth", "authpriv"],
                    "logLevels": ["*"],
                    "transform": "client_filter_auth",
                    "streams": ["Custom-FilteredSyslog"]
                }
            ]
        },
        "destinations": {
            "logAnalytics": [
                {
                    "name": "myWorkspace",
                    "workspaceResourceId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}",
                    "workspaceId": "{workspaceId}"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": ["Custom-FilteredSyslog"],
                "transform": "ingestion_enrich_syslog",
                "destinations": ["myWorkspace"],
                "outputStream": "Microsoft-Syslog"
            }
        ],
        "transformations": [
            {
                "name": "client_filter_auth",
                "headerProcessor": {
                    "processor": "header.Syslog",
                    "configuration": {}
                },
                "processors": [
                    {
                        "processor": "filter.Basic",
                        "configuration": {
                            "any": [
                                {
                                    "all": [
                                        {
                                            "columnName": "Facility",
                                            "operator": "==",
                                            "value": "auth"
                                        }
                                    ]
                                }
                            ]
                        }
                    }
                ]
            },
            {
                "name": "ingestion_enrich_syslog",
                "headerProcessor": {
                    "processor": "header.CustomStream",
                    "configuration": {
                        "streamId": "Custom-FilteredSyslog"
                    }
                },
                "processors": [
                    {
                        "processor": "transform.KQL",
                        "configuration": {
                            "expression": "source | extend EnrichedMsg = strcat(Host, ': ', Message)"
                        }
                    }
                ]
            }
        ]
    }
}

$dcr = Get-Content -Path "dcr.json" -Raw
Invoke-AzRestMethod `
    -Path "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Insights/dataCollectionRules/{dcrName}?api-version=2025-05-11" `
    -Method PUT `
    -Payload $dcr

Crear DCR de transformación del área de trabajo

La regla de recopilación de datos (DCR) de transformación del área de trabajo es una DCR especial que se aplica directamente a un área de trabajo de Log Analytics. Cada área de trabajo solo puede tener un DCR de transformación del área de trabajo, pero puede incluir transformaciones para cualquier número de tablas.

Utilice uno de los siguientes métodos para crear un DCR de transformación de su área de trabajo y agregarle una o varias transformaciones.

{
    "kind": "WorkspaceTransforms",
    "location": "eastus",
    "properties": {
        "dataSources": {},
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/71b36fb6-4fe4-4664-9a7b-245dc62f2930/resourcegroups/my-resource-group/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "MyWorkspace"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Microsoft-Table-LAQueryLogs"
                ],
                "destinations": [
                    "MyWorkspace"
                ],
                "transformKql": "source | where QueryText !contains 'LAQueryLogs'"
            },
            {
                "streams": [
                    "Microsoft-Table-Event"
                ],
                "destinations": [
                    "MyWorkspace"
                ],
                "transformKql": "source | project-away ParameterXml"
            }
        ]
    }
}

az monitor data-collection rule create \
    --name {dcrName} \
    --resource-group {resourceGroupName} \
    --body @dcr.json

Optimizar y supervisar transformaciones

Las transformaciones ejecutan una consulta KQL en todos los registros recopilados con el DCR, por lo que es importante que se ejecuten de forma eficaz. El tiempo de ejecución de la transformación contribuye a la latencia general de ingesta de datos y las transformaciones que tardan demasiado tiempo en ejecutarse pueden afectar al rendimiento de la recopilación de datos y provocar la pérdida de datos. Las transformaciones óptimas no deben tardar más de 1 segundo en ejecutarse. Consulte Optimizar consultas de registro en Azure Monitor para obtener instrucciones sobre cómo probar la consulta antes de implementarla como una transformación y para obtener recomendaciones sobre la optimización de consultas que no se ejecutan de forma eficaz.

Dado que las transformaciones no se ejecutan de forma interactiva, es importante supervisarlas continuamente para asegurarse de que se ejecutan correctamente y no tardan demasiado tiempo en procesar los datos. Consulte Supervisión y solución de problemas de recopilación de datos de DCR en Azure Monitor para más información sobre los registros y las métricas que supervisan el estado y el rendimiento de las transformaciones. Esto incluye identificar los errores que se producen en el KQL y las métricas para rastrear su tiempo de ejecución.

Las siguientes métricas se recopilan automáticamente para las transformaciones y se deben revisar periódicamente para comprobar que las transformaciones siguen ejecutándose según lo previsto. Cree reglas de alertas de métricas para recibir notificaciones automáticamente cuando una de estas métricas supere un umbral.

• Duración de la transformación de registros por minuto
• Errores de transformación de registros por minuto

Habilite los registros de errores de DCR para realizar un seguimiento de los errores que se producen en las transformaciones u otras consultas. Cree una regla de alerta de registro que se notificará automáticamente cuando se escribe una entrada en esta tabla.

Solucionar problemas de transformaciones

En las tablas siguientes se enumeran los errores de transformación comunes y sus resoluciones.

Guías de transformación por origen de datos

Hay varios métodos para crear transformaciones en función del método de recopilación de datos. En la tabla siguiente se enumeran las instrucciones de diferentes métodos para crear transformaciones.

Limitaciones y consideraciones

• Las transformaciones se ejecutan durante la ingesta y contribuyen a los costes de procesamiento de datos. Sin embargo, filtrar datos mediante transformaciones puede reducir el volumen de ingesta y los costes de almacenamiento. Para obtener más información, consulte Optimización de costos y Azure Monitor.
• No todas las tablas de un área de trabajo de Log Analytics admiten transformaciones. Para obtener una lista de las tablas admitidas, consulte Tables que admiten transformaciones en registros de Azure Monitor.
• No todos los operadores KQL son compatibles con las consultas de transformación. Para obtener más información, consulte Características de KQL compatibles en las transformaciones de Azure Monitor.
• Aunque una transformación puede enviar un único origen de datos a varias tablas, no puede enviar datos a varias áreas de trabajo. Para enviar datos desde un único origen de datos a varias áreas de trabajo, cree varias DCR.
• El DCR de transformación del área de trabajo no puede enviar un único origen de datos a varias tablas, ya que la transformación se aplica a la propia tabla.
• Las transformaciones del DCR de transformación del área de trabajo se aplican a todos los datos enviados a la tabla, independientemente del origen de datos. Si necesita aplicar diferentes transformaciones a orígenes de datos diferentes, use una where instrucción en la consulta de transformación para aplicar una lógica diferente a los datos de orígenes diferentes.
• En el caso de las transformaciones de varias fases, transform y transformKql son mutuamente excluyentes por flujo de datos. Un DCR puede mezclar flujos de datos de estilo antiguo (transformKql) y de estilo nuevo (transform) en diferentes flujos.
• Las transformaciones de varias fases requieren una versión 2025-05-11 de API o posterior.
• Los datos del contador de rendimiento requieren DCR independientes para máquinas de Windows y Linux al usar transformaciones multietapa. Un DCR de tipo All no puede usar ni header.WindowsPerformanceCountersheader.LinuxPerformanceCounters en una sola transformación del lado cliente.

Contenido relacionado

• Supervisión y solución de problemas de la recopilación de datos de DCR en Azure Monitor - Supervise el rendimiento de la transformación y diagnostique errores.
• Características de KQL compatibles en transformaciones de Azure Monitor: compruebe qué operadores KQL funcionan en transformaciones.
• Estructura de una regla de recopilación de datos (DCR) en Azure Monitor - Referencia completa del esquema JSON para las definiciones de DCR.
• Ejemplos de transformación para Azure Monitor - Consultas de transformación de ejemplo para escenarios comunes.
• Crear una regla de recopilación de datos y una asociación a ella desde una máquina virtual mediante el agente de Azure Monitor.
• Optimización de costos y Azure Monitor: comprenda cómo afectan las transformaciones a los costos de ingesta.