字段拆分
对不同结构数据的拆分成 Json 格式,发觉数据中有价值的信息。
关键术语
| 关键术语 | 描述 |
|---|---|
| Json拆分 | 一种基于Json数据封装的函数语法,可以在Json结构中拆分出需要的字段信息。 |
| Grok拆分 | 一种基于正则表达式封装的函数语法,常用于日志数据关键信息提取时使用。 |
| 结构数据 | 数据本身已经是非常规则的KV结构。 |
| 半结构数据 | 非结构数据,但数据本身也有一定的特性,按照一定规则可以分割出原子信息。 |
| 无序数据 | 非结构数据,数据完全无序,也没有特性规则。 |
前置条件
- 分析业务中的数据,包含哪些信息,需要处理到什么样的结果。
- ONE平台上接收的数据源中的原始数据,均封装在 _Message 字段中,同时添加一个 _Timestamp 字段来表示数据的接收时间。
开始使用
选择被拆分字段
组件支持配置多个字段的拆分,每次只能拆分一个字段。

设置拆分方式
支持 Json 格式数据拆分、自定义文本拆分、grok解析器拆分。
-
Json格式拆分:被拆分字段是Json数据类型,将Json按选择的Key进行拆分。

-
自定义文本拆分:可根据设定的文本分隔符进行数据切割,切割出来的每个部分都拆分为单独字段。

-
grok解析器:使用grok语法对文本数据进行拆分,适用于日志的文本字段的数据拆分。

验证
点击执行预览,在数据预览面板中查看,执行预览状态下是对数据处理的模拟,平台中不会产生真实数据。
Grok语法支持列表
0. 速查大纲
0.1 Grok 片段结构
| 结构 | 作用 | 示例 |
|---|---|---|
%{matcher} | 只参与匹配,不输出字段 | %{word} |
%{matcher:字段名} | 匹配并输出字段 | %{ipv4:clientIp} |
%{matcher:字段名:filter} | 匹配、输出字段,并执行 filter 转换 | %{notSpace:status:integer} |
%{matcher::filter} | 不指定字段名,直接对匹配值执行 filter | %{data::json} |
%{helperRule} | 引用 helper rule 复用规则片段 | %{HTTP_REQ} |
0.2 支持的内置 matcher
| 类型 | matcher | 说明 |
|---|---|---|
| 网络地址 | ipv4、ipv6、ip、port、mac、hostname | IP、端口、MAC、主机名 |
| 通用文本 | word、notSpace、data | 单词、非空白文本、任意文本 |
| 标识符 | uuid、_traceid | UUID、32 位 traceId |
| 日志内容 | _status、_class、_exception、_url | 日志级别、Java 类名、异常首行、URL |
0.3 支持的函数式 matcher
| 函数 | 作用 | 写法示例 |
|---|---|---|
date("format") | 按指定日期格式匹配,并转换为毫秒时间戳 | %{date("yyyy-MM-dd HH:mm:ss"):timestamp} |
regex("pattern") | 使用 Java 正则匹配自定义内容 | %{regex("ORD\\d{12}"):orderNo} |
boolean("trueValue","falseValue") | 匹配单词并转成布尔值 | %{boolean("Y","N"):enabled} |
number | 匹配整数或小数,并转成数字 | %{number:cost} |
0.4 支持的 filter 函数
| 类型 | filter | 写法示例 | 输出说明 |
|---|---|---|---|
| 类型转换 | boolean | %{notSpace:success:boolean} | 转 Boolean |
| 类型转换 | integer | %{notSpace:status:integer} | 转 Integer |
| 类型转换 | long | %{notSpace:bytes:long} | 转 Long |
| 类型转换 | number | %{notSpace:cost:number} | 转 Integer 或 Double |
| JSON 解析 | json | %{data::json}、%{data:payload:json} | JSON 拉平为 Map |
| KV 解析 | keyvalue | %{data:attrs:keyvalue("=", " ")} | key-value 文本转 Map |
| 字符串处理 | lowercase | %{notSpace:level:lowercase} | 转小写 |
| 字符串处理 | uppercase | %{notSpace:method:uppercase} | 转大写 |
| 空值处理 | nullIf("value") | %{notSpace:user:nullIf("-")} | 命中指定值时返回 null |
| URL 解析 | url | %{_url:req:url} | URL 拆成 scheme、host、port、path、queryString |
0.5 正则写法速查
| 场景 | 推荐写法 | 示例 |
|---|---|---|
| 已有内置 matcher | 优先使用内置 matcher | %{ip:clientIp}、%{_url:url} |
| 自定义局部正则 | 使用 regex("...") | %{regex("[A-Z]{3}\\d{4}"):bizCode} |
| 日期正则 | 优先使用 date("...") | %{date("yyyy-MM-dd HH:mm:ss"):timestamp} |
| 任意尾部文本 | 使用 data 放在末尾 | %{data:message} |
| 固定文本或分隔符 | 直接写在规则里 | level=%{_status:level}、[%{date("yyyy-MM-dd HH:mm:ss"):timestamp}] |
说明:如果规则写在 Java 字符串中,反斜杠和双引号需要按 Java 字符串规则额外转义。
1. 规则格式
一条解析规则占一行,格式如下:
规则名称 Grok表达式
示例:
nginxRule %{ipv4:clientIp} - %{notSpace:user} [%{date("dd/MMM/yyyy:HH:mm:ss Z"):timestamp}] "%{word:method} %{notSpace:path} HTTP/%{notSpace:httpVersion}" %{notSpace:status:integer} %{notSpace:bytes:long}
规则名称支持字母、数字、下划线和点号,例如:
app.access %{date("yyyy-MM-dd HH:mm:ss"):timestamp} %{_status:level} %{data:message}
限制:
- match rule 最多 10 条。
- helper rule 最多 100 条。
- helper rule 可以被 match rule 引用。
- Grok 递归展开最多 100 层,避免循环引用。
- 解析时会按规则顺序尝试,第一条匹配成功的规则会作为结果返回。
2. Grok 表达式基础语法
Grok 片段使用 %{...} 包裹,支持以下写法:
%{matcher}
%{matcher:字段名}
%{matcher:字段名:filter}
%{matcher::filter}
含义:
matcher:匹配原文的模式,可以是内置 matcher、函数式 matcher 或 helper rule。字段名:输出字段名。不写字段名时,该片段只参与匹配,不输出字段。filter:匹配成功后的转换函数,例如转数字、转 JSON、转大小写。
示例:
%{ipv4:clientIp}
%{notSpace:status:integer}
%{data:payload:json}
%{data::json}
注意:
%{data:json}表示字段名是json,不是 JSON 转换。- JSON 转换应写成
%{data::json}或%{data:payload:json}。 - 整条日志需要完整匹配,规则编译后等价于
^规则正则$。
3. 内置 matcher
通用 matcher
| matcher | 含义 |
|---|---|
uuid | 标准 UUID,例如 550e8400-e29b-41d4-a716-446655440000 |
mac | MAC 地址,支持 00:11:22:33:44:55、00-11-22-33-44-55、0011.2233.4455 |
ipv4 | IPv4 地址 |
ipv6 | IPv6 地址 |
ip | IPv4 或 IPv6 地址 |
port | 端口号,范围 1 到 65535 |
word | 单词字符,等价于 \b\w+\b |
notSpace | 非空白字符,等价于 \S+ |
data | 任意字符,支持换行,默认懒匹配 |
hostname | 主机名或域名 |
示例:
%{ipv4:hostIp}:%{port:port}
%{hostname:host}
%{word:method}
%{notSpace:path}
%{data:message}
日志专用 matcher
| matcher | 含义 |
|---|---|
_url | HTTP/HTTPS URL |
_class | Java 类名,例如 com.demo.UserService |
_status | 日志级别,支持 INFO/WARN/ERROR/DEBUG/FATAL/EMERGENCY/ALERT/CRITICAL/SEVERE 及大小写变体 |
_exception | Java 异常首行 |
_traceid | 32 位十六进制 traceId |
示例:
%{_status:level}
%{_class:className}
%{_url:url}
%{_traceid:traceId}
4. 函数式 matcher
函数式 matcher 写在 %{matcher:字段名} 的 matcher 位置,用于匹配并转换原始值。
date
语法:
%{date("日期格式"):字段名}
示例:
%{date("yyyy-MM-dd HH:mm:ss"):timestamp}
%{date("yyyy-MM-dd HH:mm:ss.SSS"):timestamp}
%{date("dd/MMM/yyyy:HH:mm:ss Z"):timestamp}
匹配成功后,字段值会转换为毫秒时间戳,字段 pattern 为对应日期格式。
当前支持的日期格式:
yyyy-MM-dd'T'HH:mm:ss.SSSZZ
yyyy-MM-dd'T'HH:mm:ss.SSSZ
yyyy-MM-dd HH:mm:ss.SSS z
EEE MMM dd HH:mm:ss yyyy
EEE MMM d HH:mm:ss yyyy
dd/MMM/yyyy:HH:mm:ss Z
dd/MMM/yyyy:HH:mm:ss.SSS
yyyy-MM-dd HH:mm:ss.SSS
yyyy-MM-dd'T'HH:mm:ss.SSSSSSZ
yyyy-MMM-dd HH:mm:ss.SSSSSS
dd MMM yyyy HH:mm:ss.SSS
yyyy-MM-dd HH:mm:ss,SSS
yyyy-MM-dd'T'HH:mm:ss,SSS
dd MMM HH:mm:ss.SSS
MM-dd HH:mm:ss.SSS
yyyy-MM-dd HH:mm:ss
yyyy-MM-dd H:mm:ss
yyyy/MM/dd HH:mm:ss
yyMMdd HH:mm:ss
hh:mm:ss a
HH:mm:ss
dd/MM/yyyy
HH:mm:ss.SSS
说明:
- 不带年份的日期格式会使用当前年份补齐。
- 仅包含时间的格式会使用当前日期补齐。
- 部分英文月份、星期格式使用英文 Locale。
regex
语法:
%{regex("Java正则表达式"):字段名}
示例:
%{regex("[A-Z]{3}\\d{4}"):bizCode}
%{regex("\\d+\\.\\d+"):cost}
说明:
regex("...")中写 Java 正则。- 在 Java 字符串中使用时,需要按 Java 字符串规则转义反斜杠。
- 复杂正则中如果包含
:、{、}等 Grok 语法字符,可能影响%{...}片段解析,建议优先使用 helper rule 或简化正则。
boolean
语法:
%{boolean("trueValue","falseValue"):字段名}
示例:
%{boolean("yes","no"):success}
%{boolean("Y","N"):enabled}
说明:
- matcher 会匹配一个单词值。
- 原文等于第一个参数时返回
true,否则返回false。
number
语法:
%{number:字段名}
示例:
%{number:cost}
说明:
- 匹配整数或小数。
- 带小数点时返回
Double,否则返回Integer。
5. filter 函数
filter 写在 Grok 片段第三段,用于对 matcher 的结果做转换。
%{matcher:字段名:filter}
类型转换 filter
| filter | 输出 |
|---|---|
boolean | Boolean |
integer | Integer |
long | Long |
number | Integer 或 Double |
示例:
%{notSpace:success:boolean}
%{notSpace:status:integer}
%{notSpace:bytes:long}
%{notSpace:cost:number}
字符串 filter
| filter | 说明 |
|---|---|
lowercase | 转小写 |
uppercase | 转大写 |
nullIf("value") | 当字段值等于指定值时返回 null |
示例:
%{notSpace:level:lowercase}
%{notSpace:method:uppercase}
%{notSpace:user:nullIf("-")}
json
语法:
%{data::json}
%{data:payload:json}
说明:
- 将 JSON 字符串拉平成 Map。
- 不写字段名时,JSON 字段直接输出。
- 写字段名时,输出字段会带前缀,例如
payload.traceId。 - 最大展开深度为 6。
示例:
jsonRule %{data:payload:json}
原文:
{"traceId":"abc","server":{"host":"node-1","port":8080}}
输出字段示例:
payload.traceId = abc
payload.server.host = node-1
payload.server.port = 8080
keyvalue
语法:
%{data::keyvalue}
%{data:attrs:keyvalue}
%{data:attrs:keyvalue("=")}
%{data:attrs:keyvalue("=", " ")}
说明:
keyvalue:默认按=拆一个 key-value。keyvalue("="):按指定分隔符拆一个 key-value,使用最后一次出现的分隔符。keyvalue("=", " "):先按第二个分隔符拆成多个片段,再按第一个分隔符拆 key-value。- 支持单引号和双引号包裹的值,拆分时会尽量避免破坏引号内内容。
- 写了字段名前缀时,输出 key 会变成
字段名.key。
示例:
kvRule %{data:attrs:keyvalue("=", " ")}
原文:
user=tom status=ok cost=12
输出字段示例:
attrs.user = tom
attrs.status = ok
attrs.cost = 12
url
语法:
%{_url:req:url}
说明:
- 解析 URL,输出 Map。
- 输出字段包括
url、scheme、host、port、path、queryString。 - 写了字段名前缀时,字段会变成
req.url、req.scheme、req.host等。
示例:
%{_url:req:url}
6. helper rule
helper rule 用于复用 Grok 表达式。match rule 可以引用 helper rule。
helper rule:
HTTP_REQUEST %{word:method} %{notSpace:path} HTTP/%{notSpace:httpVersion}
match rule:
accessRule %{ipv4:clientIp} - %{notSpace:user} [%{date("dd/MMM/yyyy:HH:mm:ss Z"):timestamp}] "%{HTTP_REQUEST}" %{notSpace:status:integer} %{notSpace:bytes:long}
说明:
- helper rule 名称写在
%{helperName}中引用。 - helper 内部的字段会输出。
- helper 引用处自身不建议再写字段名或 filter。
7. 正则写法建议
在 Grok 中直接写正则
需要直接写正则时,使用 regex("..."):
%{regex("\\d{4}-\\d{2}-\\d{2}"):dateText}
%{regex("[A-Za-z0-9_-]+"):token}
转义规则
如果规则写在普通配置文本中:
%{regex("\d+"):num}
如果规则写在 Java 字符串中,需要额外转义反斜杠:
"%{regex(\"\\d+\"):num}"
推荐写法
- 优先使用内置 matcher,例如 IP 用
%{ip:ip},URL 用%{_url:url}。 - 日期优先使用
date("..."),不要手写复杂日期正则。 - 任意剩余文本放在规则末尾时,可以使用
%{data:message}。 - 不需要输出的固定结构可以不写字段名,例如
%{word}只参与匹配。 - 避免在
regex("...")内写过于复杂的嵌套正则,防止超时或 Grok 片段解析失败。
8. 常见示例
普通应用日志
日志:
2026-06-25 10:20:30 INFO traceId=abcdef1234567890 user=tom login success
规则:
appRule %{date("yyyy-MM-dd HH:mm:ss"):timestamp} %{_status:level} traceId=%{notSpace:traceId} user=%{notSpace:user} %{data:message}
Nginx access 日志
日志:
10.0.0.1 - tom [25/Jun/2026:10:20:30 +0800] "GET /api/users HTTP/1.1" 200 1234
规则:
nginxRule %{ipv4:clientIp} - %{notSpace:user} [%{date("dd/MMM/yyyy:HH:mm:ss Z"):timestamp}] "%{word:method} %{notSpace:path} HTTP/%{notSpace:httpVersion}" %{notSpace:status:integer} %{notSpace:bytes:long}
JSON 日志
日志:
{"traceId":"abc","success":true,"server":{"host":"node-1","port":8080}}
规则:
jsonRule %{data::json}
key-value 日志
日志:
host=node-1 ip=10.0.0.1 port=8080 status=UP
规则:
kvRule %{data:attrs:keyvalue("=", " ")}
9. 当前不支持或不建议使用的语法
以下名称虽然在枚举或类名中能看到,但当前没有完整接入 Grok 编译路径,不建议作为用户语法使用:
numberStr
numberExt
numberExtStr
integer
integerStr
integerExt
integerExtStr
doubleQuotedString
singleQuotedString
quotedString
ipOrHost
如果需要整数、小数、字符串等能力,建议使用:
%{notSpace:field:integer}
%{notSpace:field:long}
%{notSpace:field:number}
%{data:field}
%{regex("..."):field}
10. 更多可直接套用的示例
10.1 固定分隔符日志
日志:
2026-06-25 10:20:30|INFO|order-service|create order success|cost=35
规则:
pipeRule %{date("yyyy-MM-dd HH:mm:ss"):timestamp}|%{_status:level}|%{notSpace:service}|%{data:message}|cost=%{notSpace:cost:long}
10.2 空格分隔日志
日志:
2026-06-25 10:20:30 INFO payment-service 10.0.1.12 /pay/create 200 18.6
规则:
spaceRule %{date("yyyy-MM-dd HH:mm:ss"):timestamp} %{_status:level} %{notSpace:service} %{ipv4:clientIp} %{notSpace:path} %{notSpace:status:integer} %{notSpace:cost:number}
10.3 key-value 日志
日志:
time=2026-06-25T10:20:30.123+0800 level=INFO host=node-1 ip=10.0.1.12 port=8080 success=true
规则:
kvLineRule %{data:attrs:keyvalue("=", " ")}
输出字段示例:
attrs.time = 2026-06-25T10:20:30.123+0800
attrs.level = INFO
attrs.host = node-1
attrs.ip = 10.0.1.12
attrs.port = 8080
attrs.success = true
10.4 JSON 日志整体展开
日志:
{"traceId":"abc-123","level":"INFO","server":{"host":"node-1","ip":"10.0.1.12"},"cost":18}
规则:
jsonFlatRule %{data::json}
输出字段示例:
traceId = abc-123
level = INFO
server.host = node-1
server.ip = 10.0.1.12
cost = 18
10.5 URL 解析
日志:
GET https://example.com:8443/api/search?q=grok&page=1 200
规则:
urlRule %{word:method} %{_url:req:url} %{notSpace:status:integer}
输出字段示例:
method = GET
req.url = https://example.com:8443/api/search?q=grok&page=1
req.scheme = https
req.host = example.com
req.port = 8443
req.path = /api/search
req.queryString.q = grok
req.queryString.page = 1
status = 200
10.6 自定义正则提取业务编号
日志:
orderNo=ORD202606250001 status=SUCCESS cost=99.5
规则:
regexRule orderNo=%{regex("ORD\\d{12}"):orderNo} status=%{word:status} cost=%{notSpace:cost:number}
说明:
- 在普通配置文本中,按配置系统对反斜杠的处理决定写
\d还是\\d。 - 如果规则写在 Java 字符串中,需要额外转义。
10.7 boolean matcher
日志:
user=tom enabled=Y deleted=N
规则:
boolMatcherRule user=%{notSpace:user} enabled=%{boolean("Y","N"):enabled} deleted=%{boolean("Y","N"):deleted}
输出字段示例:
user = tom
enabled = true
deleted = false
10.8 nullIf 处理占位符
日志:
clientIp=10.0.1.12 user=- path=/api/order
规则:
nullIfRule clientIp=%{ipv4:clientIp} user=%{notSpace:user:nullIf("-")} path=%{notSpace:path}
10.9 Java 应用日志
日志:
2026-06-25 10:20:30 ERROR com.demo.order.OrderService create order failed
规则:
javaLogRule %{date("yyyy-MM-dd HH:mm:ss"):timestamp} %{_status:level} %{_class:className} %{data:message}
10.10 Java 异常首行
日志:
java.lang.RuntimeException: create order failed
规则:
exceptionRule %{_exception:exception}
说明:
_exception主要匹配异常首行。- 多行堆栈建议由上游先合并为一条日志,或使用
%{data:stack}兜底。
10.11 traceId 提取
日志:
traceId=4bf92f3577b34da6a3ce929d0e0e4736 spanId=00f067aa0ba902b7
规则:
traceRule traceId=%{_traceid:traceId} spanId=%{notSpace:spanId}
10.12 IP 和端口
日志:
remote=10.0.1.12:443 local=172.16.1.2:8080
规则:
ipPortRule remote=%{ipv4:remoteIp}:%{port:remotePort:integer} local=%{ipv4:localIp}:%{port:localPort:integer}
10.13 helper rule 复用 HTTP 请求
helper rule:
HTTP_REQ %{word:method} %{notSpace:path} HTTP/%{notSpace:httpVersion}
match rule:
accessWithHelper %{ipv4:clientIp} "%{HTTP_REQ}" %{notSpace:status:integer} %{notSpace:bytes:long}
日志:
10.0.1.12 "POST /api/order HTTP/1.1" 201 456
10.14 helper rule 复用日志前缀
helper rule:
LOG_PREFIX %{date("yyyy-MM-dd HH:mm:ss.SSS"):timestamp} %{_status:level} %{_traceid:traceId}
match rule:
appWithPrefix %{LOG_PREFIX} %{_class:className} - %{data:message}
日志:
2026-06-25 10:20:30.123 INFO 4bf92f3577b34da6a3ce929d0e0e4736 com.demo.OrderService - create order success
10.15 中括号日志
日志:
[2026-06-25 10:20:30] [INFO] [order-service] create order success
规则:
bracketRule [%{date("yyyy-MM-dd HH:mm:ss"):timestamp}] [%{_status:level}] [%{notSpace:service}] %{data:message}
10.16 CSV 风格日志
日志:
2026-06-25 10:20:30,INFO,order-service,10.0.1.12,200,35
规则:
csvRule %{date("yyyy-MM-dd HH:mm:ss"):timestamp},%{_status:level},%{notSpace:service},%{ipv4:clientIp},%{notSpace:status:integer},%{notSpace:cost:long}
10.17 data 放在末尾兜底
日志:
2026-06-25 10:20:30 WARN disk usage high: /data 91%
规则:
tailDataRule %{date("yyyy-MM-dd HH:mm:ss"):timestamp} %{_status:level} %{data:message}
说明:
%{data:message}放在末尾时会吃掉剩余内容。- 如果放在中间,建议后面跟稳定分隔符,避免匹配过宽。
10.18 多规则匹配
match rules:
jsonRule %{data::json}
textRule %{date("yyyy-MM-dd HH:mm:ss"):timestamp} %{_status:level} %{data:message}
说明:
- 解析器会按规则加载顺序尝试。
- 第一条匹配成功的规则会返回。
- 如果 JSON 日志和文本日志混合输入,可以把更明确的规则放前面。