Structure de transformation dans Azure Monitor

Article
03/01/2024

Les transformations dans Azure Monitor vous permettent de filtrer ou de modifier des données entrantes avant qu’elles ne soient stockées dans un espace de travail Log Analytics. Elles sont implémentées en tant qu’instruction Langage de requête Kusto (KQL) dans une règle de collecte de données (DCR). Cet article fournit des détails sur la structure et les limitations de cette requête sur le langage KQL autorisé.

Structure de transformation

L’instruction KQL est appliquée individuellement à chaque entrée dans la source de données. Elle doit comprendre le format des données entrantes et créer la sortie dans la structure de la table cible. Une table virtuelle nommée source représente le flux d’entrée. Les colonnes de la table source correspondent à la définition du flux de données d’entrée. Voici un exemple typique de transformation. Cet exemple inclut la fonctionnalité suivante :

Filtre les données entrantes avec une instruction where
Ajoute une nouvelle colonne à l’aide de l’opérateur extend
Met en forme la sortie pour qu’elle corresponde aux colonnes de la table cible à l’aide de l’opérateur project

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

Limitations KQL

Étant donné que la transformation est appliquée individuellement à chaque enregistrement, elle ne peut pas utiliser des opérateurs KQL agissant sur plusieurs enregistrements. Seuls les opérateurs qui acceptent une seule ligne comme entrée et ne retournent pas plus d’une ligne sont pris en charge. Par exemple, la fonctionnalité summarize n’est pas prise en charge, car elle permet de récapituler plusieurs enregistrements. Pour obtenir la liste complète des fonctionnalités prises en charge, consultez Fonctionnalités KQL prises en charge.

Les transformations dans une règle de collecte de données (DCR) vous permettent de filtrer ou de modifier les données entrantes avant qu’elles soient stockées dans un espace de travail Log Analytics. Cet article explique comment créer des transformations dans une règle DCR, notamment des détails et des limitations du Langage de requête Kusto (KQL) utilisé pour l’instruction Transform.

Colonnes requises

La sortie de chaque transformation doit contenir un timestamp valide dans une colonne appelée TimeGenerated de type datetime. Veillez à l’inclure dans le dernier bloc extend ou project ! La création ou la mise à jour d’une DCR sans TimeGenerated dans la sortie d’une transformation entraîne une erreur.

Gestion des données dynamiques

Considérons l’entrée suivante avec des données dynamiques :

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

Pour accéder aux propriétés dans AdditionalContext, définissez-la en tant que colonne de type dynamique dans le flux d’entrée :

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

Le contenu de la colonne AdditionalContext peut désormais être analysé et utilisé dans la transformation KQL :

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

Littéraux dynamiques

Utilisez la fonction parse_json pour gérer les littéraux dynamiques.

Par exemple, les requêtes suivantes offrent la même fonctionnalité :

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":{}}')

Fonctionnalités KQL prises en charge

Instructions prises en charge

let (instruction)

La partie droite de l’instruction let peut être une expression scalaire, une expression tabulaire ou une fonction définie par l’utilisateur. Seules les fonctions définies par l’utilisateur avec des arguments scalaires sont prises en charge.

Instructions d’expression tabulaire

Voici les seules sources de données prises en charge pour l’instruction KQL :

source qui représente les données sources. Par exemple :

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

Opérateur print qui produit toujours une ligne unique. Par exemple :

print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)

Opérateurs tabulaires

extend
project
print
where
parse
project-away
project-rename
datatable
columnifexists (utilisez columnifexists au lieu de column_ifexists)

Opérateurs scalaires

Opérateurs numériques

Tous les opérateurs numériques sont pris en charge.

Opérateurs arithmétiques Datetime et Timespan

Tous les opérateurs arithmétiques Datetime and Timespan sont pris en charge.

Opérateurs de chaîne

Les opérateurs de chaîne suivants sont pris en charge.

==
!=
=~
!~
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

Opérateurs au niveau du bit

Les opérateurs au niveau du bit suivants sont pris en charge.

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

Fonctions scalaires

Fonctions au niveau du bit

Fonctions de conversion

Fonctions DateTime et TimeSpan

Fonctions dynamiques et fonctions de tableau

Fonctions mathématiques

Fonctions conditionnelles

Fonctions de chaînes

base64_encodestring (utiliser base64_encodestring au lieu de base64_encode_tostring)
base64_decodestring (utiliser base64_decodestring au lieu de base64_decode_tostring)
countof
extract
extract_all
indexof
isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
strlen
substring
tolower
toupper
hash_sha256

Fonctions de type

Fonctions spéciales

parse_cef_dictionary

Étant donné une chaîne contenant un message CEF, parse_cef_dictionary analyse la propriété Extension du message dans un objet clé/valeur dynamique. Le point-virgule est un caractère réservé qui doit être remplacé avant de transmettre le message brut à la méthode, comme illustré dans l’exemple ci-dessous.

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

geo_location

À partir d’une chaîne donnée contenant une adresse IP (IPv4 et IPv6 sont pris en charge), la fonction geo_location retourne un emplacement géographique approximatif, avec les attributs suivants :

Country
Région
State
Ville
Latitude
Longitude

| extend GeoLocation = geo_location("1.0.0.5")

Important

En raison de la nature du service de géolocalisation IP utilisé par cette fonction, une latence d’ingestion des données peut être observée dans le cas d’une utilisation excessive. Faites preuve de prudence lorsque vous utilisez cette fonction plusieurs fois par transformation.

Identificateur quoting

Utilisez l’identificateur quoting si nécessaire.

Étapes suivantes

Créez une règle de collecte de données et une association à celle-ci à partir d’une machine virtuelle à l’aide de l’agent Azure Monitor.

Structure de transformation dans Azure Monitor