Estructura de transformación en Azure Monitor

Artículo
10/31/2024

Las transformaciones en Azure Monitor le permiten filtrar o modificar los datos entrantes antes de almacenarlos en un área de trabajo de Log Analytics. Se implementan como una instrucción Lenguaje de consulta Kusto (KQL) en una regla de recopilación de datos (DCR). En este artículo se proporcionan detalles sobre cómo se estructura esta consulta y las limitaciones del lenguaje KQL permitido.

Estructura de transformación

La instrucción KQL se aplica individualmente a cada entrada del origen de datos. Debe comprender el formato de los datos entrantes y crear la salida en la estructura de la tabla de destino. Una tabla virtual denominada source representa el flujo de entrada. source las columnas de tabla coinciden con la definición del flujo de datos de entrada. A continuación se muestra un ejemplo típico de una transformación. En este ejemplo se incluye la funcionalidad siguiente:

Filtra los datos entrantes con una instrucción where.
Agrega una nueva columna mediante el operador extend.
Da formato a la salida para que coincida con las columnas de la tabla de destino mediante el operador project.

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

Limitaciones de KQL

Puesto que la transformación se aplica a cada registro individualmente, no puede usar ningún operador de KQL que actúe en varios registros. Solo se admiten los operadores que adoptan una sola fila como entrada y que no devuelven más de una fila. Por ejemplo, no se admite summarize, ya que resume varios registros. Vea Características compatibles de KQL para obtener una lista completa de las características admitidas.

Las transformaciones de una regla de recopilación de datos (DCR) permiten filtrar o modificar los datos entrantes antes de almacenarlos en un área de trabajo de Log Analytics. En este artículo se describe cómo crear transformaciones en una DCR, incluidos detalles y limitaciones del lenguaje de consulta Kusto (KQL) que se usan para la instrucción de transformación.

Comando parse

El comando parse de una transformación está limitado a 10 columnas por instrucción por motivos de rendimiento. Si la transformación requiere analizar más de 10 columnas, divida esto en varias instrucciones, tal y como se describe en Dividir comandos parse grandes.

Columnas necesarias

La salida de cada transformación debe contener una marca de tiempo válida en una columna denominada TimeGenerated de tipo datetime. Asegúrese de incluirla en el bloque extend o project final. La creación o actualización de un DCR sin TimeGenerated en la salida de una transformación provocará un error.

Control de datos dinámicos

Tenga en cuenta la siguiente entrada con datos dinámicos:

{
    "TimeGenerated" : "2021-11-07T09:13:06.570354Z",
    "Message": "Houston, we have a problem",
    "AdditionalContext": {
        "Level": 2,
        "DeviceID": "apollo13"
    }
}

Para acceder a las propiedades de AdditionalContext, defínala como una columna con tipo dinámico en el flujo de entrada:

"columns": [
    {
        "name": "TimeGenerated",
        "type": "datetime"
    },
    {
        "name": "Message",
        "type": "string"
    }, 
    {
        "name": "AdditionalContext",
        "type": "dynamic"
    }
]

El contenido de la columna AdditionalContext ahora se puede analizar y usar en la transformación de KQL:

source
| extend parsedAdditionalContext = parse_json(AdditionalContext)
| extend Level = toint (parsedAdditionalContext.Level)
| extend DeviceId = tostring(parsedAdditionalContext.DeviceID)

Literales dinámicos

Use la función parse_json para controlar literales dinámicos.

Por ejemplo, las siguientes consultas proporcionan la misma funcionalidad:

print d=dynamic({"a":123, "b":"hello", "c":[1,2,3], "d":{}})

print d=parse_json('{"a":123, "b":"hello", "c":[1,2,3], "d":{}}')

Características de KQL admitidas

Instrucciones admitidas

Instrucción Let

La parte situada a la derecha de let puede ser una expresión escalar, una expresión tabular o una función definida por el usuario. Solo se admiten funciones definidas por el usuario con argumentos escalares.

Instrucciones de expresiones tabulares

Los únicos orígenes de datos admitidos para la instrucción de KQL son los siguientes:

source, que representa los datos de origen. Por ejemplo:

source
| where ActivityId == "383112e4-a7a8-4b94-a701-4266dfc18e41"
| project PreciseTimeStamp, Message

Operador print, que siempre genera una sola fila. Por ejemplo:
```
print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)
```

Operadores tabulares

extend
project
print
where
parse
project-away
project-rename
datatable
columnifexists (use columnifexists en lugar de column_ifexists)

Operadores escalares

Operadores numéricos

Se admiten todos los operadores numéricos.

Operadores aritméticos Datetime y Timespan

Se admiten todos los operadores aritméticos Datetime y Timespan.

Operadores de cadena

Se admiten los siguientes operadores de cadena.

==
!=
=~
!~
contains
!contains
contains_cs
!contains_cs
has
!has
has_cs
!has_cs
startswith
!startswith
startswith_cs
!startswith_cs
endswith
!endswith
endswith_cs
!endswith_cs
matches regex
in
!in

Operadores bit a bit

Se admiten los siguientes operadores de bit a bit.

binary_and()
binary_or()
binary_xor()
binary_not()
binary_shift_left()
binary_shift_right()

Funciones escalares

Funciones bit a bit

Funciones de conversión

Funciones DateTime y TimeSpan

Funciones dinámicas y de matriz

Funciones matemáticas

Funciones condicionales

Funciones de cadena

base64_encodestring (use base64_encodestring en lugar de base64_encode_tostring)
base64_decodestring (use base64_decodestring en lugar de base64_decode_tostring)
countof
extract
extract_all
indexof
isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
strlen
substring
tolower
toupper
hash_sha256

Funciones de tipo

Funciones especiales

parse_cef_dictionary

Dada una cadena que contiene un mensaje CEF, parse_cef_dictionary analiza la propiedad Extension del mensaje en un objeto clave-valor dinámico. El punto y coma es un carácter reservado que se debe reemplazar antes de pasar el mensaje sin formato al método, como se muestra en el ejemplo siguiente.

| extend cefMessage=iff(cefMessage contains_cs ";", replace(";", " ", cefMessage), cefMessage) 
| extend parsedCefDictionaryMessage =parse_cef_dictionary(cefMessage) 
| extend parsecefDictionaryExtension = parsedCefDictionaryMessage["Extension"]
| project TimeGenerated, cefMessage, parsecefDictionaryExtension

geoubicación

Dada una cadena que contiene la dirección IP (se admiten IPv4 e IPv6), geo_location la función devuelve una ubicación geográfica aproximada, incluidos los atributos siguientes:

Country
Region
Estado
Ciudad
Latitude
Longitude

| extend GeoLocation = geo_location("1.0.0.5")

Importante

Debido a la naturaleza del servicio de geolocalización IP utilizado por esta función, puede introducir latencia de ingesta de datos si se usa excesivamente. Tenga cuidado al usar esta función más de varias veces por transformación.

Comillas de identificador

Use comillas de identificador según sea necesario.

Pasos siguientes

Cree una regla de recopilación de datos y una asociación a ella desde una máquina virtual mediante el agente de Azure Monitor.

Compartir a través de

Estructura de transformación en Azure Monitor