Structuur van transformatie in Azure Monitor

Artikel
02/28/2024

Met transformaties in Azure Monitor kunt u binnenkomende gegevens filteren of wijzigen voordat deze worden opgeslagen in een Log Analytics-werkruimte. Ze worden geïmplementeerd als een Kusto-querytaal -instructie (KQL) in een regel voor gegevensverzameling (DCR). Dit artikel bevat informatie over hoe deze query is gestructureerd en beperkingen voor de toegestane KQL-taal.

Transformatiestructuur

De KQL-instructie wordt afzonderlijk toegepast op elke vermelding in de gegevensbron. Het moet de indeling van de binnenkomende gegevens begrijpen en uitvoer maken in de structuur van de doeltabel. Een virtuele tabel met de naam source vertegenwoordigt de invoerstroom. source tabelkolommen komen overeen met de definitie van de invoergegevensstroom. Hieronder volgt een typisch voorbeeld van een transformatie. Dit voorbeeld bevat de volgende functionaliteit:

Filtert de binnenkomende gegevens met een where-instructie
Hiermee voegt u een nieuwe kolom toe met behulp van de operator uitbreiden
Hiermee wordt de uitvoer opgemaakt zodat deze overeenkomt met de kolommen van de doeltabel met behulp van de projectoperator

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

KQL-beperkingen

Omdat de transformatie afzonderlijk op elke record wordt toegepast, kunnen er geen KQL-operators worden gebruikt die op meerdere records reageren. Alleen operators die één rij als invoer gebruiken en die niet meer dan één rij retourneren, worden ondersteund. Samenvatten wordt bijvoorbeeld niet ondersteund omdat het meerdere records samenvat. Zie Ondersteunde KQL-functies voor een volledige lijst met ondersteunde functies.

Met transformaties in een regel voor gegevensverzameling (DCR) kunt u binnenkomende gegevens filteren of wijzigen voordat deze worden opgeslagen in een Log Analytics-werkruimte. In dit artikel wordt beschreven hoe u transformaties bouwt in een DCR, inclusief details en beperkingen van de Kusto-querytaal (KQL) die worden gebruikt voor de transformatie-instructie.

Vereiste kolommen

De uitvoer van elke transformatie moet een geldig tijdstempel bevatten in een kolom met de naam TimeGenerated van het type datetime. Zorg ervoor dat u deze opneemt in het laatste extend of project blok! Het maken of bijwerken van een DCR zonder TimeGenerated in de uitvoer van een transformatie leidt tot een fout.

Dynamische gegevens verwerken

Houd rekening met de volgende invoer met dynamische gegevens:

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

Als u toegang wilt krijgen tot de eigenschappen in AdditionalContext, definieert u deze als kolom voor dynamisch type in de invoerstroom:

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

De inhoud van de kolom AdditionalContext kan nu worden geparseerd en gebruikt in de KQL-transformatie:

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

Dynamische letterlijke waarden

Gebruik de functie parse_json om dynamische letterlijke waarden te verwerken.

De volgende query's bieden bijvoorbeeld dezelfde functionaliteit:

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

Ondersteunde KQL-functies

Ondersteunde instructies

let-instructie

De rechterzijde van let kan een scalaire expressie, een tabellaire expressie of een door de gebruiker gedefinieerde functie zijn. Alleen door de gebruiker gedefinieerde functies met scalaire argumenten worden ondersteund.

instructies voor tabellaire expressies

De enige ondersteunde gegevensbronnen voor de KQL-instructie zijn als volgt:

bron, die de brongegevens vertegenwoordigt. Voorbeeld:

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

printoperator , die altijd één rij produceert. Voorbeeld:

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

Tabellaire operators

Uitbreiden
Project
Afdrukken
Waar
Parse
project-away
projectnaam wijzigen
Datatable
columnifexists (gebruik columnifexists in plaats van column_ifexists)

Scalaire operators

Numerieke operators

Alle numerieke operators worden ondersteund.

Rekenkundige operatoren datum/tijd en tijdspan

Rekenkundige operatoren voor alle datum/tijd- en tijdspanne worden ondersteund.

Tekenreeksoperators

De volgende tekenreeksoperators worden ondersteund.

==
!=
=~
!~
bevat
!Bevat
contains_cs
!contains_cs
Hsa
!Hsa
has_cs
!has_cs
startswith
!startswith
startswith_cs
!startswith_cs
eindigt op
!endswith
endswith_cs
!endswith_cs
komt overeen met regex
in
!Inch

Bitsgewijze operatoren

De volgende Bitwise-operators worden ondersteund.

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

Scalaire functies

Bitsgewijze functies

Conversiefuncties

De functies DateTime en TimeSpan

Dynamische en matrixfuncties

Wiskundige functies

Voorwaardelijke functies

Tekenreeksfuncties

base64_encodestring (gebruik base64_encodestring in plaats van base64_encode_tostring)
base64_decodestring (gebruik base64_decodestring in plaats van base64_decode_tostring)
countof
Extract
extract_all
indexof
Isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
strlen
Subtekenreeks
tolower
Toupper
hash_sha256

Typefuncties

Speciale functies

parse_cef_dictionary

Gezien een tekenreeks met een CEF-bericht parseert u parse_cef_dictionary de extensie-eigenschap van het bericht in een dynamisch sleutel-/waardeobject. Puntkomma is een gereserveerd teken dat moet worden vervangen voordat het onbewerkte bericht in de methode wordt doorgegeven, zoals wordt weergegeven in het voorbeeld.

| 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

Gezien een tekenreeks met IP-adres (IPv4 en IPv6 worden ondersteund), geo_location retourneert de functie een geschatte geografische locatie, waaronder de volgende kenmerken:

Land/regio
Regio
Provincie
Plaats
Breedtegraad
Lengtegraad

| extend GeoLocation = geo_location("1.0.0.5")

Belangrijk

Vanwege de aard van de IP-geolocatieservice die door deze functie wordt gebruikt, kan dit leiden tot gegevensopnamelatentie als deze overmatig wordt gebruikt. Wees voorzichtig bij het gebruik van deze functie meer dan meerdere keren per transformatie.

Id-quotering

Gebruik id-quotering zoals vereist.

Volgende stappen

Maak een regel voor gegevensverzameling en een koppeling naar deze regel vanaf een virtuele machine met behulp van de Azure Monitor-agent.