observability-onboarding

オブザーバビリティのオンボーディング

Elastic Distribution of OpenTelemetry（EDOT）を使用してアプリケーションを計装し、テレメトリーが届いたことを確認します。計装の変更は作業の半分にすぎません。アプリケーションが完璧に設定されていても、何も出力しないことがあります。そのため、このスキルでは設定の差分を見て成功と判断するのではなく、Elasticsearch にクエリを実行してサービスのデータを確認します。

対象範囲は、EDOT SDK を使用したアプリケーションの計装です。EDOT Collector のデプロイ、ファイルやインフラストラクチャからのログ収集、Elastic Agent、Fleet、またはインテグレーションパッケージを通じたデータのオンボーディングは別の取り込み経路であり、このスキルでは扱いません。

テレメトリーが流れるようになったら、サービスの健全性評価には observability-sre-triage スキル、Kubernetes レイヤーの障害調査には observability-k8s-investigation、新しいシグナルに対する SLO とアラートの定義には observability-service-reliability、GenAI やエージェント型ワークロードには observability-llm-obs スキルを使用します。

環境設定

このスキルでは、Elasticsearch の操作に elastic CLI を使用します。 elastic CLI がインストールされていない場合は、何に使用するのかをユーザーに伝えてください。認証情報を推測したり、HTTP API を直接呼び出したり、ほかの回避策を試したりしないでください。

このスキルでは、HTTP の省略記法（例：GET /、GET /_cat/indices、GET /{index}/_mapping、GET /{index}/_settings/index.mode、POST /_query）で操作を示します。このドキュメント末尾の操作表に、各省略記法に相当する elastic CLI コマンドを記載しています。HTTP API を直接呼び出すのではなく、必ず CLI を使用してください。

クラスターにアクセスできない場合の分析

上記の CLI チェックで制限されるのは クラスターへのクエリ であり、分析ではありません。ユーザーが質問の中ですでに根拠（メトリクス値、件数、ステータスの理由、ログ行、アラートペイロード、設定）を提示している場合は、その根拠に基づいて判断してください。

ユーザーから提供されていないデータが本当に必要な場合は、何をどのように確認するかを伝え、判断に必要な具体的なクエリ、インデックス、フィールドを挙げてから、CLI のセットアップを依頼してください。確認内容を示す回答はクラスターにアクセスできなくても役立ちますが、セットアップを依頼するだけでは不十分です。

このスキルで Elasticsearch とやり取りするのは検証ステップのみで、その際は POST /_query を実行します。それ以外はすべて、ユーザーのワークスペース内のアプリケーションコードと設定を編集します。

達成すべき作業

• サービスに新たな計装が必要か、従来の Elastic APM エージェントからの移行が必要かを判断する
• サービスの言語とランタイムに応じた EDOT 設定を適用する
• テレメトリーの送信先を正しい OTLP エンドポイントに設定し、APM Server の URL は使用しない
• トレース、メトリクス、ログが、想定した service.name で Elasticsearch に取り込まれていることを確認する
• 計装済みのサービスが何も報告しない、または間違ったエージェントから報告している場合に原因を調査する

出力に関する規律

このスキルに基づくすべての応答に適用されます。

• 編集を実施してください。 言語、現在のエージェント、送信先が判明している場合は、変更を適用してください。計画を説明してファイルごとに承認を求めないでください。判断を本当に推測できない場合にのみ質問してください。
• ドキュメントをそのまま大量に貼り付けないでください。 関連ページへのリンクを示し、このサービスに当てはまるルールを 2～3 点説明してください。セットアップガイド全体を回答に貼り付けるのは不適切です。
• 成功を報告する前に検証してください。 成果は「正しく設定されている」ことではなく、「テレメトリーが届いている」ことです。検証結果が 0 件なら、サービスが報告していないと伝え、最も可能性の高い原因を示してください。
• 根拠を超えて推測しないでください。 検証クエリが空だったという事実だけでは、原因は複数考えられます。原因を断定せず、最も可能性の高いものと、ほかの原因と見分ける方法を挙げてください。
• 結果で締めくくってください。 「次にダッシュボードも設定しましょうか？」など、末尾で追加作業を提案しないでください。後続作業は推奨事項の一覧に、推奨として記載してください。

プロセス：リクエストの経路を判断する

1. 言語とランタイムを特定します。 プロジェクトの依存関係マニフェスト（pom.xml または build.gradle、 requirements.txt または pyproject.toml、*.csproj、composer.json）を確認します。どの言語のリファレンスを開くかを判断します。 また、プロセスの起動方法（Dockerfile の ENTRYPOINT、Kubernetes の Pod 仕様、systemd ユニットなど）も確認します。エージェントはその場所にアタッチされ、環境変数もそこで設定する必要があります。

   ランタイム	リファレンス	EDOT のアタッチ方法
   Java	references/java.md	-javaagent: フラグまたは JAVA_TOOL_OPTIONS
   Python	references/python.md	opentelemetry-instrument エントリーポイントラッパー
   .NET	references/dotnet.md	起動時の builder.AddElasticOpenTelemetry()
   PHP	references/php.md	OS パッケージでネイティブ拡張機能を導入し、その後プロセスを完全に再起動

   一覧にない言語の場合も同じ方針に従います。必要な設定と次の検証手順は言語に依存しません。アタッチ方法については、上流の EDOT SDK ドキュメントを参照してください。

2. 従来の Elastic APM エージェントを検出します。 インストルメンテーション経路と移行経路のどちらを選ぶかを判断します。各言語のリファレンスには識別マーカーが記載されています。共通するものとして、ELASTIC_APM_* 環境変数や言語固有の Elastic APM パッケージがあります。 識別マーカーが1つでも存在する場合は、移行経路を選択してください。EDOT を重ねて導入しないでください。

3. テレメトリの送信先を確定します。 OTEL_EXPORTER_OTLP_ENDPOINT に指定する URL を判断します。有効な選択肢は2つで、よくある誤りが1つあります。

   • デプロイメントまたは Serverless プロジェクトのElastic 管理 OTLP エンドポイント。正しいデフォルトです。
   • テレメトリが Elastic に届く前にエンリッチ、サンプリング、または分配する必要がある場合は、ユーザーがすでに実行している EDOT Collector。
   • APM Server の URL は使用しないでください。 候補の URL に apm-server が含まれる場合、ポート 8200 で終わる場合、または /intake/v2/events パスがある場合、それは従来の取り込みエンドポイントであり、EDOT では使用できません。移行経路では、これが最もよくある間違いです。以前の ELASTIC_APM_SERVER_URL の値を引き継いではいけません。

4. 以下の共通設定を適用してから、言語別リファレンスに従います。 共通ルールはすべてのランタイムで同じです。リファレンスでは言語固有の内容のみを扱います。

5. 検証します。 設定だけで成功を報告せず、検証手順を実行してください。

必須の設定

すべての EDOT SDK で共通です。環境変数を正確に 3 つ設定します。

変数	値
OTEL_SERVICE_NAME	サービス名です。Elasticsearch では service.name になり、ほかのすべての Observability スキルがサービスを見つけるために使われます。
OTEL_EXPORTER_OTLP_ENDPOINT	ステップ 3 で解決した、マネージド OTLP エンドポイントまたは EDOT Collector の URL です。
OTEL_EXPORTER_OTLP_HEADERS	認証情報です。Authorization=ApiKey <key> または Authorization=Bearer <token> の形式で指定します。

すべての言語に共通するルールが 2 つあります。

• OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER、OTEL_LOGS_EXPORTER は設定しないでください。 デフォルト値はすでに適切です。これらを設定すると、サービスでトレースは報告されるのに、メトリクスやログが報告されないことがよくあります。
• 同じプロセスで従来の Elastic APM エージェントと EDOT を同時に実行しないでください。両方がインストルメンテーションを行い、一貫性のないトレースが生成されます。削除と置き換えは、同じ変更で行ってください。

プロセス：テレメトリーの到着を確認する

インストルメンテーションまたは移行の変更を行うたびに実行してください。また、インストルメント済みのサービスが見つからないとユーザーから報告された場合の最初の確認手順としても実行してください。デプロイの再起動後、結論を出す前にパイプラインに1〜2分ほど時間を与えてください。

1. サービスのドキュメントが取り込まれていることを確認します。 POST /_query を実行し、OTEL_SERVICE_NAME に設定されたサービス名で絞り込みます。判断するのは、データが到着しているかどうか、またどのシグナルが到着しているかです。

   FROM traces-*,metrics-*,logs-* METADATA _index
   | WHERE @timestamp > NOW() - 15 minutes AND service.name == "<service>"
   | STATS docs = COUNT(*), last_seen = MAX(@timestamp) BY _index
   | SORT docs DESC
   | LIMIT 20
   

   正常な結果では、トレースのデータストリーム、メトリクスのデータストリーム、ログのデータストリームからそれぞれ行が返され、last_seen が直近1〜2分以内になっています。シグナルが欠けている場合は、見た目の問題ではなく診断の手がかりです。トレースのみがあり、メトリクスもログもない場合は、通常、OTEL_*_EXPORTER 変数が設定されています。

2. 何も返されない場合は、サービスがどの名前でレポートしているかを確認します。 結果が空でも、「テレメトリーがまったくない」のか、「別の名前でテレメトリーが到着している」のかは判別できません。OTEL_SERVICE_NAME のタイプミス、または SDK のデフォルト値である unknown_service が原因の可能性があります。サービスのフィルターを外し、実際に何が到着しているかを確認してください。

   FROM traces-*,metrics-*,logs-*
   | WHERE @timestamp > NOW() - 15 minutes
   | STATS docs = COUNT(*), last_seen = MAX(@timestamp) BY service.name
   | SORT docs DESC
   | LIMIT 25
   

   判断するのは、予期しない名前でサービスが表示される場合は OTEL_SERVICE_NAME を修正することです。まったく表示されない場合は、エクスポーターが宛先に到達していません。ルーティング手順のステップ3に戻り、エンドポイントと認証情報を再確認してください。

3. レポーターが別のものではなく EDOT であることを確認します。 これにより、正しい移行と中途半端な移行、標準の OpenTelemetry と EDOT を区別できます。

   FROM traces-*
   | WHERE @timestamp > NOW() - 15 minutes AND service.name == "<service>"
   | STATS spans = COUNT(*) BY telemetry.sdk.language, telemetry.sdk.name, telemetry.distro.name, telemetry.distro.version
   | SORT spans DESC
   | LIMIT 10
   

   EDOT SDK がレポートしている場合、telemetry.distro.name は elastic になります。distro が null で、telemetry.sdk.name == "opentelemetry" の場合、アプリケーションは EDOT ではなく上流の OpenTelemetry SDK を使用しています。1つのサービスに2行表示され、そのうち1行に Elastic distro がなく、または telemetry.sdk.language の値が異なる場合は、複数のエージェントが接続されているか、古いデプロイがまだ稼働しています。

4. 結果のパターンから原因を診断します。

   検証結果	最も可能性の高い原因
   サービスの行がなく、名前もどこにも見つからない	エクスポーターが宛先に到達していない — エンドポイントが間違っているか、認証情報が無効
   サービスが別の名前で表示される	OTEL_SERVICE_NAME が未設定または誤記されている。SDK がデフォルト値にフォールバックした
   トレースのみがあり、メトリクスもログもない	OTEL_*_EXPORTER 変数が設定され、デフォルトが上書きされた
   行はあるが、last_seen が古い	プロセスが終了したか、デプロイがロールバックされた
   1つのサービスに2つの distro 値がある	Classic agent と EDOT の両方が接続されているか、古いレプリカがまだ稼働している

   上記のフィールド名がマッピングにない場合は、テレメトリーに問題があると結論づける前に、GET /<index>/_mapping で利用可能なフィールドを確認してください。

例

「Spring Boot サービスにオブザーバビリティを追加してください」 — pom.xml を読んで Java であることを確認し、co.elastic.apm と ELASTIC_APM_* のマーカーをチェックします。どちらも見つからない場合は、references/java.md の計装手順に従います。コンテナーのエントリーポイントに -javaagent フラグを追加し、 3 つの環境変数を管理対象の OTLP エンドポイントに設定してから、検証クエリを実行し、どのシグナルが届いたかを報告します。

「Elastic APM エージェントから EDOT に移行します。.NET を使用しています」 — これは移行手順です。Elastic.OpenTelemetry と builder.AddElasticOpenTelemetry() を追加する変更と同時に、 Elastic.Apm.* パッケージ、AddAllElasticApm() 呼び出し、appsettings.json の ElasticApm ブロックを削除します。設定はコピーせずに変換してください。特に、ELASTIC_APM_SERVER_URLS を OTLP エンドポイントとして再利用しないでください。ステップ 3 で検証し、 レポートしているディストリビューションが正確に 1 つであることを確認します。

「Python アプリに計装を追加しましたが、Elastic に何も表示されません」 — 設定ではなく、検証プロセスから始めます。ステップ 1 を実行し、結果が空の場合はステップ 2 を実行して、サービスが別の名前でレポートされているか確認します。サービスがまったく見つからない場合、考えられる原因は、ラップされていないエントリーポイント（opentelemetry-instrument がない）と、エンドポイントがまだ APM Server を指していることの 2 つです。より一般的な原因であるエントリーポイントを先に確認してください。

「サービスからトレースは送信されていますが、ログもメトリクスもありません」 — これは OTEL_*_EXPORTER のパターンです。ステップ 1 で確認してください。トレースのデータストリームだけが表示され、ほかは何も表示されません。その後、デプロイから OTEL_TRACES_EXPORTER、 OTEL_METRICS_EXPORTER、または OTEL_LOGS_EXPORTER 変数を削除して、再度検証します。

ガイドライン

• 編集する前に、その言語のセットアップガイドまたは移行ガイドを読んでください。 言語ごとのリファレンスには、信頼できるページへのリンクがあります。ランタイムによってアタッチの仕組みが大きく異なるため、別の言語のパターンを当てはめると、設定が壊れる可能性があります。
• 削除と置き換えは 1 回の変更で行ってください。 クラシックエージェントと EDOT の両方がアタッチされている期間があると、どちらか単独の場合よりも悪い、二重に計装されたトレースが生成されます。
• クラシックエージェントのサーバー URL を引き継がないでください。 ELASTIC_APM_SERVER_URL は APM Server を指します。 OTEL_EXPORTER_OTLP_ENDPOINT は管理対象の OTLP エンドポイントまたは EDOT Collector を指す必要があります。
• 設定する変数は 3 つだけにしてください。 追加の OTEL_* チューニングが妥当な場合もありますが、特にエクスポーター変数はデフォルトのままにしてください。
• 検証結果が空の場合、特定のコンポーネントの障害ではなく、原因不明として扱ってください。 修正を提案する前に、ステップ 2 で原因を切り分けます。
• 認証情報をスキルの出力やコミット済みファイルに記載しないでください。 OTEL_EXPORTER_OTLP_HEADERS はデプロイのシークレット管理機能に設定します。
• 帰属：ここにまとめられた言語別の EDOT ガイダンスは、apm-agent-devs チームが作成したものを元にしています。

操作

HTTP API（略記）	elastic CLI コマンド
GET /	elastic es info
POST /_query	elastic es esql query --format tsv --query '<esql>'
GET /<index>/_mapping	elastic es indices get-mapping --index '<index>'