Vector 命令行接口(CLI)完全指南:子命令、参数与环境变量详解

原创2026-09-12 18:31:222,332 阅读
文章标签:可观测性日志分析指标监控链路追踪数据集成流处理云原生后端

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 渲染出完整内容:

而 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 接入日常流程

  1. CI 配置检查:任何配置变更合并前执行 vector validate --deny-warnings <config>,让告警也阻塞发布;
  2. 变更前试运行单元测试:vector test <config> 可在不启动管道的情况下验证 test 段断言;
  3. 拓扑审查:vector graph --config <config> | dot -Tpng > topology.png 快速审查数据流;
  4. 线上排障:启用 api 后,用 vector tap 观察具体组件的输入输出、用 vector top 监控各组件吞吐与错误;
  5. VRL 开发:先用 vector vrl 本地调好程序,再粘贴进 remap 转换,可显著减少线上试错;
  6. 容器场景:通过 VECTOR_HOSTNAME 注入有意义的节点名,通过 PROCFS_ROOT/SYSFS_ROOT 采集宿主指标。

如需进一步了解配置文件的完整语法与组件编写方式,可继续阅读 config/vector.yaml 与 website/content/en/docs/reference/configuration 下的参考文档。

登录后查看全文
vector