VictoriaMetrics Enterprise 命令行参数权威指南许可证、降采样、保留过滤、慢查询统计与 mTLS 自动证书【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics本篇指南以 VictoriaMetrics 仓库中自动生成的 Enterprise 专属命令行参数清单docs/victoriametrics/victoria_metrics_enterprise_flags.md为骨架逐一讲解全部 14 个仅在 Enterprise 二进制中可用的 flag并下沉到仓库源码与官方文档验证每个参数的真实行为。读完本文你将掌握如何正确配置并热更新 Enterprise 许可证、如何用-downsampling.period做多级按标签降采样、如何用-retentionFilter实现多保留期、如何开启慢查询统计并基于 VictoriaLogs 分析以及如何为组件启用 mTLS 防护与 Lets Encrypt 自动证书签发。说明该清单文件由发布流程自动生成文件头注明 The file should not be updated manually. Run make docs-update-flags...因此它与实际二进制的 flag 定义保持严格一致是查阅 Enterprise 参数的权威入口。所有参数同样适用于 VictoriaMetrics 集群版vmselect / vmstorage / vminsert / vmagent / vmalert 等组件对应场景。参数总览与通用数组语法清单共包含 14 个 Enterprise 专属 flag按用途可分为四组分组参数用途许可证-eula、-license、-license.forceOffline、-licenseFile、-licenseFile.reloadInterval激活与校验 Enterprise 授权数据生命周期-downsampling.period、-retentionFilter历史数据降采样、多保留期查询可观测性-search.logSlowQueryStats、-search.logSlowQueryStatsHeaders慢查询统计与日志安全与传输-mtls、-mtlsCAFile、-tlsAutocertCacheDir、-tlsAutocertEmail、-tlsAutocertHostsmTLS 双向认证、Lets Encrypt 自动证书清单中多数参数标注为array类型遵循 VictoriaMetrics 统一的数组参数约定实现见 lib/flagutil/array.go支持逗号分隔多值例如-retentionFilter{envdev}:3d -retentionFilter{envprod}:30d或单参数内用逗号分隔多个条目每个数组条目内部允许出现逗号只要逗号位于单引号/双引号字符串或{}、[]、()括号之内-mtls这类布尔型数组支持空值视为 false的写法便于与多个-httpListenAddr一一对应。许可证相关参数激活、离线校验与热更新Enterprise 二进制启动时必须提供有效许可证相关 flag 全部在 docs/victoriametrics/enterprise.md 的 Running VictoriaMetrics Enterprise 章节有完整操作说明。-license string/-licenseFile string-license直接以字符串传入 BASE64 编码的许可证密钥-licenseFile传入存放许可证密钥的文件路径。二者只能二选一。典型启动方式# 方式一内联密钥 ./victoria-metrics-prod -licenseBASE64_ENCODED_LICENSE_KEY # 方式二文件方式 ./victoria-metrics-prod -licenseFile/path/to/vm-licenseDocker 部署时可把许可证文件挂载进容器docker run --namevictoria-metrics \ -v /vm-license:/vm-license \ victoriametrics/victoria-metrics:v1.151.0-enterprise \ -licenseFile/vm-license-licenseFile.reloadInterval duration默认1h0m0s指定-licenseFile的重载间隔默认 1 小时设为非正值如0则禁用周期性重载以及 SIGHUP 触发的重载。该参数使得许可证续期时无需重启组件只要更新文件内容组件会在下一个间隔自动读取并应用新密钥Kubernetes Secret 方式挂载许可证文件时同样依赖此机制。-license.forceOffline是否对许可证启用离线校验。开启后组件不再连接 VictoriaMetrics 许可证服务器进行在线验证但前提是签发的许可证本身支持离线验证特性普通在线许可证无法用于离线模式。-eula已废弃清单中明确标注为 Deprecated应改用-license或-licenseFile。早期版本用它确认已阅读并接受 Enterprise Subscription AgreementESA。许可证过期与监控从 docs/victoriametrics/enterprise.md 的 License expiration 章节可知许可证检查仅在启动时执行运行期间过期不会中断服务组件会一直运行到下次重启若不再续期可平滑回退到开源版数据模型完全兼容仅失去 Enterprise 特性。仓库同时暴露两个监控指标便于提前告警vm_license_expires_at许可证过期时间unix 时间戳vm_license_expires_in_seconds距离过期的剩余秒数-downsampling.period array多级、按标签的降采样该参数是 Enterprise 版降低历史数据存储成本、提升历史查询性能的核心手段。完整行为说明见 docs/victoriametrics/README.md 的 Downsampling 章节。基本语法offset:interval-downsampling.period30d:5m含义对早于 30 天offset的样本每个 5 分钟interval区间只保留该区间内时间戳最大的最后一个样本其余丢弃。强制约束offset必须是interval的整数倍同一 filter 下的多个降采样周期彼此也必须是倍数关系。多级降采样通过逗号分隔或重复 flag 可对更老的数据应用更粗的粒度-downsampling.period30d:5m,180d:1h即超过 30 天的样本每 5 分钟留一个超过 180 天的样本每 1 小时留一个实现越老越粗的阶梯式存储策略。按标签过滤v1.100.0filter:offset:interval可对不同的时间序列集合配置独立的降采样-downsampling.period{__name__~(node|process)_.*}:1d:1m该配置只对名称以node_或process_开头的时间序列将超过 1 天的样本按 1 分钟粒度降采样。规则细节序列未匹配任何 filter 则完全不降采样序列匹配多个 filter 时取第一个匹配项生效注意是有序的、非取最小显式排除某类序列-downsampling.period{envprod}:0s:0s放在其他规则之前表示envprod的序列不降采样兼容性约束0s:interval或filter:0s:0s这类写法不能与-dedup.minScrapeInterval去重同时使用二者可能冲突当去重开启时-dedup.minScrapeInterval也必须是各降采样 interval 的倍数。适用性与注意事项降采样在每个时间序列上独立进行保留区间内最大时间戳样本机制与去重一致因此对**计数器counter与直方图histogram**这类单调递增指标效果最佳对 gauge/summary 会丢失区间内的变化细节可用 vmalert 录制规则或流式聚合先做 min/max/avg 等自定义聚合见 docs/victoriametrics/vmalert.md降采样在后台合并background merges期间执行磁盘空间不足或 vmstorage 处于只读模式时无法执行对每序列样本数很少但序列数巨大的高基数high churn rate场景收益有限——它不减少序列数量此时查询瓶颈主要在索引检索而非样本处理降采样会改变/api/v1/export导出结果未指定start且省略reduce_mem_usage时按最大的降采样 interval 导出修改-downsampling.period是安全的重启后新配置会在后台合并中逐步作用于历史数据。源码佐证与监控指标降采样的调度在存储层完成。lib/storage/partition.go 中维护了ScheduledDownsamplingPartitions与ScheduledDownsamplingPartitionsSize两个计数器app/vmstorage/main.go 将其暴露为 Prometheus 指标vm_downsampling_partitions_scheduled已排期降采样的分区总数vm_downsampling_partitions_scheduled_size_bytes已排期降采样分区的总大小可通过这两个指标观察降采样任务的处理进度。另外Enterprise 版 vmui 内置了Tools → Downsampling filters debug页面对应前端实现见 app/vmui/packages/vmui/src/pages/DownsamplingFilters/index.tsx可在上线前验证过滤器配置是否命中预期序列。-retentionFilter array多保留期retention filters-retentionFilter允许为不同的时间序列集合配置不同的数据保留期是-retentionPeriod全局保留之外的精细化手段详见 docs/victoriametrics/README.md 的 Retention filters 章节。语法与示例格式为filter:retention其中filter是合法的 series filter支持标签匹配表达式retention是合法的保留时长-retentionFilter{teamjuniors}:3d \ -retentionFilter{env~dev|staging}:30d \ -retentionPeriod1y含义带teamjuniors标签的序列保留3 天带envdev或envstaging标签的序列保留30 天其余序列按全局-retentionPeriod1y保留1 年。规则细节每个filter对应的retention必须小于等于-retentionPeriod序列不匹配任何 filter 时回落到全局-retentionPeriod序列匹配多个 filter 时取最小的 retention生效。重要限制与运维提示超出配置保留期的数据不会立即删除而是在后台合并过程中逐步清理-retentionFilter在全局-retentionPeriod到期前不会清除 IndexDB 中的旧索引因此高写入基数场景下即使小保留期也可能让索引膨胀参见 docs/victoriametrics/FAQ.md 关于 high churn rate 的讨论应用-retentionFilter期间资源占用会暂时上升读取、过滤、按保留期处理分区需要额外 CPU 与内存修改配置是安全的重启后新规则会逐步作用于历史数据。监控指标与降采样类似存储层暴露两个 gaugevm_retention_filters_partitions_scheduled排期处理的保留过滤分区总数vm_retention_filters_partitions_scheduled_size_bytes排期分区的总大小每次操作的开始与完成都会向日志写入一条包含 filter 表达式与分区名的记录便于追踪。Enterprise vmui 同样提供Tools → Retention filters debug调试页见 app/vmui/packages/vmui/src/pages/RetentionFilters/index.tsx用于上线前校验。慢查询统计-search.logSlowQueryStats与-search.logSlowQueryStatsHeaders这两个参数控制 Enterprise 版的查询执行统计日志配套的完整日志字段与分析方法见 docs/victoriametrics/query-stats.md。阈值语义-search.logSlowQueryStats duration默认5s对通过/api/v1/query与/api/v1/query_range执行的读取查询记录统计信息-search.logSlowQueryStats5s仅记录执行超过 5 秒的查询默认行为v1.129.0 起默认开启-search.logSlowQueryStats1us记录所有查询阈值设为极小值-search.logSlowQueryStats0完全关闭统计。请求头字段记录-search.logSlowQueryStatsHeaders array指定对超阈值查询额外记录哪些 HTTP 请求头如-search.logSlowQueryStatsHeadersX-Scope-OrgID,X-Tenant-ID大小写不敏感默认不记录任何请求头。这对于在多租户或网关场景下按来源定位慢查询非常有用。日志字段与典型输出每条日志以vm_slow_query_stats前缀标记、logfmt 格式输出便于机器解析。字段包括typeinstant/range、queryMetricsQL 原文、query_hash、start_ms/end_ms/step_ms、range_ms、tenant仅集群版、execution_duration_ms不含网络传输时间、series_fetched、samples_fetched、bytes、memory_estimated_bytes以及-search.logSlowQueryStatsHeaders中列出的headers.*键值对v1.121.0。基于 VictoriaLogs 的分析方法官方推荐把慢查询日志采集进 VictoriaLogs 后做聚合分析配置参考 deployment/docker/prometheus-vm-single.yml 的日志采集链路。例如找出执行最慢的 5 条查询vm_slow_query_stats | extract vm_slow_query_stats query_stats | unpack_logfmt from query_stats | stats by(query) max(execution_duration_ms) execution_duration_max | sort by(execution_duration_max) desc | limit 5也可按query,query_hash聚合series_fetched之和识别扫描数据量大的查询。官方还提供了开箱即用的查询统计 Grafana 仪表盘 dashboards/query-stats.jsonmTLS 双向认证-mtls与-mtlsCAFile-mtls array布尔数组决定对对应位置的-httpListenAddr是否强制要求有效的客户端证书-mtlsCAFile array字符串数组则为对应监听地址指定用于校验客户端证书的 TLS Root CA。二者均只在-tls开启时生效并按数组下标与多个-httpListenAddr一一对应。完整说明见 docs/victoriametrics/README.md 的 mTLS protection 章节。最简启用方式./victoria-metrics -tls -mtls默认使用系统级 TLS Root CA校验客户端证书需要自建 CA 时用-mtlsCAFile指定自定义 CA 文件-mtlsCAFile/path/to/ca.crt相关实现位于 lib/httpserver/httpserver.go其中-tls参数还支持证书文件每秒自动重读实现证书的热更新详见-tlsCertFile/-tlsKeyFile的说明。在集群版中 mTLS 还覆盖组件间通信与 vmauth 的 mTLS 路由见 docs/victoriametrics/vmauth.md配合各端点的*AuthKey鉴权参数-deleteAuthKey、-snapshotAuthKey、-configAuthKey等见 docs/victoriametrics/README.md 的 Security 章节可构建完整的传输层与接口层安全体系。Lets Encrypt 自动证书-tlsAutocertHosts/-tlsAutocertEmail/-tlsAutocertCacheDir三个参数配合实现面向公网的 HTTPS 监听地址自动签发 Lets Encrypt 证书免去手动维护证书的负担见 docs/victoriametrics/README.md 的 Automatic issuing of TLS certificates 章节。启用自动签发需同时满足-httpListenAddr监听TCP 443 端口例如-httpListenAddr:443且该端口必须能被 Lets Encrypt 服务访问-tls开启 HTTPS 接受能力此时不需要再设置-tlsCertFile/-tlsKeyFile-tlsAutocertHosts逗号分隔的域名列表组件为这些域名自动签发证书域名需能通过-httpListenAddr访问到-tlsAutocertEmail证书签发的联系邮箱Lets Encrypt 必需-tlsAutocertCacheDir证书持久化目录。若未设置证书在每次重启后会丢失并重新签发设置后可跨重启复用避免频繁触达 Lets Encrypt 的签发限额。示例./victoria-metrics -httpListenAddr:443 -tls \ -tlsAutocertHostsmetrics.example.com \ -tlsAutocertEmailadminexample.com \ -tlsAutocertCacheDir/var/lib/vm-tls-cache结语-downsampling.period与-retentionFilter共同构成 Enterprise 版的数据生命周期精细化控制能力——前者压缩历史数据密度、后者按标签差异化保留-search.logSlowQueryStats系列让慢查询可观测、可聚合、可治理-mtls/-tlsAutocert*则补齐了传输安全与证书自动化短板。所有参数的权威定义以 docs/victoriametrics/victoria_metrics_enterprise_flags.md 为准其内容随发布流程由实际二进制自动同步集群版各组件vmselect、vmstorage、vminsert、vmagent、vmalert 等的对应行为可在 docs/victoriametrics/Cluster-VictoriaMetrics.md 与各组件文档中进一步确认。需要评估这些能力时可下载 Enterprise 二进制并申请试用许可证验证。【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考