cost-export

コストエクスポート

cost-tracking からすべての session-* と budget-config-* レコードを取得し、外部のオブザーバビリティシステムで利用できる形式で出力します。これがないと、コストデータは AgentDB の名前空間内にしか存在しません。この機能を使うと、同じデータをダッシュボードに表示できます。

使用するタイミング

• コストトラックの実行後、Grafana／Datadog／Prometheus のメトリクスを更新するとき。
• /loop 5m を使って cron から定期実行し、外部ダッシュボードをほぼリアルタイムで更新するとき。
• アドホックなレポート用に、Webhook（Slack、カスタムエンドポイント）へ一度だけ送信するとき。

手順

1. 形式を選択する — Prometheus／Grafana 用の textfile collector、またはそれ以外の用途向けの Webhook POST を選びます。

   # Prometheus node_exporter textfile collector
   node plugins/ruflo-cost-tracker/scripts/export.mjs --prometheus /var/lib/node_exporter/textfile_collector/cost_tracker.prom
   
   # Webhook (POSTs JSON; add auth via env)
   EXPORT_WEBHOOK_HEADER='Authorization: Bearer $TOKEN' \
     node plugins/ruflo-cost-tracker/scripts/export.mjs --webhook https://hooks.example.com/cost-tracker
   
   # Stdout JSON (default if no flag)
   node plugins/ruflo-cost-tracker/scripts/export.mjs
   

2. 出力内容を確認する — Prometheus の出力には次の内容が含まれます。

   cost_tracker_total_usd                                    <gauge>
   cost_tracker_tier_total_usd{tier="opus|sonnet|haiku"}     <gauge>
   cost_tracker_session_total_usd{session="<8-char>"}        <gauge>
   cost_tracker_session_messages{session="<8-char>"}         <counter>
   cost_tracker_budget_usd                                   <gauge>  (if budget configured)
   cost_tracker_budget_utilization                           <gauge>  (spent / budget)
   

3. Webhook ペイロードの形式 — Webhook が受信する JSON は、標準出力の JSON と同じです。形式は { exportedAt, sessions: [...], budget, totalUsd, byTier } です。EXPORT_WEBHOOK_HEADER='K1: V1, K2: V2' を指定すると、ヘッダーを追加できます（カンマ区切り）。

環境変数による上書き

環境変数	デフォルト	用途
EXPORT_NAMESPACE	cost-tracking	対象の名前空間を上書きします
EXPORT_WEBHOOK_HEADER	未設定	Webhook 認証用の K: V ペアをカンマ区切りで指定します
EXPORT_QUIET=1	未設定	エラー以外の確認メッセージを抑制します

関連項目

• cost-track — このスキルがエクスポートするデータを生成します
• cost-budget-check — 同じ cost_tracker_budget_* メトリクスを Prometheus でアラート対象にできます
• node_exporter textfile collector のドキュメント（Prometheus の規約） — .prom ファイルを collector ディレクトリに配置すると、Prometheus が読み込みます