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 运算符。 只支持采用某一行作为输入并且返回结果不超过一行的运算符。 例如，不支持 summarize，因为它会汇总多个记录。 有关受支持功能的完整列表，请参阅受支持的 KQL 功能。

利用数据收集规则 (DCR) 中的转换，可以先筛选或修改传入的数据，然后再将这些数据存储在 Log Analytics 工作区中。 本文介绍如何在 DCR 中生成转换，包括用于转换语句的 Kusto 查询语言 (KQL) 的详细信息和限制。

必需列

每个转换的输出都必须在名为 TimeGenerated 且类型为 datetime 列中包含一个有效的时间戳。 请确保将其包括在最终的 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"
    }
]

现在，可以在 KQL 转换中分析和使用 AdditionalContext 列的内容了：

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 运算符，它始终生成一行。 例如：
print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)

表格运算符

标量运算符

数值运算符

所有数值运算符都受支持。

Datetime 和 Timespan 算术运算符

所有的 Datetime 和 Timespan 算术运算符都受支持。

字符串运算符

支持以下字符串运算符。

  • ==
  • !=
  • =~
  • !~
  • contains
  • !contains
  • contains_cs
  • !contains_cs
  • 具有
  • !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 函数

动态和数组函数

数学函数

条件函数

字符串函数

类型函数

特殊函数

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

parse_cef_dictionary 函数的示例输出。

geo_location

给定包含 IP 地址的字符串的情况下（支持 IPv4 和 IPv6），geo_location 函数会返回近似地理位置，其中包含以下属性：

  • 国家/地区
  • 区域
  • State
  • City
  • 纬度
  • 经度
| extend GeoLocation = geo_location("1.0.0.5")

geo_location 函数示例输出的屏幕截图。

重要

由于此函数使用的 IP 地理位置服务的性质，如果过度使用，它可能会导致数据引入延迟。 每次转换过多使用此函数时，请谨慎操作。

标识符引用

请根据需要使用标识符引用。

后续步骤