如何用StatsD(Prometheus)推送用户对象数组到Grafana构建Gauge仪表盘

问题描述 #

想要通过StatsD（对接Prometheus）推送包含user_id及用户专属属性的对象数组，目标是在Grafana中按所选属性统计用户数量。示例推送数据：

[
        {
            "user_id": "b3726d1d-e947-4035-bd98-87bddbca1c2b",
            "premium": false,
            "basic": false
        },
        {
            "user_id": "a2b9e909-0e35-48b2-a7d6-0a554f802159",
            "premium": false,
            "basic": true
        },
        {
            "user_id": "1e91df33-122b-4199-adff-a001e7864221",
            "premium": true,
            "basic": false
        }
]

之前尝试直接推送整个数组：

const userStatistics = await UserRepository.getUserStatistics();
statsD.default.gauge("user_statistics", userStatistics);

但指标完全不显示。需要一个可扩展的方案，未来可能新增更多用户属性。

实现方案 #

1. 正确的StatsD指标推送方式 #

StatsD的gauge无法直接接收对象数组，必须把每个用户的属性转换成带标签的指标，才能被Prometheus识别并按维度统计。

遍历用户数组，为每个属性推送带标签的gauge值（用1表示属性为true，0表示false），代码示例：

const userStatistics = await UserRepository.getUserStatistics();

userStatistics.forEach(user => {
  // 跳过user_id，仅处理属性字段
  Object.entries(user).forEach(([key, value]) => {
    if (key !== 'user_id') {
      statsD.default.gauge(
        "user_attribute", 
        value ? 1 : 0, 
        { user_id: user.user_id, attribute: key }
      );
    }
  });
});

如果只需要统计属性为true的用户，也可以只推送属性为true的条目，减少数据量：

userStatistics.forEach(user => {
  Object.entries(user).forEach(([key, value]) => {
    if (key !== 'user_id' && value) {
      statsD.default.gauge(
        "user_active_attribute", 
        1, 
        { user_id: user.user_id, attribute: key }
      );
    }
  });
});

2. Grafana中动态统计属性用户数 #

在Grafana使用PromQL查询，结合标签筛选并去重统计用户数：

• 统计premium用户数量：

  count(count(user_attribute{attribute="premium", value="1"}) by (user_id))
  

  若用第二种推送方式（只推true值），查询语句可简化为：

  count(count(user_active_attribute{attribute="premium"}) by (user_id))
  

• 实现选择属性动态统计：给Grafana面板添加attribute变量（类型选查询，数据源选Prometheus，查询语句label_values(user_attribute, attribute)），然后将PromQL改为：

  count(count(user_attribute{attribute="$attribute", value="1"}) by (user_id))
  

3. 可扩展优化建议 #

• 新增属性时无需修改推送代码，遍历逻辑会自动处理新字段
• 可以推送总用户数指标，方便快速查看整体规模：

  statsD.default.gauge("total_users", userStatistics.length);
  

• 若用户量较大，建议定期（比如每分钟）推送一次，避免频繁推送造成性能损耗

内容的提问来源于stack exchange，提问作者mehawelm11