Vector 命令行接口CLI完全指南子命令、参数与环境变量详解【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读Vector 将整个可观测性数据管道采集、转换、聚合、输出封装在单个二进制文件中并通过一套统一的命令行接口对外暴露全部管理能力。本文基于官方文档 website/content/en/docs/reference/cli.md 展开系统梳理vector根命令的全部 flags、options、子命令以及环境变量并结合 website/cue/reference/cli.cue文档数据源与 src/cli.rsclap 实际定义逐项给出默认值、取值枚举与底层实现细节。读完本文你将能够熟练使用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_HEALTHYfalse--watch-config-w监听配置文件变化并自动热重载VECTOR_WATCH_CONFIGfalse--no-graceful-shutdown-limit—收到 SIGINT/SIGTERM 后永不强制超时退出直到被 SIGKILL 终止不能与--graceful-shutdown-limit-secs同时设置VECTOR_NO_GRACEFUL_SHUTDOWN_LIMITfalse--openssl-no-probe—禁用 OpenSSL 对系统根证书位置的探测与配置VECTOR_OPENSSL_NO_PROBEfalse--allow-empty-config—允许在没有任何组件的情况下启动通常需配合--watch-config使用VECTOR_ALLOW_EMPTY_CONFIGfalse--dangerously-allow-env-var-interpolation—允许配置文件中的环境变量插值默认关闭开启可能把环境变量中的机密暴露进配置VECTOR_DANGEROUSLY_ALLOW_ENV_VAR_INTERPOLATIONfalse关于日志级别的叠加规则src/cli.rs 中的log_level()方法给出了精确映射默认info-v为debug、-vv为trace-q为warn、-qq为error、-qqq及以上为off。对于validate、graph、generate、list、test等一次性管理命令根级别的 verbose/quiet 计数还会先做一次偏移调整避免干扰命令自身的输出。通用 OptionsOption简写说明环境变量默认值--config-c从指定文件读取配置支持通配符路径与逗号分隔的多个文件格式按扩展名.yaml/.toml/.json识别无法识别时回退为 YAMLVECTOR_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_SECS60--watch-config-method—配置文件监听方式recommended事件驱动推荐或poll轮询适用于 NFS 等事件监听失效的场景VECTOR_WATCH_CONFIG_METHODrecommended--watch-config-poll-interval-seconds—轮询监听时的检查间隔仅当--watch-config-method为poll时生效VECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS30--color—ANSI 终端着色控制枚举值auto自动检测/always始终开启/never关闭VECTOR_COLORauto--log-format—日志输出格式text或jsonVECTOR_LOG_FORMATtext--threads-t处理线程数默认等于可用 CPU 核数VECTOR_THREADS可用核数--chunk-size-events—每个 source 发送批次的事件数也是 source 输出缓冲区大小的基数VECTOR_CHUNK_SIZE_EVENTS1000--internal-log-rate-limit-i内部日志限流窗口秒窗口内首条日志正常输出、第二条输出抑制警告、后续静默窗口结束再次触发时汇总被抑制条数VECTOR_INTERNAL_LOG_RATE_LIMIT10--internal-logs-source-rate-limit—作用于广播internal_logssource 的频道限流秒默认不设置保证消费者收到每条日志VECTOR_INTERNAL_LOGS_SOURCE_RATE_LIMIT未设置--max-decompressed-size-bytes—解压后负载允许的最大字节数防止压缩炸弹耗尽内存VECTOR_MAX_DECOMPRESSED_SIZE_BYTES104857600100 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/-fflag跳过全局字段的生成只输出组件片段--fileoptionstring将生成的配置写入文件例如/etc/vector/my-config.toml示例vector generate stdin/remap,filter/console --file /etc/vector/my-config.tomlvector list列出可用组件列出当前二进制内编译进来的全部组件后退出常用于确认某个组件是否可用vector listOption说明默认值--format输出编码格式枚举text文本、jsonJSON、avroApache Avrotextvector validate校验配置校验目标配置的完整性与正确性后退出不启动管道是 CI 中检查配置变更的首选命令vector validate /etc/vector/vector.yaml位置参数pathslist任意数量的配置文件不指定时默认校验/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.yamlvector tap事件采样实验性通过 Vector gRPC API 观察流经组件的真实事件观察进入 transforms/sinks 的输入以及从 sources/transforms 流出的输出并按固定间隔采样打印。Flag简写说明--quiet-q仅输出事件本身抑制 stderr 上的诊断信息--meta-m输出中附带component_id元数据真实事件嵌套在event键下--no-reconnect-nAPI 连接断开后不自动重连--duration_ms-d指定采样时长毫秒例如10000表示采样 10 秒后自动退出Option简写说明默认值--url-uVector gRPC API 服务端点—--interval-i采样间隔毫秒500--limit-l每个采样间隔最多输出的事件数100--format-f事件输出编码枚举json、yaml、logfmtjson--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 10000vector top控制台实时观测以 TUI 形式在控制台展示本地或远程 Vector 实例的拓扑与指标需编译topfeatureFlag简写说明--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-uVector gRPC API 服务端点—vector top --url http://127.0.0.1:8686 -c kafka*tap与top都依赖 Vector 的 gRPC API需要在目标实例的配置中启用api并开放对应地址见 src/api。vector vrlVRL 调试器Vector Remap LanguageVRL的独立 CLI可在不运行管道的情况下单步调试 VRL 程序非常适合编写remap转换时反复试验vector vrl .foo true参数/选项说明program位置参数string要执行的 VRL 程序例如.foo true将对象foo字段置为true--input/-ioption存放待操作对象一个或多个的文件留空则从 stdin 读取--program/-poption存放程序的脚本文件可替代位置参数PROGRAM--print-object/-oflag打印修改后的整个对象而非最后一条表达式的结果等价于以.作为末条表达式示例——从文件读取 JSON 对象并执行程序vector vrl -i event.json -p remap.vrlvector 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.yamlVECTOR_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等价-vvINFOVECTOR_LOG_FORMAT日志格式text或jsontextVECTOR_COLORANSI 着色auto/always/neverautoVECTOR_INTERNAL_LOG_RATE_LIMIT内部日志限流窗口秒作用于 stdout/stderr 输出10VECTOR_INTERNAL_LOGS_SOURCE_RATE_LIMITinternal_logssource 广播频道限流秒独立于上面的 stdout/stderr 限流未设置VECTOR_HOSTNAME覆盖日志与指标中使用的 hostname容器或 Kubernetes 场景下尤其有用例如在 Pod 中取spec.nodeName—PROCFS_ROOT指定系统 procfs 挂载根路径用于在容器内采集宿主主机指标系统/procSYSFS_ROOT指定系统 sysfs 挂载根路径示例/mnt/host/sys系统/sysRUST_BACKTRACE出错时打印 Rust backtrace仅建议调试时开启会降低性能false运行与关闭行为类环境变量说明默认值VECTOR_THREADS处理线程数可用 CPU 核数VECTOR_CHUNK_SIZE_EVENTS每个 source 发送批次的事件数及 source 输出缓冲的基数1000VECTOR_REQUIRE_HEALTHY启动时任一 sink 健康检查失败即退出falseVECTOR_WATCH_CONFIG监听配置变更并热重载falseVECTOR_WATCH_CONFIG_METHOD监听方式recommended或pollrecommendedVECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS轮询间隔秒仅poll模式生效30VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECSSIGINT/SIGTERM 后的优雅退出等待秒数超时强制退出60VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT永不强制超时退出直到被 SIGKILL 终止falseVECTOR_ALLOW_EMPTY_CONFIG允许无任何组件的空配置启动通常配合配置热重载使用false安全与兼容类环境变量说明默认值VECTOR_DANGEROUSLY_ALLOW_ENV_VAR_INTERPOLATION允许配置中的环境变量插值默认关闭开启可能泄露环境机密falseVECTOR_STRICT_ENV_VARS环境变量插值严格模式缺失变量报错而非告警。该选项已弃用未来版本将移除降级为告警的能力trueVECTOR_OPENSSL_NO_PROBE禁用 OpenSSL 根证书位置探测该探测会修改进程内SSL_CERT_FILE/SSL_CERT_DIR可能影响继承 Vector 环境的execsourcefalseVECTOR_MAX_DECOMPRESSED_SIZE_BYTES解压后负载的最大字节数上限防止压缩炸弹耗尽内存104857600100 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 下的参考文档。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考