cawplan-metrics

CawPlan メトリクス

ブートストラップ

cawplan skill check

エントリーの振り分け

入力	フロー
ビジネスメトリクスの推移の照会やグラフ化（サブスクリプション、CawPlan のチケット、QA、ワークフロー、トークン、API の使用状況など）	A — メトリクスの照会
ビジネスメトリクスイベントの記録／ログ記録	B — メトリクスの取り込み

ここにはデバイス／アプリのメトリクスに関するフローはありません。以前 API キー／CLI を通じてインストール数やクラッシュ率などを提供していた公開エンドポイントは廃止されました。ユーザーがその種のデータを求めた場合は、代替手段を推測して案内するのではなく、このスキル／CLI からは利用できなくなったことを伝えてください。

ワークフロー A — メトリクスのクエリ

各ドメインには cawplan_ が前置されます。ビジネスドメインとそのメトリクス名に決まった範囲はなく（時間の経過とともに新しいものが追加されます）、現在よく使われているものと、特に、各ドメイン内で現時点に実際にデータを書き込むプロデューサーがあるメトリクスと、定義済みでもまだ空のメトリクスを以下に示します（空のメトリクスに対するクエリは 0 行を返します。これは「この期間にデータがない」と同じ結果に見え、「まだ接続されていない」ことを意味するわけではありません。このリストを確認せずに推測しないでください）。

• cawplan_ticket：ticket_created、ticket_updated、ticket_status_changed — すべて接続済みです。
• cawplan_qa_insight：test_point_created、test_point_updated、report_created、execution — すべて接続済みです。
• cawplan_subscription：new、renew（Stripe の invoice.paid から取得し、billing_reason で区別）と cancel（ユーザーが開始した Free へのキャンセル）は接続済みです。winback、upgrade、downgrade は定義済みですが、まだ呼び出すものはありません。
• cawplan_api：throttled（429 レスポンスごとに 1 ポイント）は接続済みです。request は定義済みですが、まだ呼び出すものはありません。
• cawplan_ai_session_usage：usage_reported — 接続済みです。AI コーディングツールの使用状況レポートをアップロードするたびに、日次で 1 ポイントが記録されます（トークン数／セッション数／コスト、ワークスペース単位）。これは AI コーディングツールの内部エンジニアリングコストのテレメトリ（cawplan-coding-insights パイプライン）であり、顧客向けのトークン／クレジット台帳ではありません。以下の cawplan_token と混同しないでください。
• cawplan_workflow（execution）、cawplan_token（consumed、recharged、refunded、cost）、cawplan_user（signup、active）、cawplan_csm、cawplan_purchase：すべて定義済みですが、まだどのプロデューサーにも接続されていません — 現時点では、これらのいずれに対してクエリを実行しても常に 0 行が返されます。

ユーザーが指定したメトリクスが、これらのいずれかに明確に当てはまらない場合は、domain／metric の組み合わせを推測せず、確認してください。

1. 時間範囲を決定します。--start と --end（RFC3339）の両方を必須とします。ユーザーが「過去 30 日間」「今週」のような相対的な範囲を指定した場合は、クライアント側で期間の開始と終了を計算してください。このエンドポイントには time_range の省略表記はありません。

2. ユーザーが結果を製品またはワークスペースで絞り込む、あるいは内訳を表示したい場合は、まず製品名を ID に解決します（cawplan products list --search "<product name>"。他のスキルと同じ照合ルールを適用し、完全一致または一意に特定できる短縮名の場合のみ使用し、曖昧な場合は確認してください）。そのうえで、--tag product:<product_id>／--tag workspace_id:<workspace_id> を指定するか、--group_by に product／workspace_id を含めます。product には製品の unique_id が格納されます（表示名ではなく、cawplan products list が返す値）。workspace_id はテナントの帰属を示すディメンションであり、データベース全体ではなく単一のワークスペースに範囲を限定するクエリでは、追加する価値があります。特に cawplan_ticket イベントでは、--tag ticket_id:<ticket_id>（標準ディメンションではなく動的タグ）を使うと、特定の製品に関するポイントの集中を識別できます。複数のチケットに影響する祖先ステータスの伝播カスケードは、ticket_id で絞り込むかグループ化しない限り、同じチケットが繰り返し書き込まれた場合と同じように見えます。

3. クエリを実行します：

   cawplan metrics query \
     --domain <domain> [--metric <metric>] \
     --start <iso> --end <iso> \
     --granularity day \
     [--tag <key:value> ...] \
     [--group_by <k1,k2>] \
     [--fields value,count]
   

   デフォルトの --granularity raw は、保存されているすべてのポイントを集計せずに返します。代わりに day／hour／minute を選ぶと、タグの組み合わせごとに各バケットの合計行が 1 行返されます。生イベントの一覧ではなく傾向を見たい場合は、バケット化された粒度を使用してください。

4. レスポンスの data.truncated を確認します。true の場合、結果は上限に達しています。切り捨てられた件数を完全な件数として報告するのではなく、合計を報告する前に、時間範囲またはフィルターを狭めるか、（サーバー独自の上限まで）--limit を増やしてください。

ワークフロー B — メトリクスの取り込み

ユーザーがメトリクスイベントの記録／ログ記録／書き込みを明示的に依頼した場合に限り使用してください。一括で履歴をバックフィルまたは修正する目的では使用しないでください（取り込みエンドポイントは検証を行い、バッチ内で最初に不正な項目を検出した時点で拒否します。一括ロード用のツールではありません）。

cawplan metrics ingest --domain <domain> --metric <metric> --value 1 \
  [--dimensions '{"product":"<product_id>"}'] \
  [--tags '{"from_plan":"basic","to_plan":"pro"}']

書き込みの前に、domain／metric の組み合わせと、各種ディメンション／タグをユーザーに確認してください。書き込まれたポイントは元に戻せません（references/CAWPLAN_OPEN_API.md §7 を参照）。

出力

ワークフロー A：

• query は構造化された完全な data.rows を返します。通常はこれだけで十分です。この会話内でユーザーに表示するだけのグラフ（保存用ファイルではない）を作る場合、CLI の描画フラグは使わないでください。data.rows を自分で読み取り、グラフを直接描画／説明するか、dataviz スキルに渡してインライン／インタラクティブな可視化を行ってください。time を x 軸に、系列を区別するタグの組み合わせでグループ化し、指定されたフィールドを y 軸に割り当てます。この場合、ディスクに書き込む必要はありません。
• グラフではなく数値／概要を求められた場合は、バケット／タグの組み合わせごとの合計を直接報告してください。
• ユーザーが保存／共有用の単独のグラフファイルを求めている場合（その場で見るだけではない場合）は、--chart <path>.svg を追加します（value 以外の場合は --chart-field <value|count|cost|credit> も追加します）。ファイルパスをユーザーに伝えてください。
• そのファイルをこのチャット内に実際の画像としてインライン表示する必要がある場合（SVG をプレーンテキストとして扱う一方でラスター画像をデコードする Read ツールを使う場合など）は、同じ query 呼び出しに --png <path>.png を追加してから、そのパスを Read で読み込んで表示します。--chart と同じ方法で作成した SVG からラスター化します。環境で利用できるもの（macOS では qlmanage、それ以外では rsvg-convert）を使用するため、別途描画する手順は不要です。ラスター化ツールが利用できない場合、コマンドは壊れたファイルを書き込むのではなくエラーで終了します。注意：PNG をデコードできても、Read で読み込んだ画像が常にユーザーに表示されるとは限りません（iTerm2 の直接接続セッションでの確認例では、同じウィンドウで imgcat <path>.png を手動実行すると正しく表示されましたが、同じファイルを Read で読み込んでもユーザーの画面には表示されませんでした）。Read で読み込んだ後も画像が見えないとユーザーから報告された場合は、Read に頼らず、代わりに imgcat <path>.png（または使用中のターミナルで対応するコマンド）を直接試すよう伝えてください。
• --preview（iTerm2／Kitty／chafa によるインライン画像表示）は、ユーザー自身のターミナルで cawplan を直接実行する場合に限って使用してください。こちらが実行しても機能しません。出力されるエスケープコードは、生の標準出力を読み取る実際のターミナルエミュレーター内でのみ画像として描画されます。このチャットではツールの出力がテキストとして取得されるため、代わりに文字化けしたエスケープシーケンスが表示されます。ここでは使わず、data.rows を自分で読み取るか、代わりに --png を使用してください。
• 使用した時間範囲と粒度を必ず伝え、data.truncated が true の場合はその旨を明記してください。

ワークフロー B： 書き込まれた内容（domain、metric、フィールド、ディメンション／タグ）を確認し、このメトリクスストアはレポート用のストアであり、正式な記録システムではないことを伝えてください。財務またはコンプライアンス上の重要性があるデータ（トークン／クレジットなど）については、正式な台帳は別の場所にあり、この書き込みはダッシュボード用であることを明記してください。

判断ガイド

• Support Ops の Google スプレッドシートのエクスポート、CSM のチケット件数のバックフィル、修正、または照合作業には、cawplan-support-metrics を使用してください。
• 総合的なプロダクトの健全性概要（フィードバックと重大な問題を含みます。デバイスメトリクスはこの CLI では利用できなくなったため含みません）には、cawplan-product-insights を使用してください。
• AI によって分類されたフィードバックの傾向のみを調べる場合は、cawplan analytics get <product_id> を使用してください。
• 期間を指定したアクティビティ／進捗レポートには、cawplan-product-report を使用してください。

参考資料

• references/CAWPLAN_OPEN_API.md