cx-cost-optimization

コスト最適化スキル

Coralogix のデータコストを調査または削減するときに、このスキルを使用します。現在の支出の測定、TCO ポリシーの確認、保持期間の調整、コールドデータのアーカイブストレージの設定など、コスト管理のライフサイクル全体を網羅しています。

---

CLI コマンド

コマンド	サブコマンド	目的
cx usage	summary、daily、logs-count、spans-count、export-status、capabilities、query	現在のデータ消費量と課金対象の使用量を測定します
cx tco	list、get、create、update、delete、reorder、test、settings、settings-update	TCO（総所有コスト）ポリシーを管理します
cx retentions	list、update、activate、status	データの保持期間を管理します
cx archive logs	get、set	ログのアーカイブ先を設定します
cx archive metrics	get、create、update、enable、disable、validate	メトリクスのアーカイブストレージを設定します
cx metrics query	<promql>（位置引数）、--time	PromQL を使用して課金および使用量のメトリクスをクエリします（瞬時値）
cx metrics query-range	<promql>（位置引数）、--start／--end	PromQL を使用して課金および使用量のメトリクスをクエリします（範囲）

主なフラグ：

• すべてのコマンドで、構造化出力用の -o json と、プロファイル選択用の -p <profile> が使用できます
• cx usage daily は、--type processed-gbs|units|evaluation-tokens と --start／--end の時間フィルターを受け付けます
• cx usage summary は、--start／--end の時間フィルターを受け付けます
• cx usage logs-count と cx usage spans-count は、--start／--end の時間フィルター（既定値は直近 24 時間）に加え、--resolution（既定値は 1h）、--subsystem-aggregation、--application-aggregation、および API フィルターのクエリパラメーターを指定する、繰り返し指定可能な --param KEY=VALUE を受け付けます
• データ使用量の概要および件数のエンドポイントは、Accept: text/event-stream を使用する改行区切りの JSON として文書化されています。CLI はこの通信方式を処理し、件数チャンクを .result.logsCount[] または .result.spansCount[] に正規化します。
• cx usage capabilities は必須の最初の手順です。選択したテナントで現在サポートされているラベル、測定値、単位、およびリクエスト上限を、公開 Data Usage Query API から取得します
• cx usage query は必須の2番目の手順です。直前の capabilities レスポンスから導出した JSON リクエストのみを送信し、--query '<json>' または --from-file <path> のいずれか一方だけを指定します（--from-file - は標準入力を読み取ります）
• cx tco create/update、cx retentions update、cx archive logs set、cx archive metrics create/update/validate では、--from-file <path>（または標準入力を表す -）を使用します

---

課金対象使用量の権威あるクエリ

課金対象の合計、クォータ単位、プランの消費量、またはサポートされている使用量の内訳を取得する場合は、必須の次の2段階ワークフローを使用します。

1. 現在のセッションで cx usage capabilities を実行します。
2. そのレスポンスのみを使用して cx usage query を作成し、実行します。

cx usage query を先に呼び出したり、ラベル、測定の種類、単位、フィルター値、間隔、リクエスト上限を推測したりしないでください。これらはテナント固有であり、変更される可能性があります。

# Inspect the currently valid dimensions and constraints
cx usage capabilities -o json

# Submit a capabilities-derived request inline
cx usage query --query '{"daily":{"relativeRange":"DAILY_RELATIVE_RANGE_LAST_7_DAYS"}}' -o json

# Or read the same request from a file or stdin
cx usage query --from-file usage-query.json -o json
printf '%s' '{"daily":{"relativeRange":"DAILY_RELATIVE_RANGE_LAST_7_DAYS"}}' \
  | cx usage query --from-file - -o json

クエリ本文を作成する前に、references/data-usage-query-api.md を読み込んでください。このファイルには、capabilities とレスポンスのスキーマ、有効な間隔の形式、および上限が定義されています。

---

コスト調査のワークフロー

コストを診断して削減するには、次の手順に従います。

ステップ 1：現在の使用量を測定する

課金対象の合計、クォータ単位、プランの消費量、またはサポートされている内訳を取得する場合は、まず上記の必須の2段階ワークフローに従います。

cx usage capabilities -o json
cx usage query --from-file usage-query.json -o json

usage-query.json は、直前の capabilities レスポンスのみを使用して作成します。権威ある課金情報の代わりに、以下のレガシーコマンドを使用しないでください。

レガシーの消費量概要とログ／スパンのレコード件数を確認するには、次を使用します。

cx usage summary -o json
cx usage summary --start now-30d -o json
cx usage daily --type processed-gbs --start now-7d -o json
cx usage logs-count --start now-7d --end now -o json
cx usage spans-count --start now-7d --end now -o json

どのデータタイプが最も多くのデータ量を消費しているかを特定します。jq を使用して並べ替えます。

cx usage summary -o json | jq '[.[] | {name, daily_avg: .avg_daily_gb}] | sort_by(.daily_avg) | reverse'

ステップ 2：TCO ポリシーを確認する

cx tco list -o json
cx tco settings -o json

TCO ポリシーでは、どのログをフリークエントサーチ（高コスト、高速）とアーカイブ（低コスト、低速）のどちらに送るかを制御します。量が多く価値の低いログがフリークエントサーチに設定されていないか確認します。

cx tco list -o json | jq '.[] | select(.priority == "LOW") | {name, application, subsystem, archive_retention}'

ステップ 3：保持設定を確認する

cx retentions list -o json
cx retentions status -o json

保持期間が長いほど、ストレージコストが増加します。不必要に長い保持期間が設定されているインデックスを特定します。

ステップ 4：アーカイブ設定を確認する

cx archive logs get -o json
cx archive metrics get -o json

コールドデータ用にアーカイブストレージが設定されていることを確認します。アーカイブが設定されていない場合は、コスト削減の機会となります。

ステップ 5：最適化を提案する

調査結果に基づき、優先度の高い順（影響が最も大きいものから）に変更を提案します。

---

よくある最適化パターン

症状	診断コマンド	最適化
量が多く価値の低いログ	cx usage summary -o json	cx tco create --from-file policy.json でアーカイブ階層に移動する
コールドデータの保持期間が長い	cx retentions list -o json	cx retentions update --from-file で保持期間を短縮する
コールドストレージが設定されていない	cx archive logs get -o json	ユーザーの承認後、cx archive logs set --from-file --yes でアーカイブを有効にする
高コストのメトリクスが照会されていない	cx archive metrics get -o json	ユーザーの承認後、cx archive metrics create --from-file --yes でメトリクスのアーカイブを有効にする

---

jq の例

使用状況の分析

# Top consumers by daily volume
cx usage summary -o json | jq '[.[] | {name, daily_avg: .avg_daily_gb}] | sort_by(.daily_avg) | reverse | .[0:10]'

# Daily trend for the past week
cx usage daily --type processed-gbs --start now-7d -o json | jq '[.[] | {date, gb: .processed_gbs}]'

# Total logs and spans counts
cx usage logs-count --start now-7d --end now -o json | jq '[.result.logsCount[]?.logsCount | tonumber] | add // 0'
cx usage spans-count --start now-7d --end now -o json | jq '[.result.spansCount[]? | ((.successSpanCount | tonumber) + (.errorSpanCount | tonumber) + (.lowSuccessSpanCount | tonumber) + (.lowErrorSpanCount | tonumber) + (.mediumSuccessSpanCount | tonumber) + (.mediumErrorSpanCount | tonumber))] | add // 0'

TCO ポリシーの分析

# Policies routing to archive tier
cx tco list -o json | jq '[.[] | select(.archive_retention != null)]'

# Policies by priority
cx tco list -o json | jq 'group_by(.priority) | map({priority: .[0].priority, count: length})'

# Test if a log pattern matches a policy
cx tco test --from-file test-definition.json -o json

保持設定の確認

# All retention settings
cx retentions list -o json | jq '.[]'

# Check if retention is active
cx retentions status -o json

アーカイブのステータス

# Logs archive configuration
cx archive logs get -o json | jq '{active: .active, bucket: .bucket}'

# Metrics archive configuration
cx archive metrics get -o json | jq '{enabled: .enabled, bucket: .bucket}'

---

変更の適用

重要：ユーザーの明示的な承認なしに --yes を指定してはいけません。 アーカイブ、TCO、保持設定に関するすべての書き込み操作では、対話形式の確認と、非対話形式で実行するための --yes フラグが必要です。書き込み操作を実行する前に、変更内容を正確にユーザーに説明し、承認を得てから --yes を指定してください。

読み取り専用モード： --read-only（または CX_READ_ONLY=1）を使用すると、誤って書き込みを行うリスクなしに、コストデータを安全に確認できます。すべてのクエリコマンド（usage、tco list/get、retentions list、archive get）は読み取り専用モードでも通常どおり動作します。

エージェントモード： AI エージェント内で実行すると、cx は stdin のプロンプトで停止せず、書き込み操作をすぐに失敗させます。まずユーザーの確認を得てから、--yes を指定して再実行してください。

TCO ポリシー、保持設定、またはアーカイブを変更する場合：

1. 既存の設定をテンプレートにする： 現在の設定を JSON 形式で取得して変更し、適用します。

   cx tco get <policy-id> -o json > policy.json
   # Edit policy.json
   cx tco update --from-file policy.json
   

2. 変更後に確認する： 診断コマンドを再実行し、変更が反映されたことを確認します。

3. TCO ポリシーの順序は重要です： cx tco reorder --from-file を使用して優先順位を設定します。ポリシーは上から順に評価され、最初に一致したものが適用されます。

---

メトリクスに基づくコスト分析

cx usage API では概要を取得できますが、請求額に正確に一致する分析、異常検知、ピラー／機能ごとの内訳を確認するには、PromQL を使用して顧客のメトリクスエクスポーターにクエリを実行します。

主なメトリクス

メトリクス	意味	クエリの接尾辞
cx_data_usage_units	1 日あたりの請求対象使用量（単位）（正規の請求メトリクス）	_total なし
cx_data_plan_units_per_day	現在の 1 日あたりのプラン上限（単位）（スナップショット）	_total なし
cx_data_usage_payg_units	1 日あたりの超過／PAYG 使用量（単位）	_total なし
cx_data_usage_total	処理されたデータのサイズ（バイト）	_total
cx_data_usage_tokens_total	AI 評価トークン	_total
cx_data_usage_samples_total	処理されたメトリクスサンプル	_total

概念とメトリクスの対応

• 請求／プラン使用量／消費量 -> cx_data_usage_units + cx_data_plan_units_per_day
• 処理済みバイト数／データ量 -> cx_data_usage_total
• AI 評価トークン -> cx_data_usage_tokens_total
• メトリクスサンプル -> cx_data_usage_samples_total
• 超過／PAYG -> cx_data_usage_payg_units

よく使う PromQL クエリ

# Today's billable units consumed so far
cx metrics query 'sum(cx_data_usage_units)' --time now -o json

# Units breakdown by pillar
cx metrics query 'sum by (pillar) (cx_data_usage_units)' --time now -o json

# Daily plan quota
cx metrics query 'cx_data_plan_units_per_day' --time now -o json

# Plan consumption percentage
cx metrics query '100 * sum(cx_data_usage_units) / cx_data_plan_units_per_day' --time now -o json

# Units by feature group
cx metrics query 'sum by (feature_group_id) (cx_data_usage_units)' --time now -o json

# PAYG overage (if any)
cx metrics query 'cx_data_usage_payg_units' --time now -o json

UTC 日単位の集計ルール

すべての使用量メトリクスは UTC の午前 0 時から累積し、00:00 UTC にリセットされます。

• 日中にインスタントクエリを実行すると、「今日の現時点まで」の値が返されます
• 完了した日の合計値には、午前 0 時前の最後のサンプルを使用します
• UTC の午前 0 時をまたいで値を差し引かないでください
• 週次・月次分析では、まず完了した日ごとの合計値を算出してから集計します
• トレンドや平均を算出する際は、現在の未完了の UTC 日を除外します

異常検出

使用量の異常を調査する場合：

1. 完了した UTC 日を比較します（現在の未完了の日は除外）
2. 次の順に内訳を確認します：measurement_type -> pillar -> entity_type -> priority -> feature_group_id -> application_name -> subsystem_name
3. 季節性のあるトラフィックは、曜日を揃えて比較することを優先します
4. 請求の異常には cx_data_usage_units、ボリュームの異常には cx_data_usage_total を使用します

内訳ラベル

使用量メトリクスでは、次のグループ化ディメンションを使用できます：pillar、entity_type、priority、measurement_type、feature_group_id、feature_id、application_name、subsystem_name。

---

主な原則

• 変更前に測定する - ポリシーを変更する前に、必ず使用量・概要コマンドを実行します
• jq と -o json を使用する - 構造化出力により、正確な分析が可能になります
• 変更を検証する - 変更のたびに再クエリし、反映されたことを確認します
• 複数プロファイルを意識する - 環境間のコストを比較するには、-p <profile> または --all-profiles を使用します
• 既存の設定をテンプレートにする - 作成または更新の前に、現在の設定を JSON で取得します
• TCO が最大の改善要因です - ログを Frequent Search から Archive 層に移行すると、最も大きなコスト削減効果が得られます

---

関連スキル

• cx-telemetry-querying - 取り込まれているデータを調査します（ログ、メトリクス、スパンをクエリして、大量のデータを生成するソースを特定します）

参考ファイル

• references/data-usage-query-api.md - 機能とクエリスキーマ、間隔のルール、制限、レスポンスの解釈