statsig-dashboard

Statsig ダッシュボードの作成

コンソール v1 ダッシュボード 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 を含めます
   • サポートされているフィルター演算子とグラフタイプのみを使用します
   • イベント値によるグループ化またはフィルターを要求された場合は、value ではなく !statsig_value を使用します
6. 対応するスクリプトを実行します。
7. API レスポンスを返すか、それだけで十分な場合は、作成されたダッシュボード 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 ヒストグラム集計を使用します

変換する際も、集計の意図を維持してください：

• 平均値を求めるウィジェットでは、AVG の代わりに OTEL_GAUGE__AVG を使用します
• 最大値を求めるウィジェットでは、MAX の代わりに OTEL_GAUGE__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 を設定してください。
• すべてのスクリプトで、デフォルトの URL は https://api.statsig.com/console/v1/dashboards です。
• すべてのスクリプトは、Console API キーを statsig-api-key ヘッダーで送信します。
• すべてのスクリプトは、設定された statsig-api-version ヘッダーを送信します。
• create_dashboard.py、add_dashboard_widgets.py、replace_dashboard_widgets.py は、以下を受け付けます：
  • --body-file
  • --body
  • stdin
• read_dashboard.py、add_dashboard_widgets.py、replace_dashboard_widgets.py では、--dashboard-id が必要です。
• すべてのスクリプトは --dry-run に対応しています。
• すべてのスクリプトは --raw に対応しています。
• read_dashboard.py は、--raw が指定されている場合のみ、GET のレスポンスをそのまま出力します。それ以外の場合は、data の内容を取り出して id を削除します。