observability-service-health

APM サービスの健全性

Observability API、 APM インデックスに対する ES|QL、Elasticsearch API、および（相関分析と APM 固有のロジックには）Kibana リポジトリを使用して、APM サービスの健全性を評価します。SLO、発火中のアラート、ML の異常、スループット、レイテンシ（平均／p95／p99）、エラー率、依存関係の健全性を確認します。

確認する場所

• Observability API（Observability API）：SLO API（Stack | Serverless）を使用して、SLO の定義、ステータス、バーンレート、エラーバジェットを取得します。アラート API （Stack | Serverless）を使用して、サービスのアラートルールとアラートを一覧表示、管理します。必要に応じて、APM annotations API を使用してアノテーションを作成または検索します。
• ES|QL と Elasticsearch： ES|QL（APM メトリクスに ES|QL を使用するを参照）で traces*apm*,traces*otel* および metrics*apm*,metrics*otel* をクエリし、スループット、レイテンシ、エラー率、依存関係に関する集計を確認します。インデックスと検索については、Elasticsearch リポジトリのドキュメントに従って Elasticsearch API（ES|QL の POST _query や Query DSL など）を使用します。
• APM の相関分析： apm-correlations スクリプトを実行し、指定したサービスで高レイテンシまたは失敗したトランザクションと相関する属性を取得します。まず Kibana 内部の APM 相関分析 API を試し、その後 traces*apm*,traces*otel* に対する Elasticsearch の significant_terms にフォールバックします。APM Correlations スクリプトを参照してください。
• インフラストラクチャ： トレース内のリソース属性（k8s.pod.name、container.id、host.name など）を通じて相関付けます。ES|QL／Elasticsearch でインフラストラクチャまたはメトリクスのインデックスをクエリし、CPU とメモリを確認します。OOM と CPU スロットリングは APM の健全性に直接影響します。
• ログ： ログインデックスを service.name または trace.id で絞り込み、ES|QL または Elasticsearch 検索を使用して動作と根本原因を調査します。
• Observability Labs： パターンやトラブルシューティングについては、Observability Labs および APM タグを参照してください。

健全性の基準

利用可能な場合は、以下のすべてのシグナルを総合して健全性を評価します。

シグナル	確認する項目
SLO	バーンレート、ステータス（正常／劣化／違反）、エラーバジェット。
発火中のアラート	サービスまたは依存関係で発生中、もしくは最近発火したアラート。
ML の異常	異常検知ジョブ、およびレイテンシ、スループット、エラー率のスコアと重大度。
スループット	リクエストレート。ベースラインまたは前の期間と比較します。
レイテンシ	平均、p95、p99。SLO の目標値または過去の値と比較します。
エラー率	リクエスト総数に対する失敗リクエスト数。急増や継続的な上昇を確認します。
依存関係の健全性	下流のレイテンシ、エラー率、可用性（ES|QL、API、Kibana リポジトリ）。
インフラストラクチャ	CPU 使用率、メモリ、ポッド／コンテナー／ホストでの OOM と CPU スロットリング。
ログ	状況と根本原因を把握するため、サービスまたはトレース ID で絞り込んだアプリケーションログ。

SLO に違反している、重大なアラートが発火中である、または ML の異常が深刻な劣化を示している場合、そのサービスは健全でないと判断します。インフラストラクチャ（OOM、CPU スロットリング）、依存関係、ログ（サービス／トレースのコンテキスト）と相関付けて、原因を説明し、次の対応を提案します。

APM メトリクスでの ES|QL の使用

Elasticsearch（traces*apm*,traces*otel*、metrics*apm*,metrics*otel*）から APM データをクエリする場合、利用可能であればデフォルトで ES|QL を使用してください。

• 利用可能性： ES|QL は Elasticsearch 8.11+ で利用できます（テクニカルプレビュー。8.14 で GA）。Elastic Observability Serverless Complete tier では常に利用可能です。
• サービスの絞り込み： 必ず service.name（必要に応じて service.environment も）でフィルタリングしてください。@timestamp で時間範囲を指定します。

WHERE service.name == "my-service-name" AND service.environment == "production"
  AND @timestamp >= "2025-03-01T00:00:00Z" AND @timestamp <= "2025-03-01T23:59:59Z"

• パターン例： 時間経過に伴うスループット、レイテンシ、エラー率については、Kibana の trace_charts_definition.ts（getThroughputChart、getLatencyChart、getErrorRateChart）を参照してください。BUCKET(@timestamp, ...) と WHERE service.name == "<service_name>" を使い、from(index) → where(...) → stats(...) / evaluate(...) の順に使用します。
• パフォーマンス： LIMIT n を追加して、行数とトークン使用量を制限してください。傾向のみが必要な場合は、より大きな間隔の BUCKET(@timestamp, ...)（例：1 時間）を優先してください。間隔を細かくすると、処理量と結果のサイズが増加します。

APM 相関スクリプト

トランザクションの一部のサブポピュレーションでのみ高レイテンシや障害が発生している場合は、apm-correlations スクリプトを実行して、それらのトランザクションと相関する属性（例：ホスト、サービスバージョン、ポッド、リージョン）を一覧表示します。このスクリプトはまず Kibana 内部の APM 相関 API を試し、利用できない場合（例：404）は Elasticsearch の traces*apm*,traces*otel* に対する significant_terms にフォールバックします。

# Latency correlations (attributes over-represented in slow transactions)
node skills/observability/service-health/scripts/apm-correlations.js latency-correlations --service-name <name> [--start <iso>] [--end <iso>] [--last-minutes 60] [--transaction-type <t>] [--transaction-name <n>] [--space <id>] [--json]

# Failed transaction correlations
node skills/observability/service-health/scripts/apm-correlations.js failed-correlations --service-name <name> [--start <iso>] [--end <iso>] [--last-minutes 60] [--transaction-type <t>] [--transaction-name <n>] [--space <id>] [--json]

# Test Kibana connection
node skills/observability/service-health/scripts/apm-correlations.js test [--space <id>]

環境： Kibana には KIBANA_URL と KIBANA_API_KEY（または KIBANA_USERNAME／KIBANA_PASSWORD）を使用します。フォールバックには ELASTICSEARCH_URL と ELASTICSEARCH_API_KEY を使用します。調査と同じ時間範囲を指定してください。

ワークフロー

Service health progress:
- [ ] Step 1: Identify the service (and time range)
- [ ] Step 2: Check SLOs and firing alerts
- [ ] Step 3: Check ML anomalies (if configured)
- [ ] Step 4: Review throughput, latency (avg/p95/p99), error rate
- [ ] Step 5: Assess dependency health (ES|QL/APIs / Kibana repo)
- [ ] Step 6: Correlate with infrastructure and logs
- [ ] Step 7: Summarize health and recommend actions

ステップ 1：サービスを特定する

サービス名と時間範囲を確認します。リクエストからサービスを特定し、対象が複数ある場合は、最も関連性の高いサービスを対象にします。traces*apm*,traces*otel* または metrics*apm*,metrics*otel* に対する ES|QL（例：WHERE service.name == "<name>"）か、Kibana リポジトリの APM ルートを使用して、サービスレベルのデータを取得します。ユーザーが時間範囲を指定していない場合は、直近 1 時間を想定します。

ステップ 2：SLO と発報中のアラートを確認する

SLO： SLOs API を呼び出して、サービスの SLO 定義とステータス（レイテンシ、可用性）、健全／劣化／違反の状態、バーンレート、エラーバジェットを取得します。アラート： アクティブな APM アラートを確認するには、/api/alerting/rules/_find?search=apm&search_fields=tags&per_page=100&filter=alert.attributes.executionStatus.status:active を呼び出します。1 つのサービスを確認する場合は、params.serviceName がそのサービスと一致するルールと、params.serviceName がない（全サービス対象の）ルールの両方を含めます。アクティブ状態の確認に .alerts* インデックスをクエリしないでください。SLO 違反やメトリクスの変化と関連付けます。

ステップ 3：ML の異常を確認する

ML 異常検知を使用している場合は、サービスと時間範囲を対象に、ML ジョブの結果または異常レコードを（Elasticsearch ML API またはインデックス経由で）クエリします。重大度の高い異常（レイテンシ、スループット、エラー率）に注意し、異常の時間枠を使ってステップ 4～5 の範囲を絞り込みます。

ステップ 4：スループット、レイテンシ、エラー率を確認する

サービスと時間範囲を指定して、traces*apm*,traces*otel* または metrics*apm*,metrics*otel* に対して ES|QL を使用し、スループット（例：リクエスト数／分）、レイテンシ（平均、p95、p99）、エラー率（失敗数／合計数、または 5xx／合計数）を取得します。例：FROM traces*apm*,traces*otel* | WHERE service.name == "<service_name>" AND @timestamp >= ... AND @timestamp <= ... | STATS ...。前の期間または SLO の目標と比較します。APM メトリクスでの ES|QL の使用を参照してください。

ステップ 5：依存関係の健全性を評価する

traces*apm*,traces*otel*／metrics*apm*,metrics*otel*に対するES|QL（例：下流サービス／スパンの集計）または、依存関係／サービスマップのデータを公開するKibana リポジトリ内の APM ルートハンドラーを使って、依存関係とサービスマップのデータを取得します。サービスと時間範囲について、下流のレイテンシとエラー率を記録し、遅延または障害のある依存関係を原因の候補として挙げます。

ステップ 6：インフラストラクチャおよびログと相関させる

• APM 相関（影響を受けているのが一部のユーザー群のみの場合）：
  node skills/observability/service-health/scripts/apm-correlations.js latency-correlations|failed-correlations --service-name <name> [--start ...] [--end ...]を実行し、相関する属性を取得します。それらの属性で絞り込み、トレースのサンプルまたはエラーを取得して根本原因を確認します。APM Correlations スクリプトを参照してください。
• インフラストラクチャ： トレースのリソース属性（例：k8s.pod.name、container.id、host.name）を使用して、インフラストラクチャ／メトリクスのインデックスをES|QLまたは Elasticsearch で検索し、CPUとメモリを確認します。OOMとCPU スロットリングは APM の健全性に直接影響します。それらの発生時間帯を APM の劣化と相関させます。
• ログ： ログインデックスをES|QLまたは Elasticsearch で検索し、service.name == "<service_name>"またはtrace.id == "<trace_id>"で絞り込み、例外、タイムアウト、再起動などの挙動と根本原因を明らかにします。

ステップ 7：要約して推奨事項を提示する

理由とともに健全性（healthy／degraded／unhealthy）を示し、具体的な次のステップを列挙します。

例

例：特定のサービスに対する ES|QL

WHERE service.name == "<service_name>"と時間範囲で絞り込みます。スループットとエラー率（1 時間ごとのバケット。LIMITで行数とトークン数を制限します）：

FROM traces*apm*,traces*otel*
| WHERE service.name == "api-gateway"
  AND @timestamp >= "2025-03-01T00:00:00Z" AND @timestamp <= "2025-03-01T23:59:59Z"
| STATS request_count = COUNT(*), failures = COUNT(*) WHERE event.outcome == "failure" BY BUCKET(@timestamp, 1 hour)
| EVAL error_rate = failures / request_count
| SORT @timestamp
| LIMIT 500

レイテンシのパーセンタイルと正確なフィールド名については、Kibana のtrace_charts_definition.tsを参照してください。

例：「サービス X は健全ですか？」

1. サービス X と時間範囲を特定します。SLO APIとアラート APIを呼び出し、traces*apm*,traces*otel*／metrics*apm*,metrics*otel*に対してES|QLを実行し、スループット、レイテンシ、エラー率を確認します。依存関係／サービスマップのデータを検索します（ES|QL または Kibana リポジトリ）。
2. SLO のステータス（違反中／悪化中か）、発火中のルール、ML の異常、および依存関係の健全性を評価します。
3. 理由と次のステップ（例：Observability Labs）とともに、「Healthy／Degraded／Unhealthy」で回答します。

例：「サービス Y の動作が遅いのはなぜですか？」

1. サービス Y と遅延が発生している時間範囲を確認します。SLO APIとアラート APIを呼び出し、Y とその依存関係に対してES|QLを実行します。ML の異常検知結果を検索します。
2. ES|QLを使ってレイテンシ（平均値／p95／p99）を前の期間と比較し、依存関係のデータからレイテンシが高い、または障害のある依存関係を特定します。
3. 要約（例：p99 が上昇し、依存関係 Z も高い）し、推奨事項（Z を調査する。レイテンシについては Observability Labs を参照する）を提示します。

例：サービスとインフラストラクチャを相関させる（OpenTelemetry）

スパン／トレースのリソース属性を使って、そのサービスのランタイム（ポッド、コンテナー、ホスト）を特定します。次に、APM の問題が発生した時間帯と同じ時間帯について、それらのリソースの CPU とメモリを確認します。

• サービスのトレースまたはメトリクスから、k8s.pod.name、k8s.namespace.name、container.id、host.nameなどのリソース属性を読み取ります。
• インフラストラクチャ／メトリクスのインデックスをES|QLまたは Elasticsearch で検索し、これらのリソース値とインシデントの時間範囲で絞り込みます。CPU 使用率とメモリ消費量（例：system.cpu.total.norm.pct）を確認し、APM のレイテンシやエラーの急増と一致するOOMKilledイベント、CPU スロットリング、または CPU／メモリの高負荷が継続していないかを調べます。

例：サービスまたはトレース ID でログを絞り込む

特定のサービスまたは単一のトレースの動作を把握するには、ログを適切に絞り込みます。

• サービス別： ログインデックスに対して ES|QL または Elasticsearch 検索を実行し、service.name == "<service_name>" と時間範囲を指定して、サービスのコンテキストにおけるアプリケーションログ（エラー、警告、再起動）を取得します。
• トレース ID 別： 特定のリクエストを調査する場合は、APM トレースから trace.id を取得し、trace.id == "<trace_id>"（またはログスキーマ内の同等のフィールド）でログを絞り込みます。そのトレース ID を持つログからリクエストの全経路を確認でき、障害やレイテンシーの原因を把握するのに役立ちます。

ガイドライン

• traces*apm*,traces*otel*/metrics*apm*,metrics*otel*（8.11+ または Serverless）に対して、service.name（該当する場合は service.environment も）で絞り込み、Observability API（SLO API、アラート API）と ES|QL を使用します。アクティブな APM アラートを確認するには、/api/alerting/rules/_find?search=apm&search_fields=tags&per_page=100&filter=alert.attributes.executionStatus.status:active を呼び出します。1 つのサービスを確認する場合は、両方のルールタイプを評価します。対象サービスに params.serviceName が一致するルールと、params.serviceName がないルール（全サービス対象のルール）です。健全性を判断する前に、どちらもそのサービスに適用されるものとして扱います。現在アクティブなアラートを判断する際に .alerts* インデックスをクエリしないでください。情報源として、上記の Alerting API のレスポンスを使用します。APM の相関分析には apm-correlations スクリプト（APM Correlations スクリプトを参照）を実行します。依存関係やサービスマップのデータには、ES|QL または Kibana リポジトリのルートハンドラーを使用します。Elasticsearch のインデックスと検索の動作については、Elasticsearch リポジトリの Elasticsearch API を参照してください。
• 常にユーザーの時間範囲を使用します。問題が過去のものである場合に「過去 1 時間」と決めつけないでください。
• SLO がある場合は、SLO のステータスとバーンレートを基準に健全性の概要をまとめます。SLO がない場合は、アラート、異常、スループット、レイテンシー、エラー率、依存関係を根拠にします。
• OpenTelemetry 経由で取り込んだアプリケーションメトリクスのみを分析する場合は、効率的なメトリクスクエリのために ES|QL の TS（時系列）コマンドを使用します。TS コマンドは Elasticsearch 9.3+ で利用でき、Elastic Observability Serverless では常に利用可能です。
• まとめ：簡潔な健全性の判定を 1 つと、根拠および次の手順を箇条書きで示します。