Longhorn Upgrade Checker 信息采集机制：`Allow Collecting Longhorn Usage Metrics` 设置与 extraInfo 指标格式全解析

• 云原生
• 存储
• 高可用
• 容器编排

Longhorn 的 Upgrade Checker（升级检查器）除了在发现新版本时于 UI 弹出升级提示外，还承担着向官方升级应答服务器上报匿名使用数据、支撑 Longhorn 公共指标看板（metrics.longhorn.io）的职责。本文以仓库中的增强提案 20230420-upgrade-checker-info-collection.md 为核心，系统讲解新增的Allow Collecting Longhorn Usage Metrics设置、extraInfo扩展后采集的节点与集群指标清单、设置采集的排除与转换规则、完整的数据格式示例，并结合 Helm Chart 配置说明如何启用、覆盖或关闭该采集能力。

背景与动机：升级检查背后的数据价值

Longhorn 官方维护的公共指标看板（metrics.longhorn.io）向公众展示 Longhorn 被实际使用的概况，这类信息对两类人群有直接价值：

• 新用户与计划升级的用户：可以据此了解主流用户群体采用的 Longhorn 与 Kubernetes 版本组合，为自身的版本选型与升级路径提供参考；
• Longhorn 开发团队：借此了解真实世界的使用模式，为功能改进与发展方向决策提供数据支撑。

为了让使用模式的分析更加深入，增强提案提出在升级检查时收集更多关于**卷（volumes）、宿主机系统（host systems）与功能特性（features）**的信息，并明确了两个目标（Goals）：

1. 在升级检查期间扩展对用户集群信息的采集范围；
2. 提供一个新的设置项，让用户可以选择启用或关闭该采集能力。

该提案不涉及任何 API 变更（API changes 为None），升级策略（Upgrade strategy）同样为None，属于完全向后兼容的能力增强。

总体方案：新设置 +extraInfo扩展

整个方案由两个相互配合的部分组成：

1. 扩展extraInfo采集内容：在原有 Upgrade Checker 上报的extraInfo基础上，新增节点信息（Node Info）与集群信息（Cluster Info）两类指标，并通过 upgrade responder 请求发送至服务端；
2. 新增Allow Collecting Longhorn Usage Metrics设置：作为采集的总开关。若该值被设置为false，则不再采集任何额外信息（extra information）。

用户既可以在 Longhorn 公共指标看板上查看 Longhorn 的整体使用情况，也可以随时关闭本集群的数据采集，确保隐私可控。

Allow Collecting Longhorn Usage Metrics设置详解

设置定义

该设置在提案中给出的完整定义如下：

从定义可以看出，该设置默认启用，即默认情况下 Longhorn 会采集并上报上述额外信息；同时它是布尔类型且可写，用户可以自由地将其改为false来完全关闭额外信息采集。

在 Helm Chart 中的体现与覆盖方式

在仓库的 Helm Chart 中，该设置通过defaultSettings.allowCollectingLonghornUsageMetrics暴露，位于 chart/values.yaml，其注释说明了用途：

Setting that allows Longhorn to periodically collect anonymous usage data for product improvement purposes. Longhorn sends collected data to the Upgrade Responder server, which is the data source of the Longhorn Public Metrics Dashboard (metrics.longhorn.io). The Upgrade Responder server does not store data that can be used to identify clients, including IP addresses.

这里补充了三个关键事实：

• 采集是**周期性（periodically）**进行的匿名使用数据上报；
• 数据发送至Upgrade Responder服务器，它是 Longhorn 公共指标看板的数据源；
• 服务器不会存储可用于识别客户端身份的数据（包括 IP 地址），从机制上保证了匿名性。

Chart 中该值的默认状态为~（即未显式指定），表示由 Longhorn Manager 侧的内置默认值（"true"）生效。当用户在 Helm values 中显式赋值后，chart/templates/default-setting.yaml 会通过kindIs "invalid"判断，仅在值为非空时才向默认设置 ConfigMap 注入对应键：

{{- if not (kindIs "invalid" .Values.defaultSettings.allowCollectingLonghornUsageMetrics) }} allow-collecting-longhorn-usage-metrics: {{ .Values.defaultSettings.allowCollectingLonghornUsageMetrics }}

同时 chart/questions.yaml 提供了对应的 UI 表单变量，使用户在通过 Rancher 等图形界面部署 Longhorn 时也能直接配置该选项。需要说明的是，该设置在早期 Helm Chart 中一度缺失，仓库的 CHANGELOG-1.6.0.md 与 CHANGELOG-1.5.4.md 分别记录了 "allow-collecting-longhorn-usage-metricssetting is missing from chart settings" 的修复，即后续版本已将该设置补入 Chart，安装时即可通过 values 控制。

通过 UI 或 kubectl 配置

与 Longhorn 其他设置一样，该设置也可以在运行时通过两种方式调整：

• Longhorn UI：进入「Setting」页面，找到Allow Collecting Longhorn Usage Metrics项，切换开关后保存即可；
• kubectl：Longhorn 的所有设置都以settings.longhorn.io自定义资源存在，可以推断使用以下命令编辑：

kubectl -n longhorn-system edit settings.longhorn.io allow-collecting-longhorn-usage-metrics

将value字段改为"false"并保存后，采集即被关闭，之后 Upgrade Checker 上报时将不再携带额外信息。

extraInfo采集内容详解

提案将采集内容划分为两大类别：节点信息与集群信息。其中节点信息由每个集群节点分别上报，集群信息则由集群中的某一个节点汇总上报。

节点信息（Node Info）

以下信息从每个集群节点发送：

其中磁盘类型计数存在一个需要特别注意的边界：提案明确备注"该值在集群节点为虚拟机时可能不准确"（this value may not be accurate if the cluster node is a virtual machine）。这是因为磁盘类型判定依赖设备的底层特性，虚拟化环境下设备类型往往被抽象或透传，统计结果可能偏离物理真实值，解读数据时应结合节点形态综合判断。

集群信息（Cluster Info）

以下信息从集群中的某一个节点发送（即全局汇总数据）：

设置的采集规则

设置类指标longhorn_setting_<name>并非全部照搬，而是分为三类处理：

1. 排除清单（Settings to exclude）：以下设置不采集，多数涉及镜像地址、凭据、路径、版本信息等敏感或冗余内容：

排除BackupTargetCredentialSecret显然是出于安全考虑——它包含备份目标凭据，绝不能外泄；排除默认镜像/版本类设置则是因为它们可从其他渠道获得且变化频繁。

2. 需要转换处理的设置：个别设置需要加工后才能体现其一般用途，典型代表是SettingNameBackupTarget——采集时转换为备份目标的类型/协议（如cifs、nfs、s3），而不是原始 URL 或完整配置。

3. 布尔化采集的设置：以下设置以布尔值采集（true表示已配置，false表示未配置），避免暴露具体配置内容：

其余设置则按原样（as it is）采集。

这套规则的设计意图非常清晰：排除敏感与冗余信息，收敛高敏配置为布尔标记，兼顾统计价值与用户隐私。

完整数据示例：upgrade_request 记录解析

提案给出了启用采集后 upgrade responder 数据库中upgrade_request表的实际记录示例（节选自 enhancements/20230420-upgrade-checker-info-collection.md）：

name: upgrade_request time app_version host_kernel_release host_os_distro kubernetes_node_provider kubernetes_version longhorn_engine_image_average_cpu_usage_core longhorn_engine_image_average_memory_usage_mib longhorn_instance_manager_average_cpu_usage_core longhorn_instance_manager_average_memory_usage_mib longhorn_manager_average_cpu_usage_core longhorn_manager_average_memory_usage_mib longhorn_namespace_uid longhorn_node_count longhorn_node_disk_nvme_count longhorn_setting_allow_node_drain_with_last_healthy_replica longhorn_setting_allow_recurring_job_while_volume_detached longhorn_setting_allow_volume_creation_with_degraded_availability longhorn_setting_auto_cleanup_system_generated_snapshot longhorn_setting_auto_delete_pod_when_volume_detached_unexpectedly longhorn_setting_auto_salvage longhorn_setting_backing_image_cleanup_wait_interval longhorn_setting_backing_image_recovery_wait_interval longhorn_setting_backup_compression_method longhorn_setting_backup_concurrent_limit longhorn_setting_backup_target longhorn_setting_backupstore_poll_interval longhorn_setting_concurrent_automatic_engine_upgrade_per_node_limit longhorn_setting_concurrent_replica_rebuild_per_node_limit longhorn_setting_concurrent_volume_backup_restore_per_node_limit longhorn_setting_crd_api_version longhorn_setting_create_default_disk_labeled_nodes longhorn_setting_default_data_locality longhorn_setting_default_replica_count longhorn_setting_disable_revision_counter longhorn_setting_disable_scheduling_on_cordoned_node longhorn_setting_engine_replica_timeout longhorn_setting_failed_backup_ttl longhorn_setting_fast_replica_rebuild_enabled longhorn_setting_guaranteed_engine_manager_cpu longhorn_setting_guaranteed_instance_manager_cpu longhorn_setting_guaranteed_replica_manager_cpu longhorn_setting_kubernetes_cluster_autoscaler_enabled longhorn_setting_node_down_pod_deletion_policy longhorn_setting_node_drain_policy longhorn_setting_orphan_auto_deletion longhorn_setting_priority_class longhorn_setting_recurring_failed_jobs_history_limit longhorn_setting_recurring_successful_jobs_history_limit longhorn_setting_registry_secret longhorn_setting_remove_snapshots_during_filesystem_trim longhorn_setting_replica_auto_balance longhorn_setting_replica_file_sync_http_client_timeout longhorn_setting_replica_replenishment_wait_interval longhorn_setting_replica_soft_anti_affinity longhorn_setting_replica_zone_soft_anti_affinity longhorn_setting_restore_concurrent_limit longhorn_setting_restore_volume_recurring_jobs longhorn_setting_snapshot_data_integrity longhorn_setting_snapshot_data_integrity_cronjob longhorn_setting_snapshot_data_integrity_immediate_check_after_snapshot_creation longhorn_setting_storage_minimal_available_percentage longhorn_setting_storage_network longhorn_setting_storage_over_provisioning_percentage longhorn_setting_storage_reserved_percentage_for_default_disk longhorn_setting_support_bundle_failed_history_limit longhorn_setting_system_managed_components_node_selector longhorn_setting_system_managed_pods_image_pull_policy longhorn_setting_taint_toleration longhorn_ui_average_cpu_usage_core longhorn_ui_average_memory_usage_mib longhorn_volume_access_mode_rwo_count longhorn_volume_average_actual_size longhorn_volume_average_number_of_replicas longhorn_volume_average_size longhorn_volume_average_snapshot_count longhorn_volume_data_locality_disabled_count longhorn_volume_frontend_blockdev_count value ---- ----------- ------------------- -------------- ------------------------ ------------------ -------------------------------------------- ---------------------------------------------- ------------------------------------------------ -------------------------------------------------- --------------------------------------- ----------------------------------------- ---------------------- ------------------- ----------------------------- ----------------------------------------------------------- ---------------------------------------------------------- ----------------------------------------------------------------- ------------------------------------------------------- ------------------------------------------------------------------ ----------------------------- ---------------------------------------------------- ----------------------------------------------------- ------------------------------------------ ---------------------------------------- ------------------------------ ------------------------------------------ ------------------------------------------------------------------- ---------------------------------------------------------- ---------------------------------------------------------------- -------------------------------- -------------------------------------------------- -------------------------------------- -------------------------------------- ----------------------------------------- ---------------------------------------------------- --------------------------------------- ---------------------------------- --------------------------------------------- ---------------------------------------------- ------------------------------------------------ ----------------------------------------------- ------------------------------------------------------ ---------------------------------------------- ---------------------------------- ------------------------------------- ------------------------------- ---------------------------------------------------- -------------------------------------------------------- -------------------------------- -------------------------------------------------------- ------------------------------------- ------------------------------------------------------ ---------------------------------------------------- ------------------------------------------- ------------------------------------------------ ----------------------------------------- ---------------------------------------------- ---------------------------------------- ------------------------------------------------ -------------------------------------------------------------------------------- ----------------------------------------------------- -------------------------------- ----------------------------------------------------- ------------------------------------------------------------- ---------------------------------------------------- -------------------------------------------------------- ------------------------------------------------------ --------------------------------- ---------------------------------- ------------------------------------ ------------------------------------- ----------------------------------- ------------------------------------------ ---------------------------- -------------------------------------- -------------------------------------------- --------------------------------------- ----- 1683598256887331729 v1.5.0-dev 5.3.18-59.37-default "sles" k3s v1.23.15+k3s1 5m 11 4m 83 22m 85 1b96b299-b785-468b-ab80-b5b5b12fbe00 3 1 false false true true true true 60 300 lz4 5 none 300 0 5 5 longhorn.io/v1beta2 false disabled 3 false true 8 1440 true 12 12 12 false do-nothing block-if-contains-last-replica false false 1 1 false false disabled 30 600 false true 5 false fast-check 0 0 */7 * * false 25 false 200 30 1 false if-not-present false 0 4 3 79816021 2 8589934592 0 3 3 1 1683598257082240493 v1.5.0-dev 5.3.18-59.37-default "sles" k3s v1.23.15+k3s1 1 1 1683598257825718008 v1.5.0-dev 5.3.18-59.37-default "sles" k3s v1.23.15+k3s1 1 1

对该示例数据的解读要点如下：

• 时间戳与版本：每条记录以毫秒级时间戳为主键，app_version为 Longhorn 版本（示例为v1.5.0-dev开发版）；
• 节点信息字段：host_kernel_release=5.3.18-59.37-default、host_os_distro="sles"、kubernetes_node_provider=k3s，与前述 Node Info 清单一一对应；
• 组件资源使用：longhorn_manager_average_cpu_usage_core=22m（约 0.022 核）、longhorn_ui_average_memory_usage_mib=85（约 85 MiB）等，展示各组件平均资源占用的量纲；
• 卷维度统计：longhorn_volume_access_mode_rwo_count=3、longhorn_volume_average_size=8589934592（8 GiB 字节数）、longhorn_volume_average_number_of_replicas=3等；
• 设置字段：longhorn_setting_backup_target=none（对应"无备份目标"）、longhorn_setting_backup_compression_method=lz4、longhorn_setting_snapshot_data_integrity=fast-check、longhorn_setting_crd_api_version=longhorn.io/v1beta2等，注意backup_target已按规则转换为协议/类型而非完整 URL；
• 关键隐私设计：后两条记录（同一集群的后续上报）仅保留了少量字段与longhorn_namespace_uid，且该 UID 为随机 UUID（1b96b299-b785-468b-ab80-b5b5b12fbe00），用于跨记录关联同一集群而不暴露可识别身份的信息。

数据流与 Upgrade Responder 部署

采集到的数据由 Longhorn Manager 的 Upgrade Checker 周期性发送至 Upgrade Responder 服务器（默认端点https://longhorn-upgrade-responder.rancher.io/v1/checkupgrade，可通过defaultSettings.upgradeResponderURL覆盖，见 chart/values.yaml）。服务端将请求写入 InfluxDB 数据库，由 Grafana 渲染为 Longhorn 公共指标看板。

若需自建 Upgrade Responder 服务端进行验证，仓库提供了两条路径：

• 手动部署：参考 dev/upgrade-responder/README.md，在安装 Longhorn 后执行./install.sh，脚本会依次部署 InfluxDB（数据库longhorn_upgrade_responder）、Grafana 以及 Upgrade Responder Helm Release（longhorn-upgrade-responder），并输出 Upgrade Checker 使用的服务端 URL：

  [Upgrade Checker] URL : http://longhorn-upgrade-responder.default.svc.cluster.local:8314/v1/checkupgrade [InfluxDB] URL : http://influxdb.default.svc.cluster.local:8086 Database : longhorn_upgrade_responder Username : root Password : root [Grafana] Dashboard : http://1.2.3.4:30864 Username : admin Password : admin

  部署完成后可通过kubectl port-forward将 8314 端口映射到本机（kubectl port-forward $POD_NAME 8080:8314），即可获得本地可达的升级检查端点。

• 官方 Chart 配置：deploy/upgrade_responder_server/chart-values.yaml 提供了生产化配置样例，其中applicationName: longhorn会创建名为longhorn_upgrade_responder的数据库，responseConfig.configMap维护各版本的稳定标记（stable tags）供升级提示与版本统计使用，同时支持通过flags.scarfEndpoint配置下载统计网关。

测试计划与验收标准

提案给出的验证路径（Test plan）简洁明确：

1. 部署 Upgrade Responder 服务端（可选用仓库提供的自建方案）；
2. 分别在Allow Collecting Longhorn Usage Metrics启用与禁用两种状态下，核对数据库中upgrade_request表的记录：
   • 启用时：应能看到本文所述的节点信息、集群信息与设置字段（可对照上文示例格式检查列结构与取值）；
   • 禁用时：extraInfo不再携带额外信息，即验证开关真正生效。

总结

Allow Collecting Longhorn Usage Metrics设置与extraInfo扩展共同构成了 Longhorn 匿名使用数据采集的完整机制：默认启用、周期上报、内容分节点与集群两类、设置采集按"排除 / 转换 / 布尔化"三级规则收敛、服务器不存 IP 等可识别数据。对于运维人员，理解这一机制有助于在隐私合规要求下通过 UI、kubectl 或 Helm values 快速关闭采集；对于开发与研究人员，则可以通过本文的字段清单与示例数据格式，对 Longhorn 公共指标看板的数据做深入的解读与分析。

• 云原生
• 存储
• 高可用
• 容器编排