WPL 快速入门

5 分钟上手 WPL，立即解析你的日志数据。

📚 快速导航

什么是 WPL

WPL (Warp Processing Language) 是一种声明式规则语言，用于描述如何从日志、消息等文本数据中提取字段和解析结构。

核心特点

• 声明式：描述“数据是什么“，而非“如何提取“
• 类型安全：自动验证和转换（IP、时间、JSON 等 37 种类型）
• 强大灵活：支持 JSON/KV 嵌套提取、Base64 解码、字段验证等
• 易于学习：5 分钟即可上手基础用法

适用场景

• 解析 Web 服务器日志（Nginx、Apache）
• 提取 JSON/KV 结构化数据
• 处理编码数据（Base64、Hex）
• 防火墙、安全设备日志解析
• 自定义日志格式解析

📚 完整类型系统

WPL 支持 23 种主要数据类型，涵盖基础类型、时间、网络、结构化数据、协议和编码等。

👉 查看完整示例： 07-complete-types-example.md

该文档包含：

• ✅ 所有 23 种类型的完整示例代码
• ✅ 可运行的输入数据和 WPL 规则
• ✅ 每种类型的详细说明和使用建议
• ✅ 常见类型组合模式

快速预览主要类型：

• 基础：digit、float、chars、bool
• 时间：time/clf、time_3339、time_2822、time_timestamp
• 网络：ip、ip_net、port、domain、url
• 结构化：json、kvarr、array
• 协议：http/request、http/status、http/method、http/agent
• 编码：hex、base64

最简示例：Nginx 日志

输入数据：

192.168.1.2 - - [06/Aug/2019:12:12:19 +0800] "GET /index.html HTTP/1.1" 200 1024

WPL 规则：

package nginx {
  rule access_log {
    (
      ip:client_ip,
      2*_,
      time/clf<[,]>:time,
      http/request":request,
      digit:status,
      digit:bytes
    )
  }
}

输出结果：

client_ip: 192.168.1.2
time: 2019-08-06 12:12:19
request: GET /index.html HTTP/1.1
status: 200
bytes: 1024

说明：

• ip:client_ip - 提取 IP 地址，命名为 client_ip
• 2*_ - 忽略 2 个字段（两个 -）
• time/clf<[,]> - 提取方括号包裹的 CLF 时间
• http/request" - 提取引号包裹的 HTTP 请求
• digit - 提取数字

3 个最常用场景

场景 1：空格分隔的日志

输入：

200 192.168.1.1 2023-01-01T12:00:00 login_success

WPL：

package demo {
  rule simple_log {
    (digit:code, ip:client, time:ts, chars:action)
  }
}

输出：

code: 200
client: 192.168.1.1
ts: 2023-01-01 12:00:00
action: login_success

场景 2：JSON 数据

输入：

{"user":"admin","code":200,"message":"success"}

WPL：

package api {
  rule json_response {
    (json(
      chars@user,
      digit@code,
      chars@message
    ))
  }
}

输出：

user: admin
code: 200
message: success

场景 3：KV 键值对

输入：

host=server1;port=8080;user=admin;status=online

WPL：

package config {
  rule kv_log {
    (kvarr)
  }
}

输出：

host: server1
port: 8080
user: admin
status: online

基本语法速览

结构

package 包名 {
  rule 规则名 {
    (字段列表)
  }
}

常用字段类型

字段命名

type:name              # 命名字段
digit:status           # status = 数字
ip:client_ip           # client_ip = IP地址

忽略字段

_                      # 忽略 1 个字段
2*_                    # 忽略 2 个字段
5*_                    # 忽略 5 个字段

格式控制

<[,]>                  # 方括号包裹：[content]
<{,}>                  # 花括号包裹：{content}
"                      # 引号包裹："content"
^N                     # 固定 N 个字符

重复模式

kvarr                  # 自动解析所有KV
3*ip                   # 重复 3 次
12*digit               # 重复 12 次

子字段提取

# JSON 子字段
json(chars@name, digit@age)

# KV 子字段
kvarr(chars@host, digit@port)

# 嵌套字段
json(chars@user/name, digit@user/age)

常见模式速查

解析带引号的字段

chars":url             # "http://example.com"
http/agent":ua         # "Mozilla/5.0..."

解析带特殊分隔符的数据

# 逗号分隔
(digit, ip, chars)\,

# 分号分隔
(digit, ip, chars)\;

# 字段级分隔符（优先级更高）
digit\,, ip\;, chars\s

可选字段

opt(chars)             # 可选字段
(digit, opt(chars), time)

Base64 解码

|decode/base64|
(json(chars@data))

快速调试技巧

1. 从简单开始

# 第 1 步：最简单
(digit)

# 第 2 步：添加字段
(digit, ip)

# 第 3 步：添加命名
(digit:status, ip:client)

# 第 4 步：添加复杂类型
(digit:status, ip:client, json(chars@name))

2. 使用 opt() 定位问题

# 如果某个字段导致失败，用 opt 包裹
(digit, opt(ip), time, chars)
# 如果 ip 解析失败，其他字段仍然可以解析

3. 检查分隔符

打印原始数据，确认字段间的分隔符：

数据：200,192.168.1.1,admin
分隔符：逗号
规则：(digit, ip, chars)\,

下一步

理解概念

→ 02-core-concepts.md - 理解 WPL 的设计理念

你将学到：

• 为什么 WPL 这样设计？
• 类型系统的作用
• 匹配语义（seq/alt/opt/some_of）
• 管道系统原理
• 分隔符优先级

解决实际问题

→ 03-practical-guide.md - 按任务查找解决方案

你将学到：

• 解析 Web 服务器日志（Nginx/Apache）
• 解析 JSON 数据（嵌套、反转义）
• 解析 KV 键值对（多种分隔符）
• 处理编码数据（Base64/Hex）
• 字段验证与过滤
• 复杂场景（重复模式、可选字段）

查阅参考

→ 04-language-reference.md - 完整类型和语法参考 → 05-functions-reference.md - 所有函数参考

实战练习

练习 1：解析自定义日志

数据：

[2023-01-01 12:00:00] INFO 192.168.1.1 user=admin action=login

提示：

• 时间在方括号中
• INFO 可以忽略
• 后面是 IP 和 KV

package practice {
  rule custom_log {
    (
      time<[,]>:timestamp,
      _,
      ip:client,
      kvarr
    )
  }
}

练习 2：解析嵌套 JSON

数据：

{"user":{"name":"Alice","age":25},"status":"active"}

提示：

• 使用 @path/to/field 提取嵌套字段

package practice {
  rule nested_json {
    (json(
      chars@user/name,
      digit@user/age,
      chars@status
    ))
  }
}

练习 3：解析 Base64 编码日志

数据（Base64）：

eyJ1c2VyIjoiYWRtaW4iLCJjb2RlIjoyMDB9

解码后：

{"user":"admin","code":200}

提示：

• 使用 |decode/base64| 预处理

package practice {
  rule base64_log {
    |decode/base64|
    (json(
      chars@user,
      digit@code
    ))
  }
}

相关资源

• 核心概念：02-core-concepts.md
• 实战指南：03-practical-guide.md
• 语言参考：04-language-reference.md
• 函数参考：05-functions-reference.md
• 语法规范：06-grammar-reference.md