Azure Monitor での変換の構造

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) の詳細と制限事項なども説明します。

必須の列

すべての変換の出力には、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()

スカラー関数

ビット単位の関数

• binary_and
• binary_or
• binary_not
• binary_shift_left
• binary_shift_right
• binary_xor

変換関数

• tobool
• todatetime
• todouble/toreal
• toguid
• toint
• tolong
• tostring
• totimespan

DateTime および TimeSpan 関数

• ago
• datetime_add
• datetime_diff
• datetime_part
• dayofmonth
• dayofweek
• dayofyear
• endofday
• endofmonth
• endofweek
• endofyear
• getmonth
• getyear
• hourofday
• make_datetime
• make_timespan
• now
• startofday
• startofmonth
• startofweek
• startofyear
• todatetime
• totimespan
• weekofyear

動的関数と配列関数

• array_concat
• array_length
• pack_array
• pack
• parse_json
• parse_xml
• zip

数学関数

• abs
• bin/floor
• ceiling
• exp
• exp10
• exp2
• isfinite
• isinf
• isnan
• log
• log10
• log2
• pow
• round
• sign

条件関数

• case
• iif
• max_of
• min_of

文字列関数

• 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 関数

• gettype
• isnotnull
• isnull

特殊な関数

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 エージェントを使用する仮想マシンからそのデータ収集ルールとの関連付けを作成します。