日志服务创建加工任务-操作指南-文档中心-腾讯云

前提条件
已开通日志服务，创建源日志主题、并成功采集到日志数据。
已创建目标日志主题。建议目标日志主题为空主题，便于加工好的数据写入。
确保当前操作账号拥有配置数据加工任务的权限，参见 CLS 访问策略模板。
注意：
数据加工只能处理实时日志流，不能处理历史日志。
操作步骤
1. 登录 日志服务控制台，在左侧导航栏中单击数据加工。  
2. 单击新建加工任务。
3. 基本配置：
配置项
﻿
说明
基本信息
任务名称
数据加工任务的名称
﻿
启用状态
任务启动/停止
﻿
前置数据加工
日志采集至 CLS，先进行数据加工(过滤、结构化)，再写入日志主题。
前置数据加工的价值：
在前置加工中做日志过滤，可有效降低日志写流量、索引流量、索引存储量、日志存储量；
在前置加工中做日志结构化，开启键值索引后，可使用 SQL 对日志进行分析、配置仪表盘和告警。
您也可以在 采集配置 页面底部，点击数据加工，进入前置数据加工编辑页面：
说明：
每个日志主题仅能配置一个前置加工任务。
前置数据加工无需配置源日志主题/目标日志主题。
前置加工暂不支持分发日志到多个固定日志主题，或动态日志主题。
若您新增/修改了采集配置，请酌情调整前置加工任务的语句，确保加工语句的有效性。
﻿
数据加工服务日志
数据加工任务运行日志，保存在 cls_service_log 服务日志主题（免费），数据加工任务监控图表中的告警功能依赖该日志主题。默认开启。
源日志主题
日志主题
非前置数据加工任务的输入，您可选择日志主题作为数据加工任务的输入。
目标日志
主题
固定日志主题
非前置数据加工任务的输出，您可选择单个或者多个日志主题作为加工结果的输出。
目标名称： 如果您的输出是多个目标日志主题，例如将源日志主题中，warning 日志输出到名称为 waring 的日志主题，将 error 日志输出到名称为 error 的日志主题，那么需要配置目标名称，建议使用英文，您将在加工函数 log_output() 中使用到该名称。
﻿
动态日志主题
非前置数据加工任务的输出，适用于目标日志主题暂不能确定的场景。例如：您需要根据日志字段"pd"的值，动态创建多个目标日志主题，并将对应的日志分发至目标日志主题。
示例：假设 pd 的值为"CLB "、"Ckafka"、"COS"、"CDN"，将会动态创建出名为"CLB"、"Ckafka"、"COS"、"CDN"的目标日志主题，并将相关日志写入对应的日志主题中。动态分发使用 log_auto_output 函数。
超限处理。当您的数据加工任务生成的主题个数超出了 产品规格，您可以选择：
创建兜底日志集、日志主题并将日志写入兜底主题（创建任务时创建）。
兜底日志集：auto_undertake_logset，单地域单账号下一个；
兜底日志主题：auto_undertake_topic_$(数据加工任务名称)。例如用户创建了两个数据加工任务 etl_A 和 etl_B，那么会产生两个兜底主题：auto_undertake_topic_etl_A、auto_undertake_topic_etl_B。
丢弃日志数据：不创建兜底主题，直接丢弃日志。
4. 配置完成后单击下一步。
5. 编辑加工语句。
固定目标日志主题
动态目标日志主题
前置数据加工
注意：
语句模式下，您可使用所有数据加工函数；交互模式仅支持部分函数。
交互模式
语句模式
添加可视化函数：点击
﻿
，选中您需要添加的可视化函数大类、可视化函数名称。
调试可视化函数：点击可视化函数右上角的▶️。
删除可视化函数：点击可视化函数右上角的 X。
编辑可视化函数：点击可视化函数右上角的 
﻿
。
当前支持的可视化函数如下：
函数大类
可视化函数名称
使用场景
提取键值
JSON：从 JSON 节点中提取字段和字段值
分隔符：根据分隔符提取字段值，需要用户填字段名
正则：根据正则公式提取字段值，需要用户填写字段名
日志结构化
日志处理
删除日志，您可配置删除日志的条件（多个条件为 OR 的关系）。例如字段 A 存在，或者字段 B 不存在，则删除该条日志。
删除/保留日志
字段处理
删除字段
重命名字段
删除/重命名字段
加工案例：JSON 可视化函数提取键值
原始日志:  
日志中有两个字段 log 和 message，可对其进一步结构化。
{
    "log": "{\\"offset\\":281,\\"file\\":{\\"path\\":\\"/logs/gate.log\\"}}",
    "message": "2024-10-11 15:32:10.003 DEBUG [gateway3036810e0c33b] ",
    "content":"cls_ETL|1.06s|fields_renamed"
}
 可视化加工函数：
﻿
﻿
﻿
 加工结果：
提取出来新的字段和字段值如下:
{
"dates":"2024-10-11 15:32:10.003",
"delay_time":"1.06s",
"level":"DEBUG",
"module":"cls_ETL",
"msg":"fields_renamed",
"offset":"281",
"path":"/logs/gate.log",
"traceid":"gateway3036810e0c33b"
}
可视化函数的配置：
可视化函数
配置项目
例子中配置的值
是否必填
说明
提取键值-JSON
描述
-
否
填写您对该加工函数的描述
﻿
字段
log
是
选中您要处理的原字段
﻿
新字段前缀
-
否
为提取出来的新字段名称添加前缀
﻿
新字段后缀
-
否
为提取出来的新字段名称添加后缀
﻿
原字段自动删除
☑️
否
加工完成后，删除原字段
提取键值-正则
描述
-
否
填写您对该加工函数的描述
﻿
字段
message
是
选中您要处理的原字段
﻿
正则表达式
(\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}.\\d{3}) ([A-Z]{5}|[A-Z]{4}) \\[(.+)\\]
是
\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}.\\d{3} 提取为新字段 dates；
([A-Z]{5}|[A-Z]{4})提取为新字段 level；
[(.+)\\]提取为新字段 traceid。
﻿
新字段
dates、level、traceid
是
使用正则公式提取的新字段
﻿
原字段自动删除
☑️
否
加工完成后，删除原字段
提取键值-分割符
描述
-
否
填写您对该加工函数的描述
﻿
字段
content
是
选中您要处理的原字段
﻿
分割符
：
是
分割日志为多个新字段的值
﻿
新字段
module、delay_time、msg
是
使用分割符提取的新字段
﻿
原字段自动删除
☑️
否
加工完成后，删除原字段
您查看页面左侧加工函数说明和示例。您可以将示例复制/粘贴到加工语句的编辑框中，修改对应的参数，完成 DSL 函数的编写；
您也可以参见 加工实战案例 文档，帮助您更快地理解 DSL 函数的编写。
说明：
语句模式切换为交互模式后，将使用交互模式下生成的语句，覆盖您的加工语句，请提前保存您的语句。
原始日志数据
[
    {
        "pd": "CLB",
        "dateTime": "2023-05-25T00:00:26.579"
    },
    {
        "pd": "Ckafka",
        "time": "2023-05-25T18:00:55.350+08:00"
    },
    {
        "pd": "COS",
        "time": "2023-05-25T00:06:20.314+08:00"
    },
    {
        "pd": "CDN",
        "time": "2023-05-25T00:03:52.051+08:00"
    }
]
数据加工语句
log_auto_output(v("pd"),"我的日志集",index_options="content_index", period=3)
预览结果
自动生成了四个日志主题，分别是"CLB "、"Ckafka"、"COS"和"CDN"，日志集名称为"我的日志集"，如下图所示：
﻿
log_auto_output( )函数参数
参数名称
参数描述
参数类型
是否必须
参数
默认值
参数说明
topic_name
日志主题名称
string
y
-
参数 topic_name 中包含"|"，"|"将在生成的主题名称中被去除；
参数 topic_name 长度超出250字符，生成的日志主题名称仅有前250个字符，超出的会被截断。
logset_name
日志集名称
string
y
-
-
index_options
all_index：开启键值、全文索引
no_index：不开启索引
content_index：开启全文
key_index：开启键值索引
string
n
all_index
如果storage_type=cold，即低频存储，则all_index和key_index不会生效，即低频存储不支持键值索引
period
存储周期，一般取值范围是1 - 3600 天，
3640 代表永久存储
number
n
30
1 - 3600 天
storage_type
日志主题的存储类型，可选值
hot：标准存储
cold：低频存储
string
n
hot
当为 cold 时，period 最小为 7 天
hot_period
0：关闭日志沉降
非0：开启日志沉降后标准存储的天数
HotPeriod 需要大于等于7，且小于 Period，仅在 StorageType 为 hot 时生效
number
n
0
-
tag_dynamic
为日志主题添加动态标签，和 extract_tag() 函数配合使用，用于从日志字段中提取标签的 KV，例如：tag_dynamic=extract_tag(v("pd"),v("env"),v("team"), v("person"))
string
n
-
和 tag_static 一起不超过10对标签
tag_static
为日志主题添加静态标签，例如：tag_static="Ckafka:test_env,developer_team:MikeWang"
string
n
-
和 tag_dynamic 一起不超过10对标签
特殊情况处理
创建日志主题
特殊场景
处理逻辑
参数 topic_name 获取失败或者为""（空字符串），该行日志将进入名称为"null"的日志主题
例如指定 app 字段的值为 topicname，即日志主题名称，但某行日志中没有 app 字段，或者其值为" "，那么该行日志将写入名称为"null"的日志主题，"null"主题所属日志集，是本函数的日志集参数中指定的日志集。
说明：
如果您使用了字符串拼接来指定日志主题名称，例如 log_auto_output( str_join("-", "myprefix", v("app")), " mylogset ",period=14,storage_type="hot",hot_period=10)，那么当 app 不存在或者值为""时，日志将写入名称为"myprefix"的日志主题。
重名主题（同一日志集下）
已存在名为"Nginx"的日志主题，动态创建任务根据规则，也要创建名为"Nginx"的日志主题时，会加上 "CreateByCLSETL" 后缀，创建出的日志主题名为" Nginx-CreateByETL"。
创建日志集
特殊场景
处理逻辑
重名日志集（同一地域）
如您手动创建名为"mylogset"的日志集，动态创建任务根据函数规则也要创建名为"mylogset"的日志集时，会自动加上 CreateByCLSETL 为后缀。
如果自动创建任务1 创建出来的日志集名称为"mylogset"，自动创建任务2同样定义了日志集名称为"mylogset"，此时自动创建任务2会使用同一个日志集名称"mylogset"作为目标日志集，即不会再自动创建带有 CreateByCLSETL 后缀的日志集。
注意：      
日志集和日志主题名称，不区分英文大小写，abc 和 Abc 在 CLS 侧代表同一个资源。
日志主题添加标签
特殊场景
处理逻辑
动态标签的 KV 值获取失败
例如指定 A 字段的值为标签的 Key，B 字段的值为标签的 Value，但某行日志没有 A 字段或者 B 字段，或者 A 字段 B 字段的值为空，标签添加失败。
标签的 KV 值前后有空格
标签添加失败。
动态标签和静态标签的总数超过10对
动态标签优先级较高，如添加完动态标签后，还不足10对，补充静态标签，但总个数不超过10对。
标签 KV 的长度超出限制
标签的 key 长度大于127，value 的长度大于255，标签添加失败。
注意：
修改 log_auto_output() 函数中的参数，并重启任务之后，仅对新生成的主题生效，已生成的主题不受影响。如您需要对已经生成日志集、日志主题进行修改，请前往 日志主题列表 控制台或调用 API 进行修改。
在不修改 log_auto_output 函数的前提下，您修改数据加工任务动态创建的主题名称、兜底日志集名称、兜底日志主题名称之后，数据分发逻辑不受影响。例如加工任务已动态创建日志主题"Nginx"，您将其改名为"Nginx001"，数据还是会写入这个"Nginx001"主题，而不会新创建一个叫做"Nginx"的日志主题。
删除数据加工任务（动态创建主题），不会删除已创建的日志集和日志主题。
说明：
如果您在 POC 时需要反复重建同名加工任务，其流程如下：
先删除老的数据加工任务，否则还会持续生成日志主题；
删除兜底主题 auto_undertake_topic_${etl-task-name} ，如果连续3次创建同名任务，超限兜底主题会创建失败，进而阻塞任务正常启动；
如果 POC 的数据是同一套，不是实时数据，建议把老任务已经生成的日志集和日志主题也删掉。
前置数据加工的语句编写，请您参考固定目标日志主题 Tab 页面的说明。
说明：
每个日志主题仅能配置一个前置加工任务。
前置加工暂不支持分发到多个日志主题，或动态目标日志主题。因此您无法在前置加工任务中使用 log_output 和 log_auto_output 函数。
前置加工任务和非前置的加工任务不支持互转。
6. 调试加工语句：您可以使用原始日志或测试数据对 DSL 语句进行调试。
原始日志：系统会自动加载原始日志数据，默认100条。
测试数据：系统随机加载的原始数据，可能无法满足您的调试需求，那么您可在原始数据页签，单击加入测试数据，将原始日志加入到测试数据中，然后在测试数据页签，修改这些数据，使其满足您的调试需求。
        
﻿
﻿
完成 DSL 加工语句的编写后，单击页面左上角执行预览或者断点调试（交互模式下为可视化函数右上角的▶️），运行和调试 DSL 函数。运行结果会在右侧展示，您可以根据运行结果，调整 DSL 语句，直到满足您的需求。
7. 单击确定，提交数据加工任务。

配置项			说明
基本信息	任务名称	数据加工任务的名称
		启用状态	任务启动/停止
		前置数据加工	日志采集至 CLS，先进行数据加工(过滤、结构化)，再写入日志主题。前置数据加工的价值：在前置加工中做日志过滤，可有效降低日志写流量、索引流量、索引存储量、日志存储量；在前置加工中做日志结构化，开启键值索引后，可使用 SQL 对日志进行分析、配置仪表盘和告警。您也可以在采集配置页面底部，点击数据加工，进入前置数据加工编辑页面：说明：每个日志主题仅能配置一个前置加工任务。前置数据加工无需配置源日志主题/目标日志主题。前置加工暂不支持分发日志到多个固定日志主题，或动态日志主题。若您新增/修改了采集配置，请酌情调整前置加工任务的语句，确保加工语句的有效性。
		数据加工服务日志	数据加工任务运行日志，保存在 cls_service_log 服务日志主题（免费），数据加工任务监控图表中的告警功能依赖该日志主题。默认开启。
源日志主题	日志主题	非前置数据加工任务的输入，您可选择日志主题作为数据加工任务的输入。
目标日志主题	固定日志主题	非前置数据加工任务的输出，您可选择单个或者多个日志主题作为加工结果的输出。目标名称：如果您的输出是多个目标日志主题，例如将源日志主题中，warning 日志输出到名称为 waring 的日志主题，将 error 日志输出到名称为 error 的日志主题，那么需要配置目标名称，建议使用英文，您将在加工函数 log_output() 中使用到该名称。
目标日志主题		动态日志主题	非前置数据加工任务的输出，适用于目标日志主题暂不能确定的场景。例如：您需要根据日志字段"pd"的值，动态创建多个目标日志主题，并将对应的日志分发至目标日志主题。示例：假设 pd 的值为"CLB "、"Ckafka"、"COS"、"CDN"，将会动态创建出名为"CLB"、"Ckafka"、"COS"、"CDN"的目标日志主题，并将相关日志写入对应的日志主题中。动态分发使用 log_auto_output 函数。超限处理。当您的数据加工任务生成的主题个数超出了产品规格，您可以选择：创建兜底日志集、日志主题并将日志写入兜底主题（创建任务时创建）。兜底日志集：auto_undertake_logset，单地域单账号下一个；兜底日志主题：auto_undertake_topic_$(数据加工任务名称)。例如用户创建了两个数据加工任务 etl_A 和 etl_B，那么会产生两个兜底主题：auto_undertake_topic_etl_A、auto_undertake_topic_etl_B。丢弃日志数据：不创建兜底主题，直接丢弃日志。

函数大类	可视化函数名称	使用场景
提取键值	JSON：从 JSON 节点中提取字段和字段值分隔符：根据分隔符提取字段值，需要用户填字段名正则：根据正则公式提取字段值，需要用户填写字段名	日志结构化
日志处理	删除日志，您可配置删除日志的条件（多个条件为 OR 的关系）。例如字段 A 存在，或者字段 B 不存在，则删除该条日志。	删除/保留日志
字段处理	删除字段重命名字段	删除/重命名字段

可视化函数	配置项目	例子中配置的值	是否必填	说明
提取键值-JSON	描述	-	否	填写您对该加工函数的描述
		字段	log	是	选中您要处理的原字段
		新字段前缀	-	否	为提取出来的新字段名称添加前缀
		新字段后缀	-	否	为提取出来的新字段名称添加后缀
		原字段自动删除	☑️	否	加工完成后，删除原字段
提取键值-正则	描述	-	否	填写您对该加工函数的描述
		字段	message	是	选中您要处理的原字段
		正则表达式	(\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}.\\d{3}) ([A-Z]{5}\|[A-Z]{4}) \\[(.+)\\]	是	\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}.\\d{3} 提取为新字段 dates； ([A-Z]{5}\|[A-Z]{4})提取为新字段 level； [(.+)\\]提取为新字段 traceid。
		新字段	dates、level、traceid	是	使用正则公式提取的新字段
		原字段自动删除	☑️	否	加工完成后，删除原字段
提取键值-分割符	描述	-	否	填写您对该加工函数的描述
		字段	content	是	选中您要处理的原字段
		分割符	：	是	分割日志为多个新字段的值
		新字段	module、delay_time、msg	是	使用分割符提取的新字段
		原字段自动删除	☑️	否	加工完成后，删除原字段

参数名称	参数描述	参数类型	是否必须	参数默认值	参数说明
topic_name	日志主题名称	string	y	-	参数 topic_name 中包含"\|"，"\|"将在生成的主题名称中被去除；参数 topic_name 长度超出250字符，生成的日志主题名称仅有前250个字符，超出的会被截断。
logset_name	日志集名称	string	y	-	-
index_options	all_index：开启键值、全文索引 no_index：不开启索引 content_index：开启全文 key_index：开启键值索引	string	n	all_index	如果storage_type=cold，即低频存储，则all_index和key_index不会生效，即低频存储不支持键值索引
period	存储周期，一般取值范围是1 - 3600 天， 3640 代表永久存储	number	n	30	1 - 3600 天
storage_type	日志主题的存储类型，可选值 hot：标准存储 cold：低频存储	string	n	hot	当为 cold 时，period 最小为 7 天
hot_period	0：关闭日志沉降非0：开启日志沉降后标准存储的天数 HotPeriod 需要大于等于7，且小于 Period，仅在 StorageType 为 hot 时生效	number	n	0	-
tag_dynamic	为日志主题添加动态标签，和 extract_tag() 函数配合使用，用于从日志字段中提取标签的 KV，例如：tag_dynamic=extract_tag(v("pd"),v("env"),v("team"), v("person"))	string	n	-	和 tag_static 一起不超过10对标签
tag_static	为日志主题添加静态标签，例如：tag_static="Ckafka:test_env,developer_team:MikeWang"	string	n	-	和 tag_dynamic 一起不超过10对标签

特殊场景	处理逻辑
参数 topic_name 获取失败或者为""（空字符串），该行日志将进入名称为"null"的日志主题	例如指定 app 字段的值为 topicname，即日志主题名称，但某行日志中没有 app 字段，或者其值为" "，那么该行日志将写入名称为"null"的日志主题，"null"主题所属日志集，是本函数的日志集参数中指定的日志集。说明：如果您使用了字符串拼接来指定日志主题名称，例如 log_auto_output( str_join("-", "myprefix", v("app")), " mylogset ",period=14,storage_type="hot",hot_period=10)，那么当 app 不存在或者值为""时，日志将写入名称为"myprefix"的日志主题。
重名主题（同一日志集下）	已存在名为"Nginx"的日志主题，动态创建任务根据规则，也要创建名为"Nginx"的日志主题时，会加上 "CreateByCLSETL" 后缀，创建出的日志主题名为" Nginx-CreateByETL"。

特殊场景	处理逻辑
动态标签的 KV 值获取失败	例如指定 A 字段的值为标签的 Key，B 字段的值为标签的 Value，但某行日志没有 A 字段或者 B 字段，或者 A 字段 B 字段的值为空，标签添加失败。
标签的 KV 值前后有空格	标签添加失败。
动态标签和静态标签的总数超过10对	动态标签优先级较高，如添加完动态标签后，还不足10对，补充静态标签，但总个数不超过10对。
标签 KV 的长度超出限制	标签的 key 长度大于127，value 的长度大于255，标签添加失败。

创建加工任务

本页目录：

前提条件

操作步骤

加工案例：JSON 可视化函数提取键值

原始日志:

可视化加工函数：

加工结果：

可视化函数的配置：

log_auto_output( )函数参数

特殊情况处理

创建日志主题

创建日志集

日志主题添加标签