SPL概述

云日志服务提供SPL语句（Semi-structured Processing Language），对半结构化的日志数据做结构化处理，比如信息提取、字段操作、数据过滤等操作。SPL提供类Linux Shell脚本的管道级联功能，其中第一级管道前的表达式是数据源（可以是索引过滤条件或其他SPL语句的命名引用），后面的多级管道前后都是SPL命令表达式。

SPL语法说明

一个SPL语句由多个表达式组成，各表达式之间通过英文管道符 (|) 连接；一个SPL语句以英文分号 (;) 作为语句结束符。SPL语法结构如下：

语法

source-expr | cmd-expr | cmd-expr；

参数说明

数据源

指令表达式语法

语法

cmd -option=<option> -option ... <expression>, ... as <output>, ...

参数说明

数据类型

参数类型说明

SPL指令列表

fields指令

用于保留或排除指定模式相匹配的字段。

语法

• 保留字段

fields -wildcard -mode='overwrite' <pattern>, ... , <field>, ... , <output>=<field>

• 排除字段

fields -wildcard -drop <pattern>, ... , <field>, ...

参数说明

• 保留字段

• 排除字段

注：

• 保留字段时：

  • <pattern>、<field>、<output>=<field>三类参数至少有一个

  • 可在同一条指令中重命名字段；指令执行过程中，会先进行字段保留，再进行字段重命名。

• 排除字段时:

  • <pattern>、<field>此两类参数至少有一个

  • 排除字段时，不可在同一条指令中同时进行字段重命名；

• 时间字段（__ts__）不可排除、重命名与覆盖。详情请参见时间字段

示例

• 示例1：保留特定字段

* | fields level, msg

• 示例2：丢弃符合指定前缀的字段

* | fields -drop -wildcard '__tag__*'

• 示例3：重命名字段

* | fields ip=__tag__hostip, msg

rename指令

重命名指定字段，并原样保留其他字段。

语法

rename -mode='overwrite' <output>=<field>

参数说明

注：时间字段（__ts__）不可重命名与覆盖。详情请参见时间字段。

示例

• 重命名指定字段

* | rename ip=__tag__hostip, pod=__tag__podname

expand指令

展开指定字段的第一层JSON对象，生成多条结果。

语法

expand -mode='overwrite' -path=<path> -limit=<limit> -keep <field> as <output>

参数说明

注：

• 时间字段（__ts__）不可重命名与覆盖。详情请参见时间字段。

• 展开结果的数据类型为varchar

示例

• 示例1：展开数组，输出多条结果数据

  • SPL语句

  * |  expand fruits

  • 输入数据

  owner: 'Alice'
  fruits: '["apple", "pear", "banana"]'

  • 输出结果

  # 数据1
  owner: 'Alice'
  fruits: 'apple'
  
  # 数据2
  owner: 'Alice'
  fruits: 'pear'
  
  # 数据3
  owner: 'Alice'
  fruits: 'banana'

• 示例2：按JSONPath展开指定内容，输出至新字段

  • SPL语句

  * |  expand -path='$.data' -keep http_body as rsp

  • 输入数据

  http_body: '{"data": {"alice":1, "bob":0}}'

  • 输出结果

  # 数据1
  http_body: '{"data": {"alice":1, "bob":0}}'
  rsp: '{"alice":1}'
  
  # 数据2
  http_body: '{"data": {"alice":1, "bob":0}}'
  rsp: '{"bob":0}'

eval指令

通过SQL表达式计算结果产生新字段。

语法

eval <output>=<sql-expr>, ...

参数说明

示例

• 示例1：使用数值运算表达式，将计算结果赋值给新字段

* | eval result=a*b+c*d

• 示例2：使用正则表达式提取值给新字段

* | eval tid=regexp_extract(msg, '\w+-\w+')

where指令

根据SQL表达式过滤数据（只保留满足SQL表达式的数据）。

语法

where <sql-expr>

参数说明

示例

• 示例1：根据字段内容过滤数据

* | where level='ERROR'

• 示例2：提取字段内的数字并转换类型后，比较数值并过滤数据

* | where cast(regexp_extract(http_code, '\d+') as integer)>=300

parse指令

用指定解析器解析并提取指定字段中的信息。

语法

• 正则提取

parse -type=regexp -mode=<mode> -pattern=<pattern> <field> as <output>, ...

• CSV提取

parse -type=csv -mode=<mode> -delim=<delim> -quote=<quote> -strict <field> as <output>, ...

• JSON提取

parse -type=json -mode=<mode> -path=<path> -prefix=<prefix> <field>

• 键值分隔符提取

parse -type=regexp -mode=<mode> -prefix=<prefix> -greedy -delim=<delim> -kv-sep=<kv-sep> <field>

• 键值正则提取

parse -type=kv_reg -mode=<mode> -prefix=<prefix> -pattern=<pattern> <field>

参数说明

• 正则提取

• CSV提取

• JSON提取

• 分隔符键值提取

• 正则键值提取

示例

• 示例1：正则分组提取

  • SPL语句

  * | parse -type=regexp -pattern='(\S+)\s+\w+\s+(\S+)' msg as ip, uri

  • 输入数据

  msg: '192.168.0.1 POST /v1/content/fetch 32 0.128'

  • 输出结果

  msg: '192.168.0.1 POST /v1/content/fetch 32 0.128'
  ip: '192.168.0.1'
  uri: '/v1/content/fetch'

• 示例2：CSV提取

  • SPL语句

  * | parse -type=csv msg as a,b,c

  • 输入数据

  msg: 'alice,bob,carol'

  • 输出结果

  msg: 'alice,bob,carol'
  a: 'alice'
  b: 'bob'
  c: 'carol'

• 示例3：JSON提取

  • SPL语句

  * | parse -type=json -path='$.data' msg

  • 输入数据

  msg: '{"data": {"alice":1, "bob":0}}'

  • 输出结果

  msg: '{"data": {"alice":1, "bob":0}}'
  alice: 1
  bob: 0

• 示例4：分隔符键值提取

  • SPL语句

  * | parse -type=kv -delim='&' -kv-sep='=' msg

  • 输入数据

  msg: 'thread=23921715548&rule=cable_1&dancer=alice'

  • 输出结果

  msg: 'thread=23921715548&rule=cable_1&dancer=alice'
  thread: '23921715548'
  rule: 'cable_1'
  dancer: 'alice'

pack指令

打包多个日志字段，并以JSON序列化输出到新字段

语法

pack -include=<include> -exclude=<exclude> -keep -ltrim as <output>

参数说明

示例

• 示例1：打包k1和k2字段到msg字段，不删除被打包的原始字段

  • SPL语句

  * | pack -keep -include='^\w+$' as msg

  • 输入数据

  key#val:'test'
  k1: 'v1'
  k2: 123

  • 输出结果

  key#val:'test'
  k1: 'v1'
  k2: 123
  msg: '{"k1":"v1", "k2":123}'

let指令

定义数据引用，作为后续SPL表达式的数据源。

没有被引用到的命名引用定义将会被忽略

语法

• 定义数据引用

let <name>=<spl-expr>

• 解引用

$<name>;        -- 直接输出
$<name> | ...;  -- 作为其他SPL语句的数据源

参数说明

示例

将访问日志基于状态码进行过滤和分类处理，然后将其输出

• SPL语句

-- 转换字段格式后，定义数据引用，名称为src
let src=* | eval status=cast(status as integer);

-- 通过$+引用名称，解引用，并分别对不同范围的状态码增加错误详情并输出
$src | where status>=200 and status<300 | eval msg='success';
$src | where status>=400 and status<500 | eval msg='request error';
$src | where status>=500 | eval msg='server error';

• 输入数据

# 数据1
status: '200'
data: 'test ok'

# 数据2
status: '404'
data: 'page not found'

# 数据3
status: '504'
data: 'gateway timeout'

• 输出结果

# 结果1
status: 200
data: 'test ok'
msg: 'success'

# 结果2
status: 404
data: 'page not found'
msg: 'request error'

# 结果3
status: 504
data: 'gateway timeout'
msg: 'server error'

特殊字段处理

时间字段

在SPL执行过程中，云日志服务的日志时间字段（__ts__）类型始终保持为datetime。

• 若要更新数据时间，需使用eval指令操作，且确保新值类型为datetime。

• 其他指令均不可操作时间字段，其行为如下：

  • fields、rename：默认保留时间字段，不可将其重命名，也不可将其覆盖。

  • parse：如果提取结果包含时间字段，则将其忽略。

字段提取与覆盖模式

在SPL指令执行提取过程中，提取模式mode参数的取值说明如下

新旧值保留与覆盖

在SPL指令执行过程中，其输出的目标字段与输入数据中已有字段重名时，该字段的取值策略如下

新旧值类型不一致

直接保留输入字段原始值

示例

• SPL语句

* | eval tmp=regexp_extract(msg, '\w+-\w+') -- 表达式计算结果为varchar类型，赋值给tmp
  | rename tid=tmp                          -- tid旧值integer类型，tmp为varchar类型；tid保留旧值

• 输入数据

msg: '127.0.0.1 ed06b28a-9de1006f INFO unknown method, discard request'
tid: 3817568

• 输出结果

msg: '127.0.0.1 ed06b28a-9de1006f INFO unknown method, discard request'
tmp: 'ed06b28a-9de1006f'
tid: 3817568

新旧值类型一致

由指令中指定的mode参数确定。如果指令没有定义mode参数，则其默认值为overwrite

示例

• SPL语句

* | eval tmp=regexp_extract(msg, '\w+-\w+') -- 表达式计算结果为varchar类型，赋值给tmp
  | rename -mode='overwrite' code=tmp       -- code旧值varchar类型，tmp为varchar类型；tid被新值覆盖

• 输入数据

msg: '127.0.0.1 ed06b28a-9de1006f INFO unknown method, discard request'
code: '405 Method Not Allowed'

• 输出结果

msg: '127.0.0.1 ed06b28a-9de1006f INFO unknown method, discard request'
code: 'ed06b28a-9de1006f'