日志服务数据加工语法框架与样例

概述

当前数据加工过程全面采用ETL语言，使得操作更简洁、更灵活。关于具体使用方法，您可以先参阅ETL语言的基础介绍，此处不再赘述。

1. 全局操作事件

1.1. 字段赋值(set event)

1.1.1. 语法介绍

语法格式如下：

SET_EVENT_新字段 = 固定值
SET_EVENT_新字段 = 表达式函数

说明如下：

• 用于设置单个字段的数值，字段名称即为新字段；若该字段已存在，新值将直接覆盖原有值。
• 新字段的命名规则：支持中文、英文、数字、下划线的组合，但不能以数字开头。虽支持中文字符，但不支持:符号，因此无法通过此方式设置日志中的tag等字段，此类需求可参考通用操作。
• 若表达式函数返回None，则本次赋值操作将被跳过。
• 表达式函数返回的任意类型值都会被转换为字符串（例如数字会先格式化再写入事件中）。
• 完整的表达式函数列表，请参见表达式函数章节。

1.1.2. 样例

例子1：设置固定值
添加一个新字段city，其值为上海。

SET_EVENT_city = "上海"

例子2：复制字段值
调用单个表达式函数v，将现有字段ret的值赋给新字段result。

SET_EVENT_result = v("ret")

例子3：动态设置值
组合调用表达式函数，从字段ret和return中取第一个存在的值，转换为小写后赋值给result。

SET_EVENT_result = str_lower(v("ret", "return"))

1.2. 字段提取 (extract event)

1.2.1. 语法介绍

语法：

EXTRACT_EVENT_字段 = 字符串
EXTRACT_EVENT_字段 = 字段操作类函数

说明：

• 对单个字段的值进行操作，通常用于提取多个字段——例如使用正则、展开JSON、查表富化、键值对拆分等。也包括根据字段值将一条事件分裂成多条。
• 字符串是字段操作类函数REGEX的一种简写形式。
• 提取出的多个值，默认仅在原字段不存在或值为空时覆盖。更详细的覆盖规则见后面“提取字段的值检查与覆盖模式”部分。
• 字段的命名规则同样：中英文、数字、下划线组合，不能以数字开头。不支持:，故不能操作日志的tag，相关需求请参考通用操作。
• 表达式函数返回None时操作被忽略。
• 完整字段操作类函数信息，请参考字段类操作函数章节。

1.2.2. 样例

例子1：正则表达式提取值
从字段email中提取用户名user和邮箱域名company：

EXTRACT_EVENT_email = r"(?P\w+)@(?P\w+).com"

注意，字符串是正则表达式REGEX的简写方式，更多用法可参考手册。

例子2：根据字段值映射新字段
根据字段level的值，通过LOOKUP映射出新字段level_info：

EXTRACT_EVENT_level = LOOKUP({"1": "info","2": "warning","3": "error", "*": "other"},"level_info")

例子3：展开JSON
根据字段request_body和response_body的值，调用JSON自动展开（默认深度为10）成多个值：

EXTRACT_EVENT_request_body = JSON
EXTRACT_EVENT_response_body = JSON(depth=1)

不带参数的JSON是简化写法，更多参数请参考手册。

1.3. 通用操作

1.3.1. 语法介绍

语法：

TRANSFORM_ANY = 操作
TRANSFORM_ANY = 操作列表

操作有三种形式，包括前面两种操作的扩展版，外加第三种“事件操作类函数”：

• 字段赋值操作：{"新字段名": 固定值或表达式函数, "另一个字段名": ...}
• 字段提取操作：字段输入, 字符串或字段操作类函数
• 一般操作：事件操作类函数

操作列表：多个操作可以组成列表，例如[操作1, 操作2, 操作3, ...]，按顺序依次执行，除非某个操作将事件丢弃。注意，多个操作必须用[]括起来。

说明：

• 字段赋值操作采用{key1: value1, key2: value2}的键值对形式，支持同时为多个字段赋值。
• 字段提取操作是一个输入, 操作的配对，输入不限于单个字段，例如OSSLOOKUP支持多个输入进行映射。
• 一般操作用于对事件进行常规处理，如丢弃事件、保留/丢弃特定字段、输出事件等。
• 多个通用操作需要使用不同的占位符来区分，一般按数字累加即可。
• 完整的事件操作类函数信息，请参考事件类操作函数章节。

1.3.2. 样例

例子1：多个字段赋值操作
同时对多个字段赋值，也支持表达式函数：

TRANSFORM_ANY = {"__topic__": "default topic", "tag:__type__": v("event_type"), "level": "1"}

例子2：根据字段值提取
根据字段request_body的值，调用JSON展开：

TRANSFORM_ANY = "request_body", JSON(depth=1)

例子3：一般操作
丢弃事件中的字段field1和field2：

TRANSFORM_ANY = DROP_F(["field1", "field2"])

例子4：多个操作
多个操作按顺序执行：

TRANSFORM_ANY = [ {"email": "abc@default.com"}, ("request_body", JSON) ]

例子5：表达式函数与操作类函数互操作
根据字段valid的值是否为true来保留或丢弃事件：

TRANSFORM_ANY = op_if(op_eq(v("valid"), "true"), KEEP, DROP)

这里的KEEP和DROP分别表示保留和丢弃事件的标识。

1.4. 带条件的通用操作

1.4.1. 语法介绍

语法：

TRANSFORM_EVENT = 条件操作
TRANSFORM_EVENT = 条件操作列表

条件操作：带条件的通用操作——条件满足则执行操作，否则无动作。

条件操作 = 条件, 操作

注意，这里的操作也可以是操作列表，详情参考前面“操作”部分。

条件：用于判断当前事件是否满足特定条件，有三种形式：

• 固定条件标识（例如ANY、ALL）
• 键值对：{"字段名1", "正则表达式1"}，支持NOT、多字段AND等
• 表达式函数
• 以上形式的列表（OR关系）

条件操作的列表：由多个条件操作组成的列表，每次检查每个条件，满足则执行对应操作，然后继续检查下一个，除非某一步丢弃了事件。整个列表必须用[]括起来，每个条件操作需用()括起来。

条件语法说明

• 固定条件标识：例如ANY、ALL表示所有事件都会匹配。
• 键值对{key: value}是对字段值用正则进行完全匹配（从头到尾完全匹配才算满足）。比如字段user的值为"i love python"，那么正则"i love"或"python"都无法匹配。多个键值对是AND关系，必须全部满足。
• 对正则使用NOT修饰后，逻辑变为not。
• 通过表达式函数的返回值作为判断条件（空、None、False、0、空列表等视为不满足，其他视为满足）。
• 多个条件列表组合表达OR关系，只要有一个满足即执行操作。
• OR、AND、NOT目前版本不能任意嵌套，复杂逻辑请使用表达式函数。

1.4.2. 样例

例子1：值匹配后操作
当字段result值为failed或failure时，设置事件主题为login_failed_event：

TRANSFORM_EVENT = {"result": r"failed|failure"}, {"__topic__": "login_failed_event"}

例子2：根据字段值判断再提取
当字段request_body存在且非空时，调用JSON展开：

TRANSFORM_EVENT = NO_EMPTY("request_body"), ("request_body", JSON)

这里NO_EMPTY是特定表达式函数，表示字段存在且非空。

例子3：高级判断再操作
当字段valid的值是failed时，丢弃事件：

TRANSFORM_EVENT = op_if(v("valid"), "failed"), DROP

例子4：多个条件操作
多个操作按顺序执行：

TRANSFORM_EVENT = [ (ANY, {"__topic__": "default_login"}), ( {"valid": "failed"}, {"__topic__": "login_failed_event"} ) ]

注意，多个条件操作要用[]括起来，每个条件操作都用()括起来。

1.5. 基于条件分派操作

1.5.1. 语法介绍

语法：

DISPATCH_EVENT_占位符 = 条件操作列表

说明：形式与带条件的通用操作基本一致，区别在于——这里的多个条件操作列表，每次检查每个条件，一旦满足就执行对应的操作（或操作列表），然后跳过后面的条件操作，不再继续检查。

1.5.2. 样例

例子：条件分派
按字段http_status设置不同的事件主题：

DISPATCH_EVENT = [ ({"http_status": r"2\d+"} , {"__topic__": "success_event"}), ({"http_status": r"3\d+"} , {"__topic__": "redirection_event"}), ({"http_status": r"4\d+"} , {"__topic__": "unauthorized_event"}), ({"http_status": r"5\d+"} , {"__topic__": "internal_server_error_event"}), ]

同样，多个条件操作用[]括起来，每个条件操作用()括起来。

1.6. 常见事件操作的简化宏

1.6.1 保留/丢弃事件

语法
对满足条件的事件进行保留或丢弃。

KEEP_EVENT = 条件
DROP_EVENT = 条件

说明
条件与带条件的通用操作中的条件一致，可以是列表，参考条件部分。

1.6.2 保留/丢弃字段

语法
对满足条件的字段名进行保留或丢弃。

KEEP_FIELDS = 字符串或字符串列表
DROP_FIELDS = 字符串或字符串列表

字符串这里指的是正则表达式，当字段名匹配时保留或丢弃。列表则是用[]括起来的正则表达式列表，例如["abc", "xyz"]。系统还提供了一些预定义的元字段标识，比如F_TIME表示时间字段，F_META表示时间、主题等字段。

说明

• 条件与带条件的通用操作一致。
• 需要注意的是，日志服务中的事件还包含隐藏的元字段，例如__time__、__topic__等。如果删除了__time__，事件时间会被重置为当前时间。使用KEEP_FIELDS时要特别小心，避免误删关键字段。
• 常用的KEEP_FIELDS格式为：[F_TIME, F_META, F_TAGS, "f1", "f2" ]

1.6.3 重命名字段

语法

RENAME_FIELDS = {"现有字段名正则1": "新字段名1", "现有字段正则2": "新字段名2", ...}

说明
这里的“现有字段名”实际是正则表达式，如果有多个字段匹配，所有匹配的字段都会改为新字段名，但新字段名的值只会是其中一个（具体哪个不确定）。主要用在多种数据源的日志混合时，统一简化字段名。

1.6.4 输出事件

将满足条件的事件输出。

语法

OUTPUT = 条件
COUTPUT = 条件

说明

• OUTPUT：满足条件的事件输出后，不再进行后续处理（相当于被丢弃）。
• COUTPUT：满足条件的事件输出后，还会继续后续处理（相当于复制了一份输出）。
• 事件操作类函数中的OUTPUT和COUTPUT支持更多行为定制，参考事件类操作函数。

2. 表达式函数

表达式函数是返回特定值的表达式，一般为单个函数或其调用组合。覆盖以下几大类，目前有100多个，且持续增加：

• 基本操作函数：字段取值、控制、比较、容器判断、字段存在性判断、多字段操作等
• 转换函数：基础类型转换、数字转换
• 算术函数：基础计算、多值计算比较、数学计算、数学参数等
• 字符串函数：多字段操作、编码/解码、排序/倒叙、替换、常规规整、查找判断、切分、格式化、字符集判断等
• 日期时间函数：智能日期时间转换、获取日期时间属性、获取日期时间、获取Unix时间戳、获取日期时间字符串、修改日期时间、比较日期时间等
• 正则表达式函数：字段提取、匹配判断、替换、切分等

详细用法请参考用户手册。

3. 字段类操作函数

基于输入字段的值进行操作。注意：目前不支持字段类操作函数与表达式函数互操作。

覆盖以下几大类，持续增加中：

• 正则提取列：正则的完整支持，包括动态提取字段名等
• CSV格式提取：CSV标准支持
• 字典映射：直接字段映射
• 外部OSS多列映射：从外部OSS上的CSV进行数据富化，支持增量刷新、宽匹配等
• 外部数据库多列映射：从外部数据库进行数据富化，支持动态刷新、宽匹配等
• 外部Logstore多列映射：从外部Logstore进行数据富化，支持增量刷新、宽匹配等
• 自动KV：自动提取键值对，支持自定义分隔符、auto-escape场景
• JSON自动展开：自动展开JSON内容，包括数组，支持展开过程定制
• JSON-JMES过滤：基于JMES的动态选择与计算后再处理
• 分裂事件（基于JSON数组或字符串）：基于字符串数组或JSON数组进行事件分裂
• 多列合并（基于JSON数组或字符串）：基于字符串数组或JSON数组进行多字段合并

详细内容请参考用户手册。

提取字段的值检查与覆盖模式

关键字字符集：

执行此策略的方法有：REGEX（动态Key名）、JSON、KV。默认字符集：[一-龥ࠀ-一a-zA-Z][\w\-.]*。不符合规范的例子：123=abc、1k=200、{"123": "456"}等。

设置覆盖模式：通过参数mode

支持的提取方式：REGEX、KV、CSV、Lookup、JSON

("msg",REGEX(r"(\w+):(\d+)",{r"k_1": r"v_2"}, mode="fill-auto")

• fill – 当原字段不存在或者值为空时
• add – 当原字段不存在时设置
• overwrite – 总是设置
• fill/add/overwrite-auto – 当新值非空时才操作
• 默认：fill-auto

4. 事件类操作函数详情

对事件进行直接操作的函数。

覆盖以下几类：

• 多字段KV提取
• 事件Meta操作：字段丢弃、重命名
• 事件输出：复制输出、输出后丢弃、多目标配置、重载元meta、附加更多TAG等

注意：事件类操作也支持与特定表达式函数互操作，比如被表达式函数返回。

更多详情请参考用户手册。

进一步参考

• 日志服务最佳实践汇总（持续更新）
• 完整DSL语法介绍与参考PDF下载（持续更新）

数据加工指南

介绍：
功能概述 · 概念原理

快速开始：
快速开始（SLB日志加工实战）· 控制台操作 · 源与目标 · 访问秘钥配置 · 作业诊断指南 · 性能指南 · 成本优化指南

语法：
DSL语法介绍 · 查询字符串语法 · JMES语法介绍

管理配置：
子账号授权配置