Azure Monitor での変換の構造

[アーティクル]
10/30/2024

Azure Monitor の変換を使用すると、Log Analytics ワークスペースに格納される前に、受信データをフィルター処理または変更できます。これらは、データコレクション規則 (DCR) の Kusto 照会言語 (KQL) ステートメントとして実装されます。この記事では、このクエリの構造と、許可されている KQL 言語の制限について詳しく説明します。

変換構造

KQL ステートメントは、データソース内の各エントリに個別に適用されます。受信データの形式を理解し、ターゲットテーブルの構造で出力を作成する必要があります。 source という名前の仮想テーブルは入力ストリームを表します。 source テーブル列は入力データストリーム定義と一致します。変換の一般的な例を次に示します。この例には、次の機能が含まれています。

where ステートメントを使用して受信データをフィルター処理します。
extend 演算子を使用して新しい列を追加します。
project 演算子を使用して、ターゲットテーブルの列と一致するように出力を書式設定します。

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

KQL の制限事項

変換は各レコードに個別に適用されるので、複数のレコードに対して機能する KQL 演算子を使用することはできません。入力として 1 行を受け取り、1 行以下を返す演算子だけがサポートされます。たとえば、summarize は複数のレコードを集計するので、サポートされません。サポートされているすべての機能の一覧については、「サポートされている KQL 機能」を参照してください。

データ収集ルール (DCR) の変換を使用すると、Log Analytics ワークスペースに格納される前に、受信データをフィルター処理または変更できます。この記事では、DCR で変換を構築する方法について説明します。変換ステートメントに使用される Kusto クエリ言語 (KQL) の詳細と制限事項なども説明します。

コマンドの解析

変換の解析コマンドは、パフォーマンス上の理由から、1 ステートメントあたり 10 列までに制限されています。変換に 10 列以上の解析が必要な場合は、「大きな解析コマンドを分割する」で説明したように複数のステートメントに分割してください。

必須の列

すべての変換の出力には、datetime 型の TimeGenerated という名前の列に、有効なタイムスタンプが含まれている必要があります。必ず、最後の extend または project ブロックにそれを含めます。変換の出力に TimeGenerated が含まれない DCR を作成または更新すると、エラーが発生します。

動的データの処理

動的データでは次の入力を考慮します。

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

AdditionalContext のプロパティにアクセスするには、入力ストリームでそれを文字列型の列として定義します。

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

AdditionalContext 列の内容を KQL 変換で解析して使用できるようになりました。

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

動的リテラル

動的リテラルを処理するには、parse_json 関数を使います。

たとえば、次のクエリでは同じ機能が提供されます。

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

サポートされている KQL 機能

サポートされているステートメント

let ステートメント

let の右側には、スカラー式、表形式の式、またはユーザー定義関数を指定できます。スカラー引数を使用するユーザー定義関数だけがサポートされています。

表形式の式ステートメント

KQL ステートメントでサポートされているデータソースは次のとおりです。

source はソースデータを表します。次に例を示します。

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

print 演算子は、常に 1 つの行を生成します。次に例を示します。
```
print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)
```

テーブル演算子

extend
project
print
where
parse
project-away
project-rename
datatable
columnifexists (column_ifexists の代わりに columnifexists を使用します)

スカラー演算子

数値演算子

すべての数値演算子がサポートされています。

Datetime および Timespan 算術演算子

すべての Datetime および Timespan 算術演算子がサポートされています。

文字列演算子

以下の文字列演算子がサポートされています。

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

ビットごとの演算子

次のビットごとの演算子がサポートされています。

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

スカラー関数

ビット単位の関数

変換関数

DateTime および TimeSpan 関数

動的関数と配列関数

数学関数

条件関数

文字列関数

base64_encodestring (base64_encode_tostring の代わりに base64_encodestring を使用します)
base64_decodestring (base64_decode_tostring の代わりに base64_decodestring を使用します)
countof
extract
extract_all
indexof
isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
strlen
substring
tolower
toupper
hash_sha256

Type 関数

特殊な関数

parse_cef_dictionary

CEF メッセージを含む文字列を指定すると、parse_cef_dictionary はメッセージの Extension プロパティを動的なキー/値オブジェクトに解析します。セミコロンは、例に示すように、生メッセージをメソッドに渡す前に置き換える必要がある予約文字です。

| 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

IP アドレス (IPv4 と IPv6 がサポートされている) を含む文字列を指定すると、geo_location 関数からは、次の属性を含む地理的なおおよその場所が返されます。

Country
リージョン
都道府県
市町村
経度
Longitude

| extend GeoLocation = geo_location("1.0.0.5")

重要

この関数で活用される IP 位置情報サービスの性質に起因し、過度に使用されるとデータインジェストに遅延が発生することがあります。この関数を 1 回の変換で複数回使用するときは注意が必要です。

識別子の引用符

必要に応じて識別子の引用符を使用します。

次の手順

データ収集ルールを作成し、Azure Monitor エージェントを使用する仮想マシンからそのデータ収集ルールとの関連付けを作成します。

次の方法で共有