Vector 命令行接口(CLI)完全指南:子命令、参数与环境变量详解
Vector 命令行接口(CLI)完全指南:子命令、参数与环境变量详解
导读
Vector 将整个可观测性数据管道(采集、转换、聚合、输出)封装在单个二进制文件中,并通过一套统一的命令行接口对外暴露全部管理能力。本文基于官方文档 website/content/en/docs/reference/cli.md 展开,系统梳理 vector 根命令的全部 flags、options、子命令以及环境变量,并结合 website/cue/reference/cli.cue(文档数据源)与 src/cli.rs(clap 实际定义)逐项给出默认值、取值枚举与底层实现细节。读完本文,你将能够熟练使用 vector 完成配置校验、单元测试、拓扑可视化、事件采样(tap)、指标观测(top)与 VRL 调试等日常运维操作。
总览:单二进制 + 统一入口
Vector 本身就是一个可执行文件,所有功能都挂在同一个入口上,其通用语法为:
vector [FLAGS] [OPTIONS] [SUBCOMMAND] [ARGS]
- 不带任何子命令直接执行
vector,即启动 Vector 数据管道(前台运行,直至收到信号退出); - 携带子命令(如
validate、graph、tap)时,Vector 执行一次性管理操作后退出。
命令行结构由 src/cli.rs 中的 Opts 结构定义:根参数 RootOpts 通过 #[command(flatten)] 合并进 Opts,子命令则封装在 SubCommand 枚举中。所有长参数均使用 kebab-case 命名(rename_all = "kebab-case"),并且绝大多数参数都绑定了对应的环境变量(通过 env = "VECTOR_XXX" 声明),因此你既可以用命令行参数,也可以用环境变量完成同样的配置。
根命令(Root Command)
通用 Flags
根级 flags 大多用于控制日志输出与全局行为,其中多数支持重复叠加(通过 clap 的 ArgAction::Count 实现):
| Flag | 简写 | 说明 | 环境变量 | 默认值 |
|---|---|---|---|---|
--help |
-h |
打印帮助信息 | — | — |
--version |
-V |
打印版本信息 | — | — |
--verbose |
-v |
输出更详细的日志,可重复叠加以逐级提升级别,会覆盖 --quiet |
— | — |
--quiet |
-q |
降低内部日志详细程度,可重复叠加,会覆盖 --verbose |
— | — |
--require-healthy |
-r |
启动时若任一 sink 健康检查失败则直接退出 | VECTOR_REQUIRE_HEALTHY |
false |
--watch-config |
-w |
监听配置文件变化并自动热重载 | VECTOR_WATCH_CONFIG |
false |
--no-graceful-shutdown-limit |
— | 收到 SIGINT/SIGTERM 后永不强制超时退出(直到被 SIGKILL 终止),不能与 --graceful-shutdown-limit-secs 同时设置 |
VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT |
false |
--openssl-no-probe |
— | 禁用 OpenSSL 对系统根证书位置的探测与配置 | VECTOR_OPENSSL_NO_PROBE |
false |
--allow-empty-config |
— | 允许在没有任何组件的情况下启动(通常需配合 --watch-config 使用) |
VECTOR_ALLOW_EMPTY_CONFIG |
false |
--dangerously-allow-env-var-interpolation |
— | 允许配置文件中的环境变量插值(默认关闭,开启可能把环境变量中的机密暴露进配置) | VECTOR_DANGEROUSLY_ALLOW_ENV_VAR_INTERPOLATION |
false |
关于日志级别的叠加规则,src/cli.rs 中的 log_level() 方法给出了精确映射:默认 info;-v 为 debug、-vv 为 trace;-q 为 warn、-qq 为 error、-qqq 及以上为 off。对于 validate、graph、generate、list、test 等一次性管理命令,根级别的 verbose/quiet 计数还会先做一次偏移调整,避免干扰命令自身的输出。
通用 Options
| Option | 简写 | 说明 | 环境变量 | 默认值 |
|---|---|---|---|---|
--config |
-c |
从指定文件读取配置,支持通配符路径与逗号分隔的多个文件;格式按扩展名(.yaml/.toml/.json)识别,无法识别时回退为 YAML |
VECTOR_CONFIG |
/etc/vector/vector.yaml |
--config-dir |
-C |
从目录读取配置(可多个),非 .toml/.json/.yaml/.yml 结尾的文件被忽略 |
VECTOR_CONFIG_DIR |
— |
--config-yaml |
— | 读取配置并强制按 YAML 格式解释(支持通配符与多文件) | VECTOR_CONFIG_YAML |
— |
--config-toml |
— | 读取配置并强制按 TOML 格式解释 | VECTOR_CONFIG_TOML |
— |
--config-json |
— | 读取配置并强制按 JSON 格式解释 | VECTOR_CONFIG_JSON |
— |
--graceful-shutdown-limit-secs |
— | 收到 SIGINT/SIGTERM 后等待优雅退出的秒数,超时则强制退出 | VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS |
60 |
--watch-config-method |
— | 配置文件监听方式:recommended(事件驱动,推荐)或 poll(轮询,适用于 NFS 等事件监听失效的场景) |
VECTOR_WATCH_CONFIG_METHOD |
recommended |
--watch-config-poll-interval-seconds |
— | 轮询监听时的检查间隔(仅当 --watch-config-method 为 poll 时生效) |
VECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS |
30 |
--color |
— | ANSI 终端着色控制,枚举值 auto(自动检测)/always(始终开启)/never(关闭) |
VECTOR_COLOR |
auto |
--log-format |
— | 日志输出格式:text 或 json |
VECTOR_LOG_FORMAT |
text |
--threads |
-t |
处理线程数,默认等于可用 CPU 核数 | VECTOR_THREADS |
可用核数 |
--chunk-size-events |
— | 每个 source 发送批次的事件数,也是 source 输出缓冲区大小的基数 | VECTOR_CHUNK_SIZE_EVENTS |
1000 |
--internal-log-rate-limit |
-i |
内部日志限流窗口(秒),窗口内首条日志正常输出、第二条输出抑制警告、后续静默,窗口结束再次触发时汇总被抑制条数 | VECTOR_INTERNAL_LOG_RATE_LIMIT |
10 |
--internal-logs-source-rate-limit |
— | 作用于广播 internal_logs source 的频道限流(秒),默认不设置,保证消费者收到每条日志 |
VECTOR_INTERNAL_LOGS_SOURCE_RATE_LIMIT |
未设置 |
--max-decompressed-size-bytes |
— | 解压后负载允许的最大字节数,防止压缩炸弹耗尽内存 | VECTOR_MAX_DECOMPRESSED_SIZE_BYTES |
104857600(100 MiB) |
一个典型的启动命令:
vector --config /etc/vector/vector.yaml --require-healthy -v
在 src/cli.rs 中可以核对上述定义:例如 config 参数通过 value_delimiter(',') 支持逗号分隔多文件;verbose/quiet 使用 ArgAction::Count 支持重复计数;color 的 Auto 模式在 Unix 下通过 std::io::stdout().is_terminal() 检测终端(Windows 的 cmd.exe 下直接禁用 ANSI),详见 src/cli.rs。
子命令详解
SubCommand 枚举定义于 src/cli.rs,官方文档收录了以下九个公开子命令(另有 convert-config、generate-schema、completion(隐藏)、service(仅 Windows 编译时启用)等未列入文档的子命令,可从源码枚举中查得)。各子命令都继承了根级 flags 与 options(_default_flags、_core_flags、_core_options),因此 --config、--verbose 等参数在子命令下同样可用。
vector graph:拓扑可视化
以 DOT 语言输出管道拓扑图,可配合 GraphViz 渲染成图片:
vector graph --config /etc/vector/vector.yaml | dot -Tsvg > graph.svg
该命令的 --config 等核心 options 与根命令一致;vector graph 的渲染流程见 src/graph.rs 中的 cmd 实现。
vector generate:生成配置
根据组件列表生成一份 Vector 配置,参数 pipeline 使用 组件/子组件 语法描述流水线:
| 参数/选项 | 说明 |
|---|---|
pipeline(位置参数,string) |
流水线表达式,例如 stdin/remap,filter/console |
--fragment / -f(flag) |
跳过全局字段的生成,只输出组件片段 |
--file(option,string) |
将生成的配置写入文件,例如 /etc/vector/my-config.toml |
示例:
vector generate stdin/remap,filter/console --file /etc/vector/my-config.toml
vector list:列出可用组件
列出当前二进制内编译进来的全部组件后退出,常用于确认某个组件是否可用:
vector list
| Option | 说明 | 默认值 |
|---|---|---|
--format |
输出编码格式,枚举:text(文本)、json(JSON)、avro(Apache Avro) |
text |
vector validate:校验配置
校验目标配置的完整性与正确性后退出(不启动管道),是 CI 中检查配置变更的首选命令:
vector validate /etc/vector/vector.yaml
- 位置参数
paths(list):任意数量的配置文件;不指定时默认校验/etc/vector/vector.yaml。 --config-yaml/--config-toml/--config-json:分别强制按对应格式解释配置文件。- 专属 flags:
--no-environment:跳过环境检查(包括组件级检查与健康检查);--skip-healthchecks:仅跳过健康检查;--deny-warnings/-d:将告警视为失败,任何 warning 都导致校验失败。
vector test:配置单元测试(实验性)
执行配置中内置的单元测试并退出。该命令标记为实验性,接口可能随版本变化;单元测试的编写方式可参考仓库中的 unit_test 相关模块(src/config/unit_test)。位置参数 paths 与 validate 相同,也支持 --config-yaml/--config-toml/--config-json 强制格式。
vector test /etc/vector/vector.yaml
vector tap:事件采样(实验性)
通过 Vector gRPC API 观察流经组件的真实事件:观察"进入 transforms/sinks 的输入"以及"从 sources/transforms 流出的输出",并按固定间隔采样打印。
| Flag | 简写 | 说明 |
|---|---|---|
--quiet |
-q |
仅输出事件本身,抑制 stderr 上的诊断信息 |
--meta |
-m |
输出中附带 component_id 元数据,真实事件嵌套在 event 键下 |
--no-reconnect |
-n |
API 连接断开后不自动重连 |
--duration_ms |
-d |
指定采样时长(毫秒),例如 10000 表示采样 10 秒后自动退出 |
| Option | 简写 | 说明 | 默认值 |
|---|---|---|---|
--url |
-u |
Vector gRPC API 服务端点 | — |
--interval |
-i |
采样间隔(毫秒) | 500 |
--limit |
-l |
每个采样间隔最多输出的事件数 | 100 |
--format |
-f |
事件输出编码,枚举:json、yaml、logfmt |
json |
--inputs-of |
— | 观察指定组件的输入(逗号分隔,支持 glob 模式) | 空 |
--outputs-of |
— | 观察指定组件的输出(逗号分隔,支持 glob 模式);仅当未指定任何 --outputs-of/--inputs-of 时默认值为 * |
* |
components(位置参数,list) |
— | 待观察的组件(sources、transforms),逗号分隔,支持 glob | * |
示例:
vector tap -u http://127.0.0.1:8686 --outputs-of 'sample*' -d 10000
vector top:控制台实时观测
以 TUI 形式在控制台展示本地或远程 Vector 实例的拓扑与指标(需编译 top feature):
| Flag | 简写 | 说明 |
|---|---|---|
--human-metrics |
-H |
人性化指标数字,例如 1,100 → 1.10 k、1,000,000 → 1.00 M |
--no-reconnect |
-n |
连接断开后不自动重连 |
| Option | 简写 | 说明 | 默认值 |
|---|---|---|---|
--components |
-c |
待观察的组件 ID(逗号分隔,支持 glob) | * |
--interval |
-i |
指标采样间隔(毫秒) | 1000 |
--url |
-u |
Vector gRPC API 服务端点 | — |
vector top --url http://127.0.0.1:8686 -c 'kafka*'
tap 与 top 都依赖 Vector 的 gRPC API,需要在目标实例的配置中启用 api 并开放对应地址(见 src/api)。
vector vrl:VRL 调试器
Vector Remap Language(VRL)的独立 CLI,可在不运行管道的情况下单步调试 VRL 程序,非常适合编写 remap 转换时反复试验:
vector vrl ".foo = true"
| 参数/选项 | 说明 |
|---|---|
program(位置参数,string) |
要执行的 VRL 程序,例如 ".foo = true" 将对象 foo 字段置为 true |
--input / -i(option) |
存放待操作对象(一个或多个)的文件;留空则从 stdin 读取 |
--program / -p(option) |
存放程序的脚本文件,可替代位置参数 PROGRAM |
--print-object / -o(flag) |
打印(修改后的)整个对象,而非最后一条表达式的结果;等价于以 . 作为末条表达式 |
示例——从文件读取 JSON 对象并执行程序:
vector vrl -i event.json -p remap.vrl
vector help:帮助信息
vector help 打印根命令帮助;vector help <subcommand> 打印指定子命令的帮助。所有子命令的帮助也可以直接用 vector <subcommand> --help 查看。
环境变量(Environment Variables)
所有核心环境变量在 website/cue/reference/cli.cue 中集中定义,并通过 website/layouts/shortcodes/cli/env-vars.html 注入页面。除下列全局变量外,该小节还会合并 aws_cloudwatch_logs、docker_logs、gcp_stackdriver_logs 等组件专属的环境变量。
配置加载类
| 环境变量 | 说明 | 默认值 |
|---|---|---|
VECTOR_CONFIG |
从文件读取配置(支持通配符与多文件),格式由扩展名推断,无法识别回退 YAML | /etc/vector/vector.yaml |
VECTOR_CONFIG_DIR |
从目录读取配置,非 .toml/.json/.yaml/.yml 文件被忽略 |
— |
VECTOR_CONFIG_YAML |
按 YAML 格式读取配置 | — |
VECTOR_CONFIG_TOML |
按 TOML 格式读取配置 | — |
VECTOR_CONFIG_JSON |
按 JSON 格式读取配置 | — |
日志与可观测类
| 环境变量 | 说明 | 默认值 |
|---|---|---|
VECTOR_LOG |
日志级别,枚举:ERROR(等价 -qq)、WARN(等价 -q)、INFO(默认)、DEBUG(等价 -v)、TRACE(等价 -vv) |
INFO |
VECTOR_LOG_FORMAT |
日志格式:text 或 json |
text |
VECTOR_COLOR |
ANSI 着色:auto/always/never |
auto |
VECTOR_INTERNAL_LOG_RATE_LIMIT |
内部日志限流窗口(秒),作用于 stdout/stderr 输出 | 10 |
VECTOR_INTERNAL_LOGS_SOURCE_RATE_LIMIT |
internal_logs source 广播频道限流(秒),独立于上面的 stdout/stderr 限流 |
未设置 |
VECTOR_HOSTNAME |
覆盖日志与指标中使用的 hostname,容器或 Kubernetes 场景下尤其有用(例如在 Pod 中取 spec.nodeName) |
— |
PROCFS_ROOT |
指定系统 procfs 挂载根路径,用于在容器内采集宿主主机指标 | 系统 /proc |
SYSFS_ROOT |
指定系统 sysfs 挂载根路径,示例 /mnt/host/sys |
系统 /sys |
RUST_BACKTRACE |
出错时打印 Rust backtrace,仅建议调试时开启(会降低性能) | false |
运行与关闭行为类
| 环境变量 | 说明 | 默认值 |
|---|---|---|
VECTOR_THREADS |
处理线程数 | 可用 CPU 核数 |
VECTOR_CHUNK_SIZE_EVENTS |
每个 source 发送批次的事件数,及 source 输出缓冲的基数 | 1000 |
VECTOR_REQUIRE_HEALTHY |
启动时任一 sink 健康检查失败即退出 | false |
VECTOR_WATCH_CONFIG |
监听配置变更并热重载 | false |
VECTOR_WATCH_CONFIG_METHOD |
监听方式:recommended 或 poll |
recommended |
VECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS |
轮询间隔(秒),仅 poll 模式生效 |
30 |
VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS |
SIGINT/SIGTERM 后的优雅退出等待秒数,超时强制退出 | 60 |
VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT |
永不强制超时退出,直到被 SIGKILL 终止 | false |
VECTOR_ALLOW_EMPTY_CONFIG |
允许无任何组件的空配置启动(通常配合配置热重载使用) | false |
安全与兼容类
| 环境变量 | 说明 | 默认值 |
|---|---|---|
VECTOR_DANGEROUSLY_ALLOW_ENV_VAR_INTERPOLATION |
允许配置中的环境变量插值(默认关闭,开启可能泄露环境机密) | false |
VECTOR_STRICT_ENV_VARS |
环境变量插值严格模式:缺失变量报错而非告警。该选项已弃用,未来版本将移除"降级为告警"的能力 | true |
VECTOR_OPENSSL_NO_PROBE |
禁用 OpenSSL 根证书位置探测(该探测会修改进程内 SSL_CERT_FILE/SSL_CERT_DIR,可能影响继承 Vector 环境的 exec source) |
false |
VECTOR_MAX_DECOMPRESSED_SIZE_BYTES |
解压后负载的最大字节数上限,防止压缩炸弹耗尽内存 | 104857600(100 MiB) |
环境变量与命令行参数的对应关系可以在 src/cli.rs 的 #[arg(env = "...")] 声明中逐一印证,例如 VECTOR_CONFIG ↔ --config、VECTOR_THREADS ↔ --threads。当两者同时出现时,命令行参数优先。
文档数据从哪里来:CUE 驱动文档生成
website/content/en/docs/reference/cli.md 本身非常精简,正文通过两个 shortcode 渲染出完整内容:
{{< cli/commands >}}:由 website/layouts/shortcodes/cli/commands.html 渲染,读取site.Data.docs.cli生成根命令与各子命令的 usage、flags/options/args 表格(支持枚举展开、环境变量交叉链接);{{< cli/env-vars >}}:由 website/layouts/shortcodes/cli/env-vars.html 渲染,合并cli.env_vars与部分组件专属环境变量。
而 site.Data.docs.cli 的源头正是 website/cue/reference/cli.cue:该文件以 CUE 模式(schema)定义了 #Flags、#Options、#Commands、#Args、#EnvVars 等结构化约束(例如带 enum 的 option 自动将 type 置为 enum、无默认值的 option 标记为 required),再填充实际的命令与变量数据,最后生成 JSON 供站点使用。这意味着本文列出的所有参数、枚举与默认值都可以在 cli.cue 与 src/cli.rs 中双向核对,文档与实现保持一致。
实操建议:把 CLI 接入日常流程
- CI 配置检查:任何配置变更合并前执行
vector validate --deny-warnings <config>,让告警也阻塞发布; - 变更前试运行单元测试:
vector test <config>可在不启动管道的情况下验证test段断言; - 拓扑审查:
vector graph --config <config> | dot -Tpng > topology.png快速审查数据流; - 线上排障:启用
api后,用vector tap观察具体组件的输入输出、用vector top监控各组件吞吐与错误; - VRL 开发:先用
vector vrl本地调好程序,再粘贴进remap转换,可显著减少线上试错; - 容器场景:通过
VECTOR_HOSTNAME注入有意义的节点名,通过PROCFS_ROOT/SYSFS_ROOT采集宿主指标。
如需进一步了解配置文件的完整语法与组件编写方式,可继续阅读 config/vector.yaml 与 website/content/en/docs/reference/configuration 下的参考文档。