【笔记】如何调试 vector 的 VRL 语言

作者:张富春(ahfuzhang)，转载时请注明作者和引用链接，谢谢！

• cnblogs博客
• zhihu
• Github
• 公众号:一本正经的瞎扯
  

---

需要使用 vector 的 transform 来对日志做 ETL, 但是这个叫做 VRL 的语言实在太难写了。
碰壁了很久终于找到了如下调试方式：

在线 playground

see: https://playground.vrl.dev/

分别输入脚本和日志数据，运行后就可以看到处理结果。

docker 命令行

playground 无法选择对应的 vector 版本，可能需要使用特定的版本号来调试。
我们团队使用了这个镜像： timberio/vector:0.48.0-distroless-libc

• 如下命令可以看见 VRL 的命令行参数：

docker run -it --rm \
          --cpus=1 -m=512m \
          -e VECTOR_LOG=debug \
          timberio/vector:0.48.0-distroless-libc vrl --help

可以看见：

Usage: vector vrl [OPTIONS] [PROGRAM]

Arguments:
  [PROGRAM]  The VRL program to execute. The program ".foo = true", for example, sets the event object's `foo` field to `true`

Options:
  -i, --input <INPUT_FILE>      The file containing the event object(s) to handle. JSON events should be one per line..
  -p, --program <PROGRAM_FILE>  The file containing the VRL program to execute. This can be used instead of `PROGRAM`
  -o, --print-object            Print the (modified) event object instead of the result of the final expression. Setting this flag is equivalent to using `.` as the
                                final expression
  -z, --timezone <TIMEZONE>     The timezone used to parse dates
  -r, --runtime <RUNTIME>       Should we use the VM to evaluate the VRL [default: ast]
      --print-warnings
  -h, --help                    Print help

• 在某个目录下准备日志文件: haproxy.log
  格式大致如下：

{ "time":"06/Nov/2025:04:53:43.724","client_ip":"f408:8469:f7d0:231:f8f4:5fa:cfff:f05a","bytes_read":"1138","captured_request_headers":"api.xxx.com - 5d4e -","http_method":"POST","http_request_path":"/api/v2/Spin","http_request_query_string":"?traceId=BQEIHM06","http_version":"HTTP/1.1","server_name":"host-190","status_code":"200"}

• 准备一个脚本： program.vrl

log_json,err = parse_json(.message)
if err == null && is_object(log_json) {
  log_json = object!(log_json)
  . |= log_json
  if exists(log_json.MessageTemplate) {
    del(log_json.MessageTemplate)
  }
  ._msg = encode_json(log_json)
  del(.message)
}

• 使用命令行运行，进行调试：

docker run -it --rm \
          --cpus=1 -m=512m \
          -e VECTOR_LOG=debug \
          -v ~/Downloads/temp/2025/2025-11-21/:/data/ \
          timberio/vector:0.48.0-distroless-libc vrl \
            -i /data/in.json \
            -p /data/program.vrl \
            --print-warnings \
            --print-object

这下调试起来就舒心了。
Have fun. 😃