ICAgent结构化解析规则说明

功能优势

• 基于日志文件，无侵入式采集日志。您无需修改应用程序代码，且采集日志不会影响您的应用程序运行。
• 稳定处理日志采集过程中的各种异常。当遇到网络异常、服务端异常等问题时会采用主动重试、本地缓存数据等措施保障数据安全。
• 基于日志服务的集中管理能力。安装ICAgent后，只需要在日志服务上配置主机组、ICAgent采集配置等信息即可。
• 完善的自我保护机制。为保证运行在服务器上的ICAgent，不会明显影响您服务器上其他服务的性能，ICAgent在CPU、内存及网络使用方面都做了严格的限制和保护机制。

单行-全文日志

采集的日志文件中，如果您希望每一行日志在LTS界面中都显示为一条单独的日志数据，则选择单行日志。

1. 选择单行-全文日志。
2. 日志过滤默认关闭，可根据需要打开日志过滤，进行添加白名单规则或黑名单规则，白名单规则或黑名单规则添加上限为20个。
   图1 日志过滤规则
   
   • 开启日志过滤才需要设置，添加白名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为命中规则，即匹配上正则表达式的日志才会被采集上报。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。单行/多行全文模式下，默认使用content作为全文的键{key}名，多条过滤规则之间关系是“或”逻辑。例如采集日志源文件中包含hello的日志，可配置采集规则为.*hello.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
        图2 校验
        
   • 开启日志过滤才需要设置，添加黑名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为丢弃规则，即匹配上正则表达式的日志会被丢弃。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。单行/多行全文模式下，默认使用content作为全文的键{key}名，多条过滤规则之间关系是“或”逻辑。例如不采集日志源文件中包含test的日志，可配置采集规则为.*test.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。

多行-全文日志

采集的日志中包含像java异常的日志，如果您希望多行异常的日志显示为一条日志，正常的日志则每一行都显示为一条单独的日志数据，则选择多行日志，方便您查看日志并且定位问题。

1. 选择多行-全文日志。
2. 从“从已有日志中选择”或“从剪切板中粘贴”选择日志样例。
   • 从已有日志中选择：单击“从已有日志中选择”，在弹出框中根据业务需求选择待操作的日志，单击“确定”。通过选择不同时间段筛选日志。
   • 从剪切板中粘贴：单击“从剪切板中粘贴”，可直接自动将您剪切的日志内容复制到示例日志框中。

   

3. 在“首行正则表达式”下方支持自动生成或手动输入正则表达式。首行正则表达式需要匹配首行完整内容，注意并非首行的开头内容。
   图3 首行正则表达式
   
4. 日志过滤默认关闭，可根据需要打开日志过滤，进行添加白名单规则或黑名单规则，白名单规则或黑名单规则添加上限为20个。
   图4 日志过滤规则
   
   • 开启日志过滤才需要设置，添加白名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为命中规则，即匹配上正则表达式的日志才会被采集上报。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。单行/多行全文模式下，默认使用content作为全文的键{key}名，多条过滤规则之间关系是“或”逻辑。例如采集日志源文件中包含hello的日志，可配置采集规则为.*hello.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
        图5 校验
        
   • 开启日志过滤才需要设置，添加黑名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为丢弃规则，即匹配上正则表达式的日志会被丢弃。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。单行/多行全文模式下，默认使用content作为全文的键{key}名，多条过滤规则之间关系是“或”逻辑。例如不采集日志源文件中包含test的日志，可配置采集规则为.*test.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。

JSON

适用JSON格式的日志，通过提取JSON字段将其拆分为键值对。

1. 选择JSON格式。
2. 日志过滤默认关闭，可根据需要打开日志过滤，进行添加白名单规则或黑名单规则，白名单规则或黑名单规则添加上限为20个。
   图6 日志过滤规则
   
   • 开启日志过滤才需要设置，添加白名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为命中规则，即匹配上正则表达式的日志才会被采集上报。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。Key值为日志字段名称，多条过滤规则之间关系是“或”逻辑。例如采集日志源文件中包含hello的日志，可配置采集规则为.*hello.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
        图7 校验
        
   • 开启日志过滤才需要设置，添加黑名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为丢弃规则，即匹配上正则表达式的日志会被丢弃。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。Key值为日志字段名称，多条过滤规则之间关系是“或”逻辑。例如不采集日志源文件中包含test的日志，可配置采集规则为.*test.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
3. 上传原始日志。

   打开上传原始日志开关后，原始日志将作为content字段的值上传到日志服务。

4. 上传解析失败日志。

   打开上传解析失败日志开关后，原始日志将作为_content_parse_fail_字段的值上传到日志服务。

5. 自定义日志时间。

   开启后可指定某一字段作为日志时间，或关闭此项使用日志被采集时间作为日志时间。

6. json解析层数。增加json解析层数配置，取值范围为1~4，只能整数，默认值为1。

   将json格式日志的字段展开，例如原始日志为{"key1":{"key2":"value"}}，解析1层日志为：{"key1":{"key2":"value"}}，解析2层日志为：{"key1.key2":"value"}。

分隔符

使用分隔符（例如：逗号、空格或字符）提取字段。

1. 选择分隔符。
2. 根据原始日志内容选择分隔符，或自定义其他需要的特殊字符作为分隔符。
3. 从“从已有日志中选择”或“从剪切板中粘贴”选择日志样例，单击“验证”，在提取结果下方查看结果。
   • 从已有日志中选择：单击“从已有日志中选择”，在弹出框中根据业务需求选择待操作的日志，单击“确定”。通过选择不同时间段筛选日志。
   • 从剪切板中粘贴：单击“从剪切板中粘贴”，可直接自动将您剪切的日志内容复制到示例日志框中。
   图8 分隔符
   
4. 日志过滤默认关闭，可根据需要打开日志过滤，进行添加白名单规则或黑名单规则，白名单规则或黑名单规则添加上限为20个。
   图9 日志过滤规则
   
   • 开启日志过滤才需要设置，添加白名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为命中规则，即匹配上正则表达式的日志才会被采集上报。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。Key值为日志字段名称，多条过滤规则之间关系是“或”逻辑。例如采集日志源文件中包含hello的日志，可配置采集规则为.*hello.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
        图10 校验
        
   • 开启日志过滤才需要设置，添加黑名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为丢弃规则，即匹配上正则表达式的日志会被丢弃。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。Key值为日志字段名称，多条过滤规则之间关系是“或”逻辑。例如不采集日志源文件中包含test的日志，可配置采集规则为.*test.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
5. 上传原始日志。

   打开上传原始日志开关后，原始日志将作为content字段的值上传到日志服务。

6. 上传解析失败日志。

   打开上传解析失败日志开关后，原始日志将作为_content_parse_fail_字段的值上传到日志服务。

7. 自定义日志时间。

   开启后可指定某一字段作为日志时间，或关闭此项使用日志被采集时间作为日志时间。

单行-完全正则

适用任意格式的单行日志，使用正则表达式提取字段。

1. 选择单行-完全正则。
2. 从“从已有日志中选择”或“从剪切板中粘贴”选择日志样例。
   • 从已有日志中选择：单击“从已有日志中选择”，在弹出框中根据业务需求选择待操作的日志，单击“确定”。通过选择不同时间段筛选日志。
   • 从剪切板中粘贴：单击“从剪切板中粘贴”，可直接自动将您剪切的日志内容复制到示例日志框中。
3. 在“提取正则表达式”下方输入要提取日志的正则表达式，单击“验证”，在提取结果下方查看结果。

   或者单击“正则表达式自动生成”，在新打开的页面根据日志样例提取字段，输入key值，单击“确定”即可自动生成正则表达式，设置完成后，单击“确定”。

   图11 提取正则表达式
   
4. 日志过滤默认关闭，可根据需要打开日志过滤，进行添加白名单规则或黑名单规则，白名单规则或黑名单规则添加上限为20个。
   图12 日志过滤规则
   
   • 开启日志过滤才需要设置，添加白名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为命中规则，即匹配上正则表达式的日志才会被采集上报。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。Key值为日志字段名称，多条过滤规则之间关系是“或”逻辑。例如采集日志源文件中包含hello的日志，可配置采集规则为.*hello.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
        图13 校验
        
   • 开启日志过滤才需要设置，添加黑名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为丢弃规则，即匹配上正则表达式的日志会被丢弃。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。Key值为日志字段名称，多条过滤规则之间关系是“或”逻辑。例如不采集日志源文件中包含test的日志，可配置采集规则为.*test.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
5. 上传原始日志。

   打开上传原始日志开关后，原始日志将作为content字段的值上传到日志服务。

6. 上传解析失败日志。

   打开上传解析失败日志开关后，原始日志将作为_content_parse_fail_字段的值上传到日志服务。

7. 自定义日志时间。

   开启后可指定某一字段作为日志时间，或关闭此项使用日志被采集时间作为日志时间。

多行-完全正则

适用任意格式的多行日志，使用正则表达式提取字段。

1. 选择多行-完全正则。
2. 从“从已有日志中选择”或“从剪切板中粘贴”选择日志样例。
   • 从已有日志中选择：单击“从已有日志中选择”，在弹出框中根据业务需求选择待操作的日志，单击“确定”。通过选择不同时间段筛选日志。
   • 从剪切板中粘贴：单击“从剪切板中粘贴”，可直接自动将您剪切的日志内容复制到示例日志框中。
3. 在“首行正则表达式”下方支持自动生成或手动输入正则表达式。首行正则表达式需要匹配首行完整内容，注意并非首行的开头内容。
   

   “首行正则表达式”用于识别多行日志的行首，例如以下日志示例：

   2024-10-11 10:59:07.000 a.log:1 level:warn
     no.1 log
   2024-10-11 10:59:17.000 a.log:2 level:warn
     no.2 log

   完整的多行是：

   2024-10-11 10:59:07.000 a.log:1 level:warn
   no.1 log

   首行则是：

   2024-10-11 10:59:07.000 a.log:1 level:warn

   首行正则示例：^(\d+-\d+-\d+\s+\d+:\d+:\d+\.\d+)，由于每个首行的日期是唯一的，因此可以根据日期来生成首行正则。

4. 在“提取正则表达式”下方输入要提取日志的正则表达式，单击“验证”，在提取结果下方查看结果。

   或者单击“正则表达式自动生成”，在新打开的页面根据日志样例提取字段，输入key值，单击“确定”即可自动生成正则表达式，设置完成后，单击“确定”。

   

   提取结果显示的是“提取正则表达式”执行的结果，而不是“首行正则表达式”执行的结果，“首行正则表达式”执行的结果需要到目标日志流查看。

   如果“首行正则表达式”手动输入的正则表达式有误，则会导致无法查看上报的日志流数据。

   图14 设置正则表达式
   
5. 日志过滤默认关闭，可根据需要打开日志过滤，进行添加白名单规则或黑名单规则，白名单规则或黑名单规则添加上限为20个。
   图15 日志过滤规则
   
   • 开启日志过滤才需要设置，添加白名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为命中规则，即匹配上正则表达式的日志才会被采集上报。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。Key值为日志字段名称，多条过滤规则之间关系是“或”逻辑。例如采集日志源文件中包含hello的日志，可配置采集规则为.*hello.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
        图16 校验
        
   • 开启日志过滤才需要设置，添加黑名单规则。

     您可以添加过滤规则筛选出有价值的日志数据，过滤规则为正则表达式，应用到指定Key的Value。所创建的过滤规则为丢弃规则，即匹配上正则表达式的日志会被丢弃。

     1. 单击“添加”，填写Key值和过滤规则（正则表达式）。Key值为日志字段名称，多条过滤规则之间关系是“或”逻辑。例如不采集日志源文件中包含test的日志，可配置采集规则为.*test.*
     2. 单击操作列的可以进行规则校验，输入字段值，单击“校验”，提示校验成功。
6. 上传原始日志。

   打开上传原始日志开关后，原始日志将作为content字段的值上传到日志服务。

7. 上传解析失败日志。

   打开上传解析失败日志开关后，原始日志将作为_content_parse_fail_字段的值上传到日志服务。

8. 自定义日志时间。

   开启后可指定某一字段作为日志时间，或关闭此项使用日志被采集时间作为日志时间。

组合解析

适用于多格式嵌套的日志（例如：分隔符+JSON），根据语法自定义配置解析规则。

1. 选择组合解析。
2. 从“从已有日志中选择”或“从剪切板中粘贴”选择日志样例，在插件配置下方输入配置内容。
3. 您可以根据日志内容参考以下插件语法自定义设置：
   • processor_regex

     表1 正则提取

     参数	类型	说明
     source_key	string	原始字段名。
     regex	string	正则表达式()中为提取字段。
     keys	string	为提取的内容指定字段名。
     keep_source	boolean	是否保留原始字段。
     keep_source_if_parse	boolean	解析错误是否保留原始字段。

   • processor_split_string

     表2 分隔符解析

     参数	类型	说明
     source_key	string	原始字段名。
     split_sep	string	分隔符字符串。
     keys	string	为提取的内容指定字段名。
     keep_source	boolean	被解析后的日志中是否保留原始字段。
     split_type	char/special_char/string	分隔类型，支持char-单字符、special_char-不可见字符、string-字符串。
     keep_source_if_parse_error	boolean	解析错误是否保留原始字段。

   • processor_split_key_value

     表3 键值对分割

     参数	类型	说明
     source_key	string	原始字段名。
     delimiter	string	键值对之间的分隔符，默认值为制表符\t。
     separator	string	单个键值对中键与值之间的分隔符，默认值为半角冒号（:）。
     keep_source	boolean	被解析后的日志中是否保留原始字段。

   • processor_add_fields

     表4 添加字段

     参数	类型	说明
     fields	json/object	待添加的字段名和字段值。键值对格式，支持添加多个。

   • processor_drop

     表5 丢弃字段

     参数	类型	说明
     drop_keys	string	丢弃的字段列表。

   • processor_rename

     表6 重命名字段

     参数	类型	说明
     source_keys	string	待重命名的原始字段。
     destkeys	string	重命名后的字段。

   • processor_json

     表7 json展开提取

     参数	类型	说明
     source_key	string	原始字段名。
     keep_source	string	被解析后的日志中是否保留原始字段。
     expand_depth	int	json展开的深度。默认值为0，表示不限制。1表示当前层级，以此类推。
     expand_connector	string	json展开时的连接符，默认值为下划线（_）。
     prefix	string	json展开时，对字段名附加的前缀。
     keep_source_if_parse_error	boolean	解析错误是否保留原始字段。

   • processor_filter_regex

     表8 过滤器

     参数	类型	说明
     include	json/object	key为日志字段，value为匹配的正则表达式。
     exclude	json/object	key为日志字段，value为匹配的正则表达式。

   • processor_gotime

     表9 提取时间

     参数	类型	说明
     source_key	string	原始字段名。
     source_format	string	原始时间的格式。
     source_location	int	原始时间的时区。参数值为空时，表示logtail所在主机或容器的时区。
     dest_key	string	解析后的目标字段。
     dest_format	string	解析后的时间格式。
     dest_location	int	解析后的时区。参数值为空时，表示本机时区。
     set_time	boolean	是否将解析后的时间设置为日志时间。
     keep_source	boolean	被解析后的日志中是否保留原始字段。

4. 参考示例：

   [
           {
               "type": "processor_regex",
               "detail": {
                   "source_key": "content",
                   "regex": "*",
                   "keys": [
                       "key1",
                       "key2"
                   ],
                   "multi_line_regex": "*",
                   "keep_source": true,
                   "keep_source_if_parse_error": true
               }
           },
           {
               "type": "processor_split_string",
               "detail": {
                   "split_sep": ".",
                   "split_type": ".",
                   "split_keys": [
                       "key1",
                       "key2"
                   ],
                   "source_key": "context",
                   "keep_source": true,
                   "keep_source_if_parse_error": true
               }
           },
           {
               "type": "processor_add_fields",
               "detail": {
                   "fields": [
                       {
                           "key1": "value1"
                       },
                       {
                           "key2": "value2"
                       }
                   ]
               }
           },
           {
               "type": "processor_drop",
               "detail": {
                   "drop_keys": [
                       "key1",
                       "key2"
                   ]
               }
           },
           {
               "type": "processor_rename",
               "detail": {
                   "source_key": [
                       "skey1",
                       "skey2"
                   ],
                   "dest_keys": [
                       "dkey1",
                       "dkey2"
                   ]
               }
           },
           {
               "type": "processor_json",
               "detail": {
                   "source_key": "context",
                   "expand_depth": 4,
                   "expand_connector": "_",
                   "prefix": "prefix",
                   "keep_source": true,
                   "keep_source_if_parse_error": true
               }
           },
           {
               "type": "processor_gotime",
               "detail": {
                   "source_key": "skey",
                   "source_format": "ydm",
                   "source_location": 8,
                   "dest_key": "dkey",
                   "dest_format": "ydm",
                   "dest_location": 8,
                   "set_time": true,
                   "keep_source": true,
                   "keep_source_if_parse_error": true
               }
           },
           {
               "type": "processor_filter_regex",
               "detail": {
                   "include": {
                       "ikey1": "*",
                       "ikey2": "*"
                   },
                   "exclude": {
                       "ekey1": "*",
                       "ekey1": "*"
                   }
               }
           }
       ]

自定义日志时间

开启自定义日志时间开关，参考表10设置参数。

• 若时间格式填写错误或指定字段不存在，将使用日志被采集时间作为日志时间。
• 对结构化解析进行字段名称修改、字段删除、字段类型修改等操作，都需要重新校验时间字段。

常见日志时间格式

常见日志时间格式如下表11。

默认情况下，云日志服务LTS中的日志时间戳精确到秒，因此时间格式只需配置到秒，无需配置毫秒、微秒等信息。