鲁兹：鲁兹（Ruz）精讲：从零到一的完整实操指南
读完本文，你将彻底掌握鲁兹的安装、配置、核心操作与故障排查，能独立完成从数据接入到结果输出的全流程任务，不再被“报错”卡住。
鲁兹（Ruz）是一套轻量级的数据流处理工具，常用于日志清洗、字段映射和实时管道搭建。它的核心思想是“声明式管道”：你定义输入、处理规则和输出，鲁兹自动完成调度。下面按步骤拆解实操。
第一步：环境准备与安装
鲁兹依赖Python 3.9+和pip。先创建虚拟环境避免污染系统：
```bash
python -m venv ruz_env
source ruz_env/bin/activate # Windows用 ruz_env\Scripts\activate
```
然后安装：
```bash
pip install ruz-cli
```
验证安装：`ruz --version`。若出现“command not found”，检查是否将虚拟环境的bin目录加入PATH。安装完成后，鲁兹自带一个示例配置，运行`ruz demo`生成`demo.yaml`文件，这是后续练习的基础。
第二步：理解核心配置文件
鲁兹的所有操作都在一个YAML文件中定义。最小结构如下：
```yaml
input:
type: file
path: ./data/input.log
processors:
- type: regex
pattern: '(\d{4}-\d{2}-\d{2})'
target: date
output:
type: console
```
- `input`：数据来源，支持file、kafka、http等。
- `processors`：处理链，按顺序执行。每个处理器有`type`和参数。
- `output`：结果去向，console、file、elasticsearch等。
打开`demo.yaml`，逐行注释理解。重点注意：字段名`target`代表将提取结果存到哪个新字段。
第三步：编写第一个管道——日志清洗
假设`input.log`每行是`2025-01-01 12:00:00 ERROR 连接超时`。目标：提取日期、级别和消息，并过滤掉INFO级别。
在`processors`中配置：
```yaml
processors:
- type: regex
pattern: '^(\S+)\s+(\S+)\s+(\S+)\s+(.*)$'
targets: [date, time, level, message]
- type: filter
condition: 'level != "INFO"'
```
注意：`regex`的`targets`必须与捕获组数量一致。`filter`的`condition`支持Python表达式，引用字段用字段名。运行：
```bash
ruz run -c my_pipeline.yaml
```
观察输出。如果报错“字段未定义”，检查正则是否匹配了空行——用`skip_empty_lines: true`加在input下。
第四步：字段变换与数据增强
鲁兹内置`transform`处理器，可做类型转换和拼接：
```yaml
- type: transform
operations:
- field: date
action: strptime
format: '%Y-%m-%d'
output: timestamp
- field: full_message
action: concat
fields: [date, time, message]
separator: ' '
```
`strptime`将字符串转成日期对象，`concat`生成新字段。若需调用自定义函数，用`type: python`处理器，内嵌Python代码：
```yaml
- type: python
code: |
def process(event):
event['level_upper'] = event['level'].upper()
return event
```
注意：自定义函数必须命名为`process`，接受event字典并返回它。
第五步：输出到文件与外部系统
将输出改为写文件：
```yaml
output:
type: file
path: ./output/clean.log
format: jsonl # 或 csv, plain
```
如果输出到Kafka：
```yaml
output:
type: kafka
topic: clean-events
bootstrap_servers: 'localhost:9092'
```
鲁兹支持批量缓冲，在output下加`batch_size: 100`和`flush_interval: 5`（秒），避免每条写一次。注意：Kafka输出前必须确保topic存在，否则报“unknown topic”——用`ruz kafka --create-topic clean-events`预创建。
第六步：调试与日志追踪
运行加`--debug`参数会打印每条event的完整内容：
```bash
ruz run -c my_pipeline.yaml --debug
```
更高级：在任意处理器后加`- type: debug`，它会在处理链中途输出当前状态，适合定位“某一步之后字段丢了”的问题。另外，鲁兹支持`--dry-run`，只读输入不写输出，用于检查正则是否匹配。
第七步：定时调度与监控
用`ruz schedule`启动常驻任务：
```bash
ruz schedule -c my_pipeline.yaml --interval 60
```
每60秒读取一次输入文件的新增内容（需设置input的`follow: true`）。监控方面，鲁兹内置HTTP健康检查端点，在配置文件顶部加：
```yaml
server:
port: 8080
```
然后访问`http://localhost:8080/health`，返回JSON状态。若进程崩溃，系统会重启——但需确保用systemd或supervisor管理，否则退出后不会自动拉起。
常见坑与避坑指南
1. 正则贪婪陷阱：`(.*)`会吞掉整行，导致后续字段为空。务必用非贪婪`(.*?)`或限制字符类`([^\s]+)`。
2. 字段名冲突：如果新字段名与已有字段重名，鲁兹默认覆盖——不想覆盖要加`overwrite: false`。
3. 时区问题：`strptime`解析的日期是naive类型，若后续比较需时区，先`astimezone`。
4. 大文件内存溢出：input默认一次读全文件，加`chunk_size: 1000`改为流式读取。
5. Kafka重平衡：多个消费者实例时，用`group_id`指定，否则默认随机组会导致消息重复处理。
6. YAML缩进错误：鲁兹对缩进极其敏感，用2空格，不要用Tab。报错“mapping values are not allowed”多半是冒号后缺空格。
7. 忘记处理空行：空行会让正则处理器报错，一律在input下加`skip_empty_lines: true`。
最后，建议每写一个处理器就跑一次`--debug`，确认无副作用再叠加下一步。鲁兹的哲学是“显式优于隐式”，所有字段变化必须明确声明，这虽然繁琐，但能避免生产环境出现幽灵数据。
