数据解析类插件

数据解析效果示例

以常见的应用打印文本日志为例，直观了解使用数据解析插件前后的差异。

不使用解析插件

未经任何处理的原始日志，保存到日志服务后所有信息都混杂在一个content字段中，难以直接使用。

Content："127.0.0.1 - - [16/Aug/2024:14:37:52 +0800] "GET /wp-admin/admin-ajax.php?action=rest-nonce HTTP/1.1" 200 41 "http://www.example.com/wp-admin/post-new.php?post_type=page" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36 Edg/127.0.0.0""

使用正则解析插件

使用正则解析插件，原始日志被精确地提取为多个有意义的字段，每个字段都可以被独立查询和分析。

body_bytes_sent: 41
http_referer: http://www.example.com/wp-admin/post-new.php?post_type=page
http_user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; ×64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36 Edg/127.0.0.0
remote_addr: 127.0.0.1
remote_user: -
request_method: GET
request_protocol: HTTP/1.1
request_uri: /wp-admin/admin-ajax.php?action=rest-nonce
status: 200
time_local: 16/Aug/2024:14:37:52 +0800

如何选择数据解析插件

日志服务提供多种解析插件，适配不同格式的日志。选择合适的插件可显著提升解析效率与配置体验。请根据日志的实际格式和结构进行选择：

• 正则解析：适用于从非结构化文本中提取符合特定模式的内容。

  • 优势：通用性强，几乎可处理任意文本格式。

  • 限制：需手动编写和调试正则表达式，学习成本较高；在高吞吐场景下性能开销相对较大。

• JSON解析：解析标准JSON Object格式日志。

  • 优势：配置简单，解析速度快，无需编写规则。

  • 限制：默认仅提取JSON Object的首层键值对；不支持直接解析JSON Array，如需处理嵌套或数组结构请参考如何处理复杂JSON。

• 分隔符模式解析：适用于字段由固定分隔符（如 | , && 等）分隔的日志。常见于 CSV 或自定义格式日志。

  • 优势：配置直观，适合格式规整的结构化文本。

  • 提示：请确保分隔符在日志内容中不会意外出现，以免解析错位。

• 专用日志格式解析：针对主流日志提供开箱即用的支持，无需编写正则表达式。

  • Nginx模式解析：只需粘贴Nginx配置文件中的log_format定义，即可解析Nginx访问日志。

  • Apache模式解析：只需粘贴Apache配置文件中的LogFormat定义，即可解析Apache访问日志。

  • IIS模式解析：支持 W3C、NCSA 和 IIS 原生日志格式，按实际日志类型选择对应模板即可。

功能入口

当需要使用插件处理日志时，可在创建或修改Logtail配置时，添加插件。

数据解析插件使用

通用配置参数

以下参数在各数据解析插件中都会出现，其功能和用法是统一的，在后续插件说明中不再赘述。

正则解析

正则解析插件支持通过正则表达式提取日志字段，并将日志解析为键值对形式。灵活性极高，能适应几乎所有文本格式。

配置说明

• 参数说明

  除通用配置参数外核心参数如下：

  参数名称	说明
  正则表达式	用于匹配日志的正则表达式。 若在处理配置中配置了日志样例，在正则解析处理插件中会出现您配置的日志样例，支持通过自动或手动输入行首正则表达式的方式生成正则表达式。 单击自动生成正则表达式，然后在日志样例文本框中，划选需提取的日志内容，单击生成正则，日志服务会根据划选的内容，生成正则表达式。 单击手动输入正则表达式，输入正则表达式。配置完成后，单击验证即可验证输入的正则表达式是否可以解析、提取目标日志内容。更多信息，请参见如何调试正则表达式。 若未配置日志样例，需根据实际日志输入正则表达式。
  日志提取字段	为提取到的日志内容（Value），设置对应的字段名（Key）。

• 配置示例

  • 输入日志

    127.0.0.1 - - [16/Oct/2023:12:36:49 +0800] "GET /index.html HTTP/1.1" 200 612 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"

  • 插件配置

    参考功能入口配置，其中，正则表达式为(\S+)\s-\s(\S+)\s\[([^]]+)]\s"(\w+)\s(\S+)\s([^"]+)"\s(\d+)(\s\d+)[^-]+([^"]+)"\s"([^"]+).*。

    

  • 解析结果

JSON解析

JSON解析插件支持将Object类型的JSON日志结构化，解析为键值对形式。

使用限制

JSON日志包含Object类型（键值对的集合）和Array类型（值的有序列表）。JSON解析插件默认仅提取JSON Object的首层键值对；不支持直接解析JSON Array，若有相关需求请参考如何处理复杂JSON。

分隔符模式解析

分隔符模式解析插件支持通过分隔符将日志内容结构化，解析为多个键值对形式。

Nginx模式解析

Nginx模式插件支持根据log_format中的定义将日志内容结构化，解析为多个键值对形式。

log_format main  '$remote_addr - $remote_user [$time_local] "$request" '
                 '$request_time $request_length '
                 '$status $body_bytes_sent "$http_referer" '
                 '"$http_user_agent"';
access_log /var/logs/nginx/access.log main

配置说明

• 参数说明

  除通用配置参数外核心参数如下：

  参数名称	说明
  NGINX日志配置	Nginx配置文件中的日志配置部分，以log_format开头。例如： log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$request_time $request_length ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent"';
  日志提取字段	根据NGINX日志配置自动提取对应的日志字段（Key）。

• 配置示例

  • 输入日志

    192.168.*.* - - [15/Apr/2025:16:40:00 +0800] "GET /nginx-logo.png HTTP/1.1" 0.000 514 200 368 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.*.* Safari/537.36"

  • 插件配置

    

    参考功能入口配置，NGINX日志配置使用如下示例：生产环境中，此处的log_format必须与Nginx配置文件（通常位于  /etc/nginx/nginx.conf文件中）中的定义保持一致。

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                        '$status $body_bytes_sent "$http_referer" '
                        '"$http_user_agent" $request_time $request_length';

  • 解析结果

    body_bytes_sent: 368
    http_referer: -
    http_user_agent : Mozi11a/5.0 (Nindows NT 10.0; Win64; x64) AppleMebKit/537.36 (KHTML, like Gecko) Chrome/131.0.x.x Safari/537.36
    remote_addr:192.168.*.*
    remote_user: -
    request_length: 514
    request_method: GET
    request_time: 0.000
    request_uri: /nginx-logo.png
    status: 200
    time_local: 15/Apr/2025:16:40:00

Apache模式解析

Apache模式解析插件支持根据Apache日志配置文件中的定义将日志内容结构化，解析为多个键值对形式。

配置说明

• 参数说明

  除通用配置参数外核心参数如下：

  参数名称	说明
  日志格式	根据Apache日志配置文件中定义的日志格式进行选择，包括common、combined和自定义。
  APACHE配置字段	Apache配置文件中的日志配置部分，通常以LogFormat开头。 当配置日志格式为common或combined时，此处会自动填充对应格式的配置字段，请确认是否和Apache配置文件中定义的格式一致。 当配置日志格式为自定义时，请根据实际情况填写，例如LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %D %f %k %p %q %R %T %I %O" customized。
  日志提取字段	根据APACHE配置字段中的内容自动生成日志字段（key）。

• 配置示例

  • 输入日志

    192.168.1.10 - - [08/May/2024:15:30:28 +0800] "GET /index.html HTTP/1.1" 200 1234 "https://www.example.com/referrer" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.X.X Safari/537.36"

  • 插件配置

    参考功能入口配置，日志格式选择combined。

  • 解析结果

    http_referer:https://www.example.com/referrer
    http_user_agent:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.X.X Safari/537.36
    remote_addr:192.168.1.10
    remote_ident:-
    remote_user:-
    request_method:GET
    request_protocol:HTTP/1.1
    request_uri:/index.html
    response_size_bytes:1234
    status:200
    time_local:[08/May/2024:15:30:28 +0800]

IIS模式解析

IIS模式插件支持根据IIS日志格式定义将日志内容结构化，解析为多个键值对形式。

配置说明

• 参数说明

  除通用配置参数外核心参数如下：

  参数名称	说明
  日志格式	选择IIS服务器日志采用的日志格式，包括IIS、NCSA和W3C。
  IIS配置字段	日志格式为IIS或NCSA时，日志服务已默认设置了IIS配置字段。 日志格式为W3C日志时，设置为IIS配置文件中logExtFileFlags参数中的内容，例如： logExtFileFlags="Date, Time, ClientIP, UserName, SiteName, ComputerName, ServerIP, Method, UriStem, UriQuery, HttpStatus, Win32Status, BytesSent, BytesRecv, TimeTaken, ServerPort, UserAgent, Cookie, Referer, ProtocolVersion, Host, HttpSubStatus" IIS5配置文件默认路径：C:\WINNT\system32\inetsrv\MetaBase.bin。 IIS6配置文件默认路径：C:\WINDOWS\system32\inetsrv\MetaBase.xml。 IIS7配置文件默认路径：C:\Windows\System32\inetsrv\config\applicationHost.config。
  日志提取字段	根据IIS配置字段中的内容自动生成日志字段（Key）。

• 配置示例

  • 输入日志

    #Fields: date time s-sitename s-ip cs-method cs-uri-stem cs-uri-query s-port cs-username c-ip cs(User-Agent) sc-status sc-substatus sc-win32-status sc-bytes cs-bytes time-taken

  • 插件配置

    参考功能入口配置，日志格式选择IIS。

  • 解析结果

    c-ip: cs-username
    cs-bytes: sc-substatus
    cs-method: cs-method
    cs-uri-query: cs-uri-query
    cs-uri-stem: cs-uri-stem
    cs-username: s-port
    date: #Fields:
    s-computername: s-sitename
    s-ip: s-ip
    s-sitename: time
    sc-bytes: sc-status
    sc-status: c-ip
    sc-win32-status: cs (User-Agent)
    time: date
    time-taken: sc-win32-status

常见问题

正则表达式在测试工具中正确，为何在日志服务中解析失败？

请检查以下常见问题：

1. 日志样例不匹配：确保在Logtail配置中使用的日志样例与实际采集到的日志格式完全一致，包括空格和特殊字符。

2. 多格式日志混杂：如果日志源包含多种格式，单一的正则表达式可能无法全部匹配。建议开启解析失败时保留原始字段，这样即使部分日志解析失败，原始数据也不会丢失，便于后续排查或使用多个Logtail配置分别处理不同格式的日志。

3. 控制台与代码转义问题：从代码中复制的正则表达式可能包含额外的转义符（如 \\S+），在日志服务控制台配置时应使用单反斜杠（\S+）。

配置数据解析后，如何查询来自特定文件的日志？

采集时日志服务会自动为每条日志添加一个名为 __tag__:__path__ 的元数据字段，值为日志的完整源文件路径。可在查询分析语句中使用此字段进行过滤。例如，查询所有来自 /var/log/app/error.log 的日志：* AND __tag__:__path__: /var/log/app/error.log。

修改索引配置后（例如为JSON字段开启统计），为何无法查询到历史数据？

日志服务的索引修改仅对新写入的数据生效。对于已存在的历史数据，需执行重建索引任务，才能使用新的索引配置进行查询。

JSON日志格式较复杂（如包含JSONArray）时如何处理？

当日志字段是一个JSON数组，且需要将数组中的每个元素拆分成独立的日志条目时，标准JSON解析插件无法直接处理。

解决方案：

日志服务提供了展开JSON字段插件，专门用于处理此类场景。核心功能是“展开”或“拆分”指定的JSON数组字段。

{"s_key":{"k1":{"k2":{"k3":{"k4":{"k51":"51","k52":"52"},"k41":"41"}}}}}

0_s_key_k1_k2_k3_k41:41
0_s_key_k1_k2_k3_k4_k51:51
0_s_key_k1_k2_k3_k4_k52:52

1_s_key:{"k1":{"k2":{"k3":{"k4":{"k51":"51","k52":"52"},"k41":"41"}}}}

日志格式复杂，既有普通文本，又内嵌了JSON字符串，该如何解析？

可以通过组合使用多个插件来解决。日志服务支持使用多个处理插件，将前一个插件的输出作为后一个插件的输入进行关联处理。

场景示例：

假设应用日志格式如下，包含时间、日志级别等文本信息，以及一个作为消息体的JSON字符串。

2025-11-12 10:30:15 INFO Request details: {"trace_id": "xyz-123", "user_id": 500, "action": "login"}

解析策略：在Logtail配置中按顺序添加如下两个插件，并为第二个插件正确指定原始字段，就可以处理这种混合格式的日志。这种链式处理的方式同样适用于其他插件组合。

1. 使用正则解析插件，提取出前面的文本字段，并将内嵌的JSON字符串完整地提取到一个独立的字段中。结果如下：

   {
        "log_time": "2025-11-12 10:30:15",
        "log_level": "INFO",
        "json_message": {"trace_id": "xyz-123", "user_id": 500, "action": "login"}
   }

2. 添加JSON解析插件，将 `json_message` 字段作为原始字段，解析JSON字段内容为其内部的键值对。结果如下：

   {
        "log_time": "2025-11-12 10:30:15",
        "log_level": "INFO",
        "trace_id": "xyz-123",
        "user_id": 500,
        "action": "login"
   }

相关文档

• 通过API接口配置Logtail流水线：

  • GetLogtailPipelineConfig - 获取Logtail流水线配置

  • ListLogtailPipelineConfig - 罗列Logtail流水线配置

  • CreateLogtailPipelineConfig - 创建Logtail流水线配置

  • DeleteLogtailPipelineConfig - 删除Logtail流水线配置

  • UpdateLogtailPipelineConfig - 更新Logtail流水线配置

• 通过控制台配置处理插件：

  • 主机文本日志采集

  • 通过控制台采集集群容器日志（标准输出/文件）

• 通过Kubernetes CRD采集集群容器日志（标准输出/文件）