statsig-dashboard

创建 Statsig Dashboard

为 console v1 dashboards API 构建有效的 API 请求，并使用随附脚本执行请求。

阅读 references/dashboard-api.md，了解准确的字段级架构、支持的值和可直接编辑的示例。

以下命令示例假定你在此技能目录中运行。

快速开始

1. 导出 API 密钥： export STATSIG_CONSOLE_API_KEY="..."
2. 将请求正文保存到 JSON 文件。
3. 运行对应的脚本：

python3 scripts/create_dashboard.py \
  --body-file /tmp/dashboard.json

配套脚本

• scripts/create_dashboard.py：使用 POST /console/v1/dashboards 创建新的仪表板
• scripts/read_dashboard.py：使用 GET /console/v1/dashboards/{id} 获取仪表板；默认打印与创建兼容的格式
• scripts/add_dashboard_widgets.py：使用 POST /console/v1/dashboards/{id}/widgets 添加工具
• scripts/replace_dashboard_widgets.py：使用 PUT /console/v1/dashboards/{id}/widgets 替换所有工具

工作流

1. 选择正确的端点：
   • 创建仪表板：create_dashboard.py
   • 以与创建兼容的格式读取仪表板：read_dashboard.py
   • 添加工具：add_dashboard_widgets.py
   • 替换所有工具：replace_dashboard_widgets.py
2. 为所选端点构建匹配的请求正文。
3. 仅包含受支持的字段：
   • name
   • description
   • defaults
   • widgets
4. 将每个请求的工具映射到一种受支持的工具类型：
   • header
   • text
   • timeseries
   • 每个工具都可以包含可选的 width 和 height
5. 对于 timeseries，严格遵循查询约定：
   • source 和 sources 中必须且只能包含一个
   • 每个来源都使用 type: "event"
   • 包含 aggregation
   • 仅使用受支持的筛选运算符和图表类型
   • 如果用户希望按事件值分组或筛选，请使用 !statsig_value，而不是 value
6. 执行对应的脚本。
7. 返回 API 响应；如果用户只需要仪表板 ID 或工具 ID，则概述这些 ID。

服务筛选条件

当工具需要限定 Statsig 服务范围时，优先使用以下筛选条件：

{
  "property": {
    "key": "custom.service",
    "column": "user_object"
  },
  "operator": "EQ",
  "values": ["service-name"]
}

构建仪表板工具时，不要默认使用裸字段 service。在 Statsig 事件负载中，该字段通常嵌套在 user_object.custom 下，因此 custom.service 是更稳妥的默认选择。

OTEL 聚合

当工具针对的指标可能来自 OTEL 时，先采样该指标并检查 company_metadata.__metric_type。

• 如果存在 __metric_type，则将该指标视为由 OTEL 提供，并优先使用匹配的 OTEL 聚合系列，而不是普通聚合。
• 如果代表性样本中不存在 __metric_type，则将该指标视为非 OTEL 指标，并使用常规聚合类型。

首选映射：

• __metric_type = "gauge"：使用 OTEL_GAUGE__AVG、OTEL_GAUGE__MAX、OTEL_GAUGE__MIN 或 OTEL_GAUGE__SUM
• __metric_type = "counter"：使用 OTEL_COUNTER__SUM、OTEL_COUNTER__AVG、OTEL_COUNTER__MIN 或 OTEL_COUNTER__MAX
• __metric_type = "histogram"：使用 references/dashboard-api.md 中说明的 OTEL 直方图聚合

转换时保持聚合意图不变：

• 平均值类型的工具应使用 OTEL_GAUGE__AVG，而不是 AVG
• 最大值类型的工具应使用 OTEL_GAUGE__MAX，而不是 MAX

注意事项

• 不要虚构不受支持的工具类型，例如表格。
• 创建仪表板时不要包含布局字段。创建端点不接受工具位置。
• 不要包含 row 或 column。API 目前支持通过 width 和 height 调整工具大小，不支持显式指定位置。
• 创建请求正文中不要包含 id。
• 如果用户提供了通过 GET /console/v1/dashboards/{id} 获取的仪表板，请复用其与创建兼容的格式，但移除 id。
• 用户希望修改现有仪表板时，不要使用创建端点。
• 文本工具中优先使用 Markdown 格式，让内容清晰且结构分明。

示例

最简仪表板：

cat > /tmp/dashboard.json <<'JSON'
{
  "name": "Checkout Overview"
}
JSON

python3 scripts/create_dashboard.py \
  --body-file /tmp/dashboard.json

将现有仪表板读取为可复用的创建负载：

python3 scripts/read_dashboard.py \
  --dashboard-id dash_123

向现有仪表板追加组件：

python3 scripts/add_dashboard_widgets.py \
  --dashboard-id dash_123 \
  --body-file /tmp/add-widgets.json

替换现有仪表板上的所有组件：

python3 scripts/replace_dashboard_widgets.py \
  --dashboard-id dash_123 \
  --body-file /tmp/replace-widgets.json

脚本说明

• 所有脚本都从环境变量中读取 STATSIG_CONSOLE_API_KEY。
• 所有脚本都将 STATSIG_API_VERSION 的默认值设为 20240601。
• 传入 --api-version 或设置 STATSIG_API_VERSION 可覆盖该默认值。
• 所有脚本的默认地址均为 https://api.statsig.com/console/v1/dashboards。
• 所有脚本都在 statsig-api-key 请求头中发送 Console API 密钥。
• 所有脚本都发送已配置的 statsig-api-version 请求头。
• create_dashboard.py、add_dashboard_widgets.py 和 replace_dashboard_widgets.py 接受：
  • --body-file
  • --body
  • 标准输入
• read_dashboard.py、add_dashboard_widgets.py 和 replace_dashboard_widgets.py 要求提供 --dashboard-id。
• 所有脚本都支持 --dry-run。
• 所有脚本都支持 --raw。
• 只有设置 --raw 时，read_dashboard.py 才会输出原始 GET 响应。否则，它会解包 data 并移除 id。