# 字段操作函数 本文介绍字段操作函数的语法规则，包括参数解释、函数示例等。 #### 函数列表 | **函数** | **说明** | |---|---| | [v] | 获得日志特定字段的值。当同时传入多个字段名时，返回日志中第一个存在的字段的值。支持和其他函数组合使用。 | | [e_set] | 添加新字段或为现有字段设置新的字段值。支持和其他函数组合使用。 | | [e_drop_fields] | 删除符合条件的日志字段。支持和其他函数组合使用。 | | [e_keep_fields] | 保留符合条件的日志字段。 | | [e_pack_fields] | 打包日志字段，并输出到新的字段中。 | | [e_rename] | 重命名符合条件的日志字段名称。支持和其他函数组合使用。 | #### v 调用v函数获得日志特定字段的值。当同时传入多个字段名时，返回日志中第一个存在的字段的值。 - **函数格式** ``` v(key, ..., default=None) ``` - **参数说明** | **参数** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | key | String | 是 | 指定字段名。 | | default | 任意 | 否 | 指定的字段名不存在时，返回default的值。默认值为None。 | - **返回结果** 返回日志中第一个存在的字段值。不存在时返回default参数的值。 - **函数示例** 将content字段的值赋给test_content字段。 - 测试数据 ``` { "content": "hello" } ``` - 加工规则 ``` e_set("test_content", v("content")) ``` - 加工结果 ``` content: hello test_content: hello ``` - **更多参考** 支持和其他函数组合使用。 #### e_set 调用e_set函数添加新字段或为现有字段设置新的字段值。 - **函数格式** ``` e_set(key1, value1, key2, value2, mode="overwrite") ``` - 函数中key1和value1必须成对出现。 - 通过e_set函数设置时间字段F_TIME或__time__时，必须设置为数字、字符串。 ``` e_set(F_TIME, "abc") # 错误 e_set(F_TIME, "12345678") # 正确 ``` - **参数说明** | **参数** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | key | String | 是 | 目标字段名，也可以通过字符串表达式获得该字段名。 | | value | 任意 | 是 | 新的字段值。非字符串都转化成字符串放入日志中，其中元组、列表、字典会转换成JSON对象的字符串。 **说明** 如果传递的值是None，则不会进行更新操作。 | | mode | String | 否 | 字段的覆盖模式。默认为overwrite。 | - **返回结果** 返回更新后的日志。 - **函数示例** 1. 示例1：为字段设置固定值。 添加一个新字段city，字段值为上海。 - 原始数据 ``` {} ``` - 加工规则 ``` e_set("city", "上海") ``` - 加工结果 ``` city: 上海 ``` 2. 示例2：复制字段值。 调用单个表达式函数，将现有字段ret的值，赋给新字段result。 - 原始数据 ``` {"ret": "value"} ``` - 加工规则 ``` e_set("result", v("ret")) ``` - 加工结果 ``` ret：value result：value ``` 3. 示例3：动态设置值。 调用组合表达式函数，获取第一个存在的字段值，返回其小写格式并赋值给字段result。 - 原始数据 ``` { "return": "AAA" } ``` - 加工规则 ``` e_set("result", str_lower(v("ret", "return"))) ``` - 加工结果 ``` return: AAA result: aaa ``` 4. 示例4：多次设置字段值。 - 原始数据 ``` { "ret" : "fail" } ``` - 加工规则 ``` e_set("event_type", "login event", "event_info", "login host") ``` - 加工结果 ``` ret: fail event_type: login event event_info: login host ``` - **更多参考** 支持和其他函数组合使用。 #### e_drop_fields 调用e_drop_fields函数删除符合条件的日志字段。 - **函数格式** ``` e_drop_fields(key1, key2, ....,regex=false) ``` - **参数说明** | **参数** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | key | String | 是 | 日志字段名，可以为正则表达式。当字段名完全满足条件时删除该字段，保留不满足条件的字段。关于正则表达式的更多信息，请参见正则表达式。至少需要配置一个日志字段。 | | regex | Boolean | 否 | 如果设置为false，表示不使用正则表达式进行匹配。当不配置该参数时，系统默认取值为true。 | - **返回结果** 返回删除后的日志。 - **函数示例** 如果content字段的值为123，则删除content字段和age字段。 - 测试数据 ``` { "age": 18, "content": 123, "name": "twiss" } ``` - 加工规则 ``` e_if(e_search("content==123"), e_drop_fields("content", "age",regex=true)) ``` - 加工结果 ``` name: twiss ``` - **更多参考** 支持其他它函数组合使用。 #### e_keep_fields 调用e_keep_fields函数保留符合条件的日志字段。 云日志服务中包含内置的元字段，例如__time__、__topic__等。如果在调用e_keep_fields函数时没有保留__time__字段，则日志时间将被重置为系统当前时间。如果您不希望重置元字段的值，需要将元字段放入列表中，常见格式为F_TIME, F_META, F_TAGS, "f1", "f2"。 - **函数格式** ``` e_keep_fields(key1, key2, ....,regex=false) ``` - **参数说明** | **参数** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | key | String | 是 | 日志字段名，可以为正则表达式。当字段名完全满足条件时保留该字段，删除不满足条件的字段。至少需要配置一个字段。 | | regex | Boolean | 否 | 如果设置为false，表示不使用正则表达式进行匹配。当不配置该参数时，系统默认取值为true。 | - **返回结果** 返回保留的日志。 - **函数示例** 如果content字段的值是123，则保留content和age字段。 - 测试数据 ``` { "age": 18, "content": 123, "name": "twiss" } ``` - 加工规则 ``` e_if(e_search("content==123"), e_keep_fields("content", "age")) ``` - 加工结果 ``` age: 18 content: 123 ``` #### e_pack_fields 用e_pack_fields函数将日志字段进行打包，并输出到新的字段中。 - **函数格式** ``` e_pack_fields(output_fields,include=".*",exclude=None,drop_packed=true) ``` - **参数说明** | **参数** | **类型** | **是否必填** | **说明** | |---|---|---|---| | output_field | String | 是 | 指定打包后输出的字段名称。其值为JSON格式。 | | include | String | 否 | 白名单配置，符合正则表达式的字段会被打包。默认为".\*" ，表示全部匹配。 | | exclude | String | 否 | 黑名单配置，符合正则表达式的字段不会被打包。默认为None，表示不进行匹配判断。 | | drop_packed | Boolean | 否 | 打包数据后是否删除被打包的原数据，默认为true。 - true（默认值）：输出结果中删除被打包的原数据。 - false：输出结果中不删除被打包的原数据。 | - **返回结果** 返回被打包后的日志数据。 - **函数示例** 1. 示例1：将日志所有字段打包到test字段，默认删除被打包的原始字段。 - 测试数据 ``` { "test1":123, "test2":456, "test3":789 } ``` - 加工规则 ``` e_pack_fields("test") ``` - 加工结果 ``` test:{"test1": 123, "test2": 456, "test3": 789} ``` 2. 示例2：将日志所有字段打包到test字段，不删除被打包的原始字段。 - 测试数据 ``` { "test1":123, "test2":456, "test3":789 } ``` - 加工规则 ``` e_pack_fields("test",drop_packed=false) ``` - 加工结果 ``` test:{"test1": 123, "test2": 456, "test3": 789} test1:123 test2:456 test3:789 ``` 3. 示例3：打包test和abcd字段到content字段，不删除被打包的原始字段。 - 测试数据 ``` { "abcd@#%":123, "test":456, "abcd":789 } ``` - 加工规则 ``` e_pack_fields("content", include="\w+", drop_packed=false) ``` - 加工结果 ``` abcd:789 abcd@#%:123 content:{"test": 456, "abcd": 789} test:456 ``` 4. 示例4：不打包test和abcd字段，其余字段打包到content字段，删除被打包的原始字段。 - 测试数据 ``` { "abcd@#%":123, "test":456, "abcd":789 } ``` - 加工规则 ``` e_pack_fields("content", exclude="\w+", drop_packed=true) ``` - 加工结果 ``` abcd:789 content:{"abcd@#%": "123"} test:456 ``` #### e_rename 调用e_rename函数重命名符合条件的日志字段名称。 - **函数格式** ``` e_rename("key1", "new key1", "key2", "new key2", ..., regex=false) ``` 函数中key和new key必须成对出现。 - **参数说明** | **参数** | **参数类型** | **是否必填** | **说明** | |---|---|---|---| | key | String | 是 | 日志字段名，可以为正则表达式。当字段名完全满足条件时，重命名该字段。至少需要配置一个字段。 | | new key | String | 是 | 重命名后的字段名。 | | regex | Boolean | 否 | 如果设置为false，表示不使用正则表达式进行匹配。当不配置该参数时，系统默认取值为true。 | - **返回结果** 返回重命名后的字段。 - **函数示例** 1. 示例1：将字段host重命名为client_hos。 - 测试数据 ``` { "host": 1006 } ``` - 加工规则 ``` e_rename("host","client_host") ``` - 加工结果 ``` client_host: 1006 ``` 2. 示例2：不存在字段时，不进行重命名。 - 测试数据 ``` { "host": 1006 } ``` - 加工规则 ``` e_rename("url","rename_url") ``` - 加工结果 ``` host: 1006 ``` - **更多参考** 支持和其他函数组合使用。