云原生【免费下载链接】kubevirtKubernetes Virtualization API and runtime in order to define and manage virtual machines.项目地址https://gitcode.com/gh_mirrors/ku/kubevirt点击查看免费下载导读本指南以 docs/observability/monitoring-guidelines.md 为骨架系统讲解 KubeVirt 可观测性体系Metrics、Prometheus Recording Rules、Alerting Rules的兼容性策略、命名规范与开发流程。无论你是要新增一个 VM 指标、设计一条集群级记录规则还是编写一条带 runbook 的告警规则都能在本指南中找到必须遵守的规则与可直接照抄的代码示例。读完本文你将掌握如何让新信号与 Kubernetes 生态对齐、如何优雅地弃用旧信号以及如何通过源码级验证与 CI 工具链保证规则正确。KubeVirt 可观测性兼容性策略KubeVirt 的监控体系覆盖三类可观测性信号指标metrics含其名称、标签集和类型、Prometheus 记录规则recording rules与告警规则alerting rules。除非明确声明否则这些信号一律被视为实现细节随时可能变更。这与 Kubernetes 官方监控实践保持一致——监控信号面向运维消费而不是面向 API 兼容性契约。稳定性约定KubeVirt不保证可观测性信号具备长期向后兼容。名称、标签、类型与语义都可能随版本更新而变化其目的可能是修正正确性、提升性能或改善可运维性。因此任何依赖 KubeVirt 指标的自动化系统都应将信号视作易变输入而非稳定契约。弃用流程当信号被重命名或移除时KubeVirt 会在可行范围内按以下顺序执行弃用流程在文档中把旧名称标记为Deprecated例如 docs/observability/metrics.md 中大量[Deprecated]条目可选地提供短期的兼容性记录规则别名将新信号映射回旧名称在条件允许时弃用信号至少保留一个 minor 版本仅在安全、正确性或可扩展性等例外场景下允许不经过弃用窗口直接变更。以记录规则为例pkg/monitoring/rules/recordingrules/deprecated_recordingrules.go 集中定义了所有弃用规则——它们本质上是新规则的别名// All deprecated recording rules centralized here, aliasing the new names var deprecatedRecordingRules []operatorrules.RecordingRule{ // Nodes { MetricsOpts: operatormetrics.MetricOpts{ Name: kubevirt_allocatable_nodes, Help: [Deprecated] Replaced by cluster:kubevirt_nodes_allocatable:count., }, MetricType: operatormetrics.GaugeType, Expr: intstr.FromString(cluster:kubevirt_nodes_allocatable:count), }, // ... }这段代码展示了短寿命兼容别名的完整实现方式Expr直接引用新规则名Help明确标注被哪个新信号替代用户只需升级查询语句即可平滑迁移。沟通机制重要变更会通过以下渠道同步写入版本发布说明release notes反映在 docs/observability/metrics.md 中告警与规则的更新同步体现在 PR 描述中供审查者与下游消费者知悉。消费者指引对于使用 KubeVirt 监控信号构建 Dashboard 与告警的团队官方给出两条硬性建议编写 PromQL 时预期标签集会变化不要依赖穷举或固定标签集选择、连接、分组时只使用所需的最小标签集合。例如能用sum by (namespace)(...)就不要写sum by (namespace,pod,container,instance)(...)——标签越少查询对上游信号变更的鲁棒性越强把弃用信号视为临时过渡一旦发现使用的信号被打上Deprecated标记应尽快迁移到替代信号不要长期停留在别名上。贡献者义务新增或修改可观测性信号的贡献者需要同时完成更新对应文档评估是否值得提供临时兼容规则在 PR 描述与发布说明中包含迁移说明。KubeVirt 指标Metrics命名规范与 Kubernetes 指标对齐KubeVirt 指标命名遵循一个基本原则与 Kubernetes 自身指标命名保持一致。这样用户在检索节点node、容器container、Pod 与虚拟机VM指标时能够获得完全一致的检索体验——看到*_network_receive_packets_total就知道是网络收包计数无论前缀是node_、container_还是kubevirt_vmi_。两条硬性命名要求先查证新增指标前先确认 Kubernetes 中是否存在针对 node、container 或 pod 的同类指标并尽量对齐其命名VMI 前缀表示运行中虚拟机VirtualMachineInstanceVMI的 KubeVirt 指标必须使用kubevirt_vmi_前缀。原文给出的对照示例非常直观。Kubernetes 网络指标node_network_receive_packets_totalnode_network_transmit_packets_totalcontainer_network_receive_packets_totalcontainer_network_transmit_packets_total对应的 KubeVirt VMI 指标kubevirt_vmi_network_receive_packets_totalkubevirt_vmi_network_transmit_packets_total源码级印证指标的真实定义位置上述命名规则并非纸上谈兵而是确实落实在源码中。pkg/monitoring/metrics/virt-handler/domainstats/network_metrics.go 中通过operatormetrics.NewCounter定义了收发字节、收发包、收发错误、收发丢包等一整套网络指标networkReceivePackets operatormetrics.NewCounter( operatormetrics.MetricOpts{ Name: kubevirt_vmi_network_receive_packets_total, Help: Total network traffic received packets., }, ) networkTransmitPackets operatormetrics.NewCounter( operatormetrics.MetricOpts{ Name: kubevirt_vmi_network_transmit_packets_total, Help: Total network traffic transmitted packets., }, )对应的单元测试 pkg/monitoring/metrics/virt-handler/domainstats/network_metrics_test.go 逐条校验了每个指标的采集值收包计数值为 3、发包计数值为 4并验证了当统计未填充或NameSet为 false 时收集结果为空。这表明命名规范直接决定了采集器的数据结构与测试预期。指标类型速览从 docs/observability/metrics.md 中可以看到 KubeVirt 指标使用的 Prometheus 类型主要有四类类型语义典型示例Gauge当前值快照可增可减kubevirt_vmi_memory_available_bytes、kubevirt_vm_infoCounter只增不减的累计值kubevirt_vmi_network_receive_packets_total、kubevirt_vmi_sync_totalHistogram观测值分布统计kubevirt_vmi_phase_transition_time_seconds、kubevirt_rest_client_request_latency_secondsRecording rule由规则计算出的派生指标cluster:kubevirt_nodes_allocatable:countKubeVirt 记录规则Recording Rules命名规范Prometheus 记录规则计算出的结果在 Prometheus 中同样以指标形式呈现因此命名需要同时遵循两层约束格式约束遵循 Prometheus 命名最佳实践采用level:metric:operation三段式结构其中level表示聚合级别operation表示执行的运算前缀约束为了让 KubeVirt 记录规则易于识别metric部分必须包含kubevirt_前缀。对照 docs/observability/metrics.md 中实际的记录规则清单可以直观看到规范落地后的效果记录规则名称level说明cluster:kubevirt_nodes_allocatable:countcluster集群中可分配节点数cluster:kubevirt_non_schedulable_nodes:sumcluster集群中不可调度节点数node:kubevirt_vmi_phase:sumnode按节点与 phase 统计 VMI 数量namespace:kubevirt_vm:sumnamespace按命名空间统计 VM 数量vmi:kubevirt_vmi_memory_used_bytes:sumvmiVMI 视角的已用内存container:kubevirt_memory_delta_from_requested_bytes:maxcontainer容器实际占用与请求内存的差值以 pkg/monitoring/rules/recordingrules/vmi.go 中的实现为例记录规则通过operatorrules.RecordingRule结构定义MetricOpts.Name即规则最终暴露的指标名Expr为 PromQL 表达式var vmiRecordingRules []operatorrules.RecordingRule{ { MetricsOpts: operatormetrics.MetricOpts{ Name: node:kubevirt_vmi_phase:sum, Help: Sum of VMIs per phase and node. phase can be one of the following: [Pending, Scheduling, Scheduled, Running, Succeeded, Failed, Unknown]., }, MetricType: operatormetrics.GaugeType, Expr: intstr.FromString( sum by (node, phase, os, workload, flavor, instance_type, preference, guest_os_kernel_release, guest_os_machine, guest_os_arch, guest_os_name, guest_os_version_id) (kubevirt_vmi_info), ), }, // ... }注意Help字段还同步说明了该规则暴露的标签维度如phase的合法取值这与文档化的指标描述保持一致方便下游用户直接消费。KubeVirt 告警规则Alerting Rules规范创建一条 KubeVirt 告警规则时必须依次满足以下五点要求1. 计算优先使用记录规则凡是涉及聚合、比率、增量等计算的表达式应优先封装为记录规则再在告警表达式中引用。这样既能避免在每条告警中重复复杂计算也能让计算逻辑可被测试、可被复用。例如 pkg/monitoring/rules/alerts/vms.go 中的KubeVirtVMGuestMemoryPressure告警直接引用了vmi:kubevirt_vmi_memory_headroom_ratio:sum、vmi:kubevirt_vmi_pgmajfaults:rate5m、vmi:kubevirt_vmi_swap_traffic_bytes:rate5m等预计算好的记录规则。2. 为告警编写 runbook每条告警都必须配套一份 runbook故障处理手册说明该告警的含义、排查路径与修复手段。KubeVirt 的告警注册代码 pkg/monitoring/rules/alerts/alerts.go 会自动为每条规则注入runbook_url注解模板默认为prometheusRunbookAnnotationKey runbook_url defaultRunbookURLTemplate https://kubevirt.io/monitoring/runbooks/%s runbookURLTemplateEnv RUNBOOK_URL_TEMPLATE即最终注解形如runbook_url: https://kubevirt.io/monitoring/runbooks/AlertName且可以通过环境变量RUNBOOK_URL_TEMPLATE覆盖模板。模板字符串必须恰好包含一个%s占位符否则注册时直接 panic——这是保证每条告警都能链接到对应 runbook 的强制约束。3. 必须包含severity标签每条告警规则必须设置severity取值限定为三档severity含义触发场景critical立即处理服务宕机、核心功能丧失必须马上采取行动。例GuestFilesystemAlmostOutOfSpace使用率 ≥ 95%、VMNonRecoverableOSPanic24h 内发生 5 次以上不可恢复 Guest OS panicwarning需要人工介入若不尽快解决可能演变为更严重的问题。例VMCannotBeEvicted、KubeVirtVMIExcessiveMigrations、文件系统使用率 ≥ 85%info需要尽快处理但不紧急已检测到次要问题。例KubeVirtVMGuestMemoryAvailableLow可用内存低于 3% 且无 swap 流量在源码层面severity通过统一的标签键常量severityAlertLabelKey severity注入例如 pkg/monitoring/rules/alerts/vms.go 中的{ Alert: VMCannotBeEvicted, Expr: intstr.FromString(withVMLabel( kubevirt_vmi_non_evictable * on(name, namespace) group_left() topk by(name, namespace) (1, kubevirt_vmi_info{phaserunning}) 1, )), For: ptr.To(promv1.Duration(1m)), Annotations: map[string]string{ descriptionAnnotationKey: Eviction policy for VirtualMachine {{ $labels.name }} in namespace {{ $labels.namespace }} (on node {{ $labels.node }}) is set to Live Migration but the VM is not migratable, summaryAnnotationKey: The VMs eviction strategy is set to Live Migration but the VM is not migratable, }, Labels: map[string]string{ severityAlertLabelKey: warning, operatorHealthImpactLabelKey: none, }, },此外注册阶段alerts.go还会自动补充kubernetes_operator_part_ofkubevirt、kubernetes_operator_componentkubevirt标签并为控制面组件的告警注入安装命名空间标签便于按组件归集。4.message/description必须详细告警消息必须足够详细verbose因为它在执行make-generate时会被传播到 docs/observability/metrics.md 文档中。以 pkg/monitoring/rules/alerts/vms.go 的GuestFilesystemAlmostOutOfSpace为例描述中既包含命名的 VMI、命名空间、文件系统与挂载点标签还带出当前使用率{{ $value }}%确保页面与告警通知都能定位到具体对象。5. 一组可直接参考的完整告警样例如需快速理解规范齐备的告警长什么样可直接研读 pkg/monitoring/rules/alerts/vms.go。该文件包含VMCannotBeEvicted、KubeVirtVMIExcessiveMigrations、OutdatedVirtualMachineInstanceWorkloads、GuestVCPUQueueHighWarning、GuestVCPUQueueHighCritical、VirtualMachineStuckInUnhealthyState、KubeVirtVMGuestMemoryPressure、GuestFilesystemAlmostOutOfSpacewarning/critical 双阈值、KubeVirtVMGuestMemoryAvailableLow、VMNonRecoverableOSPanic等十余条告警覆盖 VM 驱逐、迁移风暴、陈旧工作负载、vCPU 队列、内存压力、文件系统空间与 Guest OS panic 等典型场景每条都完整携带severity、summary、description与自动注入的runbook_url。规则的注册、打包与 CI 验证规则的统一注册入口所有记录规则与告警规则都通过 pkg/monitoring/rules/rules.go 统一注册与打包func SetupRules(namespace string) error { err : recordingrules.Register(registry, namespace) // ... err alerts.Register(registry, namespace) // ... } func BuildPrometheusRule(namespace string) (*promv1.PrometheusRule, error) { rules, err : registry.BuildPrometheusRule( kubevirtPrometheusRuleName, // prometheus-kubevirt-rules namespace, map[string]string{ prometheusLabelKey: prometheusLabelValue, // prometheus.kubevirt.iotrue k8sAppLabelKey: kubevirtLabelValue, // k8s-appkubevirt }, ) // ... }recordingrules.Registerpkg/monitoring/rules/recordingrules/recordingrules.go按 api、gpu、nodes、operator、virt、vm、vmi、vmsnapshot、pvc 与 deprecated 分组注册全部记录规则alerts.Register则汇总 system、virt-api、virt-controller、virt-handler、virt-operator 与 VM 负载告警。最终产出一个名为prometheus-kubevirt-rules的PrometheusRuleCR 对象供 Prometheus Operator 加载。用 promtool 做规则验证CI 闭环规则的语法与语义正确性由 CI 脚本保证。hack/prom-rule-ci/rule-spec-dumper.go 负责调用rules.SetupRules(ci)与rules.BuildPrometheusRule(ci)把生成的PrometheusRule.Spec序列化为 JSON 文件随后 hack/prom-rule-ci/verify-rules.sh 使用官方 Prometheus 镜像中的promtool执行两类检查# 语法检查校验规则文件格式与表达式合法性 promtool check rules /tmp/rules.verify # 单元测试依据 prom-rules-tests.yaml 中的断言执行 PromQL 求值 promtool test rules /tmp/rules.test其中单元测试用例定义在 hack/prom-rule-ci/prom-rules-tests.yaml。也就是说你在源码中每新增一条规则CI 都会自动完成规则生成 → 语法检查 → 表达式单元测试的全链路验证无需手动维护 YAML 规则文件。指标文档的自动生成与同步metrics.md 中的全部指标Metric、记录规则Recording rule表格都是自动生成的精确反映当前暴露的信号集合。文档末尾明确说明All metrics documented here are auto-generated and reflect exactly what is being exposed. After developing new metrics or changing old ones please regenerate this document.因此工作流是在pkg/monitoring/metrics/指标定义或pkg/monitoring/rules/记录规则与告警规则中修改源码运行make-generate重新生成 docs/observability/metrics.md更新相关的 runbook 与发布说明通过 CI 的 promtool 校验后合入。这样既保证命名规范在代码、文档、测试三个层面完全一致也让下游消费者始终能拿到一份与真实采集面完全同步的信号清单。总结新增一条监控信号的完整检查清单无论新增指标、记录规则还是告警规则请按以下清单逐项自检命名对齐kubevirt_vmi_前缀VMI 指标记录规则使用level:metric:operation格式且metric含kubevirt_与 Kubernetes 对齐优先对照 node/container/pod 层同名指标标签最小化PromQL 只 select、join、group 必要标签不依赖穷举标签集告警三件套severitycritical/warning/inforunbook_url自动注入 详细的summary/description计算下沉复杂计算封装为记录规则后再被告警引用弃用合规改名或删除时标注[Deprecated]、评估临时别名规则、保留至少一个 minor 版本文档同步运行make-generate刷新 docs/observability/metrics.md并在 PR 描述与发布说明中写明迁移路径CI 验证确保新规则通过 hack/prom-rule-ci/verify-rules.sh 的promtool check rules与promtool test rules。遵循以上规范你的新监控信号将与 KubeVirt 既有体系无缝融合并为集群运维人员提供与 Kubernetes 一致的查询体验。赞分享云原生【免费下载链接】kubevirtKubernetes Virtualization API and runtime in order to define and manage virtual machines.项目地址https://gitcode.com/gh_mirrors/ku/kubevirt点击查看免费下载相关推荐3分钟掌握unrpa轻松提取RenPy游戏资源的终极工具指南3分钟掌握unrpa轻松提取RenPy游戏资源的终极工具指南 你是否玩过RenPy引擎开发的视觉小说游戏想要提取里面的精美图片、动听音乐或有趣脚本un开发工具Screenshot-to-code容器编排监控Prometheus指标与告警规则Screenshot to code容器编排监控Prometheus指标与告警规则 一、监控体系构建背景 Screenshot to code作为截图转代码的示例工程Kibana监控告警自定义告警规则开发Kibana监控告警自定义告警规则开发 在日常运维中你是否还在为无法及时发现系统异常而烦恼是否希望能够根据业务需求灵活定制告警规则本文将带你一步步掌握K前端数据可视化数据分析后端可观测性上一篇Video2X免费AI视频增强实操3条命令让模糊老视频升级成高清流畅影片下一篇植物大战僵尸修改器怎么用新手5分钟上手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考