cx-profiling

プロファイリングスキル

Coralogix プロファイリング API を通じて、どのサービスが最も多くの CPU やメモリを消費しているか、またサービス内のどの関数がその原因となっているかなど、継続的プロファイリングに関する質問に回答する際にこのスキルを使用します。profiles.cpu-profiles:Read 権限が必要です。

CLI コマンド

コマンド	目的	主なフラグ
cx profiling services	CPU＋ウォール秒（cpu）、または割り当て＋ヒープバイト（memory）の多い順にプロファイリング対象サービスを表示	--category（必須）、--environment、--limit（デフォルト 20、最大 100）、--offset、--include-time-series
cx profiling metadata <service>	サービスの言語と、データがあるプロファイルタイプを表示	-
cx profiling filters <service>	サービスのプロファイルを絞り込むためのラベルキーとその値を表示	--profile-type（必須）、--filter、--max-values-per-key（デフォルト 50）
cx profiling metrics <service>	1 つのプロファイルタイプの使用量を時間ごとに表示し、service、pod、または任意のラベルで分割。合計値の多い順に表示	--profile-type（必須）、--sum-by（デフォルト service）、--max-buckets（デフォルト 60）、--limit（デフォルト 10）、--filter
cx profiling flame-graph <service>	デコードされたフレームグラフと、自己値の高い関数を表示	--profile-type（必須）、--filter、--top-functions（デフォルト 20）、--min-node-ratio（デフォルト 0.01）、--max-depth、--show-kernel

• すべてのコマンドは読み取り専用で、-o json ／ -o toon に対応しています。
• すべてのコマンドで --start ／ --end を指定します（デフォルトは now-1h ／ now）。now、now-1h 形式の相対表現、または ISO-8601 タイムスタンプを使用できます。
• --profile-type は cpu、wall、memory-allocation-bytes、memory-allocation-objects、memory-heap-bytes、memory-heap-objects のいずれかです（大文字と小文字は区別されません。MEMORY_HEAP_BYTES も使用できます）。最初に metadata を確認してください。has_data: true のタイプだけが結果を返します。
• --filter は繰り返し指定でき、フィルターは AND で結合されます。 key=v1,v2（いずれかの値）、key!=v1,v2（いずれの値でもない）、 key:exists、key:not-exists を指定します。filters でキーと値を確認してください。
• services --environment は deployment.environment.name と一致します。サービスのランキングで適用される唯一のフィルターです。
• services はランキングをページ分割して取得します。ページがいっぱいになると、次に使用する --offset が CLI に表示されます。--include-time-series を指定しない限り、時系列データは省略されます。
• 大規模なサービスでは flame-graph に約 40 秒かかることがあります。短い --http-timeout は設定しないでください。

調査ワークフロー

1. 負荷の高いサービスを見つける（ユーザーがサービス名を指定している場合は省略します）：

   cx profiling services --category cpu --limit 10 -o json
   cx profiling services --category memory --environment <env> --limit 10 -o json
   

2. サービスで利用可能なプロファイルタイプを確認します：

   cx profiling metadata <service> -o json
   

3. 絞り込みや分割に使える項目（ポッド、バージョン、環境など）を確認します：

   cx profiling filters <service> --profile-type cpu -o json
   

4. 使用量が変化した時期とその原因を特定します。手順 3 の pod またはラベルキーで分割します：

   cx profiling metrics <service> --profile-type cpu --sum-by pod --limit 5 -o json
   cx profiling metrics <service> --profile-type cpu --sum-by service.version --start now-24h -o json
   

5. 原因となっているコードを特定します。まず上位の関数を確認してから、ツリーを確認します：

   cx profiling flame-graph <service> --profile-type cpu --top-functions 10 -o json | jq '.top_functions'
   cx profiling flame-graph <service> --profile-type cpu --filter k8s.pod.name=<pod> \
     --min-node-ratio 0.05 --max-depth 20 -o json
   

出力の読み方

• サービス：cpu 行には total_cpu_seconds ／ total_wall_seconds が含まれます。memory 行には total_memory_allocations_bytes ／ total_heap_bytes が含まれます。 last_active はエポック秒です。
• メトリクス：series は total（バケット合計の総和）で順位付けされ、--limit の件数に切り詰められます。total_series はサーバーが返した系列数です。unit はプロファイルタイプに応じて seconds、bytes、objects のいずれかです。
• フレームグラフ：top_functions はツリー全体にわたって関数とファイルの組み合わせごとに自己値を合計するため、ツリーの切り詰めによる影響を受けません。tree ノードには function、file、line、self、total、self_percent、total_percent、children（total の降順）が含まれます。omitted_subtrees は --min-node-ratio ／ --max-depth によって除外されたノードの数です。サーバーはすでに、合計の 0.1% 未満のノードを除外しています。シンボルのないフレームは、アドレスまたは unknown として表示されます。warnings（例：maxBytes）は、サーバーがプロファイルの読み取りを早期に停止したことを示すため、グラフが対象範囲の一部のみをカバーしている可能性があります。

重要な原則

• まず順位を確認し、その後に掘り下げます — services と metrics は低コストですが、flame-graph は高コストの呼び出しです。実行を依頼する前に、サービス、プロファイルの種類、時間範囲、フィルターを絞り込んでください。
• 大きなツリーは容量も大きくなります — 深いスタック（Java、Scala）では、数百 KB の JSON が生成されることがあります。ツリーには --min-node-ratio を大きくするか、--max-depth を設定してください。または、.top_functions だけを読み取ってください。
• Self と total の違い — self が大きい場合、その関数自体が高負荷です。self が小さいのに total が大きい場合、コストはその関数が呼び出す処理にあります。
• 結果が空でもエラーではありません — 選択したプロファイルの種類または時間範囲にデータがないサービスでは、空の系列または合計がゼロのグラフが返されます。metadata を再確認し、--start の範囲を広げてください。
• プロファイリングデータがない場合 — metadata に has_data: true のプロファイルの種類が表示されない場合、そのサービスはプロファイリングされていません。他のサービス名を探さず、cx-service-catalog または cx-telemetry-querying から回答してください（CPU またはメモリの使用量、発生時刻、該当するポッドを確認）。そのサービスで関数レベルの詳細を確認するには、プロファイリングを有効にする必要があることを伝えてください。
• 複数プロファイルへのファンアウトは、すべてのサブコマンドで使用できます。-p <profile> を繰り返してください。複数指定した場合、結果には profile が付与されます。

関連スキル

• cx-service-catalog — 同じサービスの RED メトリクス（レイテンシ、エラー）を確認できます。ここで見つかった CPU スパイクとレイテンシの悪化を関連付けてください。
• cx-telemetry-querying — プロファイリングで明らかになったサービスまたはポッドのログ、スパン、PromQL メトリクスに切り替えて確認できます（cx logs、cx spans、cx metrics）。
• cx-infra — 高負荷のポッドがインフラストラクチャの問題を示している場合に、ホストとコンテナーの状態を確認できます。