cx-service-catalog

サービスカタログスキル

このスキルを使うと、v2 Service Catalog API 経由で Service Catalog エンティティ（サービス、 データベース、オペレーション、データベースオペレーション、JVM、JVM GC、Kubernetes ポッド、 トランザクション）と、その列指向メトリクス（レイテンシ、エラー率、ヘルス、リソース使用量など）を 検出してクエリできます。

CLI コマンド

コマンド	目的	主なフラグ
cx service-catalog entity-types	このアカウントにデータがあるエンティティタイプを一覧表示します	-
cx service-catalog schema <entity-type>	1 つのエンティティタイプの列／ラベルのスキーマを表示します	-
cx service-catalog entities <entity-type>	1 つのタイプの既知のエンティティ（例：サービス名）を表示します	-
cx service-catalog data <entity-type>	あるタイプのすべてのエンティティにわたる集約列データを表示します	--start、--end、--column（必須、繰り返し指定可）、--group-by、--filter、--aggregation、--limit、--sort-column、--sort-order
cx service-catalog entity-data <entity-type> <entity-id>	名前を指定した 1 つのエンティティの列データを表示します（ドリルダウン）	--start、--end、--column（必須、繰り返し指定可）、--group-by、--filter、--aggregation

• すべてのコマンドは読み取り専用で、構造化出力用の -o json／-o toon に対応しています。
• エンティティタイプには短縮形を指定できます：service、database、operation、database-operation、jvm、jvm-gc、k8s-pod、transaction（大文字と小文字は区別されず、ハイフンまたはアンダースコアを使用できます）。完全な proto 名（ENTITY_TYPE_K8S_POD）も使用できます。未知の値は、リクエストを送信する前にクライアント側で拒否されます。
• --start／--end には、now、now-1h のような相対式、または RFC3339 タイムスタンプを指定できます。
• --column は必須で、繰り返し指定できます。有効な列 ID は、先に cx service-catalog schema <entity-type> で確認してください。未知の列 ID は API によって拒否されます。
• --filter label=value1,value2 は、異なるラベルに対してのみ繰り返し指定できます（フィルターは AND 条件で結合されます）。同じラベルの複数の値は、フラグを繰り返すのではなくカンマで区切って指定してください。同じラベルの繰り返し指定はクライアント側で拒否されます。
• --aggregation は table（--limit／--sort-column／--sort-order と組み合わせた場合のデフォルトの動作）または timeseries です。--limit、--sort-column、--sort-order は table の場合にのみ適用されます。バックエンドは timeseries ではこれらを黙って無視するため、CLI はフラグが静かに破棄されるリクエストを送信する代わりに、その組み合わせを事前に拒否します。
• entity-data はエンティティ ID を自動的にパーセントエンコードします。entities が返した値（例：checkout/api）をそのまま指定してください。/ を含む場合は引用符で囲みます。

確認ワークフロー

4 つのステップがあります。各ステップで次のステップに必要な入力を得るためだけに実行します。entity-types から有効な <entity-type> の値を取得し、schema から有効な --column ID を取得し、entities からドリルダウンに使用する entity-id を取得します。

1. 存在するエンティティタイプを検出します — アカウントによって異なるため、決して推測しないでください。

   cx service-catalog entity-types -o json
   

2. 1 つのエンティティタイプのスキーマを確認し、有効な列 ID とフィルター／グループ化が可能なラベルを調べます。

   cx service-catalog schema service -o json
   

3. そのタイプの既知のエンティティ（例：サービス名）を一覧表示します。

   cx service-catalog entities service -o json
   

4. データをクエリします — すべてのエンティティを対象に集約するか、1 つのエンティティに絞り込みます。以下の列 ID、フィルター／グループ化のラベル、エンティティ ID はプレースホルダーです。必ず対象のエンティティタイプについて schema／entities が返した値に置き換えてください。これらの値はアカウントとエンティティタイプによって異なります。

   cx service-catalog data <entity-type> --start now-1h --end now \
     --column <column-id> --column <column-id> -o json
   
   cx service-catalog entity-data <entity-type> <entity-id> --start now-1h --end now \
     --column <column-id> -o json
   

例

以下のコマンドでは具体例として service と k8s-pod を使用していますが、<column-id>、<filterable-label>、<groupable-label>、<entity-id> はすべて、そのエンティティタイプ固有の schema／entities の出力から取得する必要があります。あるエンティティタイプの列やラベルが、別のエンティティタイプにも存在すると決めつけないでください。

過去 1 時間のメトリクス上位 5 エンティティ

cx service-catalog schema service -o json  # discover column ids first
cx service-catalog data service --start now-1h --end now \
  --column <column-id> --aggregation table \
  --sort-column <column-id> --sort-order desc --limit 5 -o json

1 つのラベル値で絞り込む

cx service-catalog schema service -o json  # discover filterable_labels first
cx service-catalog data service --start now-1h --end now \
  --column <column-id> --column <column-id> \
  --filter <filterable-label>=<value> -o json

ラベルでグループ化する

cx service-catalog schema service -o json  # discover groupable_labels first
cx service-catalog data service --start now-1h --end now \
  --column <column-id> --group-by <groupable-label> -o json

Kubernetes ポッドのリソース飽和

cx service-catalog schema k8s-pod -o json  # discover column ids first
cx service-catalog data k8s-pod --start now-1h --end now \
  --column <column-id> --column <column-id> --column <column-id> -o json

1 つのエンティティの経時的なレイテンシ

cx service-catalog entities service -o json  # discover entity ids first
cx service-catalog entity-data service <entity-id> --start now-24h --end now \
  --column <column-id> --aggregation timeseries -o json

行のみ表示する

# Table responses live under .rows; timeseries under .series
cx service-catalog data service --start now-1h --end now \
  --column <column-id> -o json | jq '.rows'

主要な原則

• クエリの前に情報を確認する — entity-types と schema は手軽に実行でき、「ここで有効なものは何か」を把握できます。推測して data／entity-data を呼び出す前に利用してください。
• --column の値はエンティティタイプごとに異なります — service で有効な列が k8s-pod には存在しない場合があります。エンティティタイプを切り替えるときは、必ず schema を再確認してください。
• 不正なレスポンスは、何も返さずに空の結果を返すのではなくエラーになります — 値でもエラーでもない列（または両方に該当する列）がある場合、一部または空の行を返すのではなく、明示的にエラーになります。そのため、終了コードが 0 以外なら「データなし」ではなく、原因を調査してください。
• 列単位のエラーはコマンドの失敗ではありません — それ以外は成功した行の中に、個々の列が {"error": "..."} として返る場合があります（例：その列だけのクエリタイムアウト）。リクエスト全体が失敗したと判断する前に、列ごとの結果を確認してください。
• table と timeseries は相互に排他的な結果形式です — table のレスポンスは -o json | jq '.rows' に適したフラットな行です。timeseries のレスポンスは系列ごとにデータポイントがネストされているため、テーブルに変換するより、生の JSON として扱うのが最適です。
• フィルタリングには -o json と jq を、エージェントのコンテキストでトークン効率のよい出力を得るには -o toon を使用します。
• 複数プロファイルへのファンアウトは、すべてのサブコマンドで使用できます — -p <profile> を繰り返して、アカウント間で同じエンティティタイプ／データを比較します。複数指定した場合、行と系列には profile がタグ付けされます。

関連スキル

• cx-infra — インフラストラクチャリソースの健全性（ホスト、コンテナ）は、Service Catalog のエンティティの健全性とは別の概念です。ホスト／インスタンスレベルの監視には cx-infra を、アプリケーション／サービスレベルの APM エンティティにはこのスキルを使用します。
• cx-telemetry-querying — このスキルのコマンドでサービス名またはポッド名が見つかったら、生のテレメトリに切り替えます。関連するログ／スパンのフィールドを見つけるには、cx logs "filter $l.subsystemname == '<service>'" または cx search-fields "<name>" -s value を実行してください。レイテンシやエラーの急増と、関連するログ／スパンを関連付けます。
• cx-alerts — cx alerts list --name "<service-name>" を実行すると、このスキルで見つかったサービスに一致するアラート定義を検索できます。
• cx-dashboards — cx dashboards search "<service-name> ..." を実行すると、ここで見つかったサービスを対象に作成されたダッシュボードを検索できます。