sentry-otel-exporter-setup

Sentry OTel Exporter のセットアップ

用語：エクスポーターコンポーネントを指す場合は、常に「Sentry Exporter」と大文字で表記してください。

OpenTelemetry Collector を設定して、Sentry Exporter を使用し、トレースとログを Sentry に送信します。

セットアップの概要

このチェックリストをコピーして、進捗を記録してください。

OTel Exporter Setup:
- [ ] Step 1: Check for existing configuration
- [ ] Step 2: Check collector version and install if needed
- [ ] Step 3: Configure project creation settings
- [ ] Step 4: Write collector config
- [ ] Step 5: Add environment variable placeholders
- [ ] Step 6: Run the collector
- [ ] Step 7: Verify setup

ステップ 1：既存の設定を確認する

receivers: を含む YAML ファイルを探して、既存の OpenTelemetry Collector 設定を検索します。また、otel-collector-config.*、collector-config.*、otelcol.* という名前のファイルも確認します。

既存の設定が見つかった場合：ユーザーに、希望する方法を尋ねます。

• 既存の設定を変更する：重複を避けるため、既存のファイルに Sentry Exporter を追加します（推奨）。
• 別の設定を作成する：既存の設定は変更せず、テスト用に新しいファイルを作成します。

**ステップ 2 に進む前に、ユーザーの回答を待ち、選択した方法を記録してください。**以降のワークフローは、この選択によって異なります。

設定が見つからない場合：ステップ 4 で新しい collector-config.yaml を作成することを記録してから、ステップ 2 に進みます。

ステップ 2：Collector のバージョンを確認する

Sentry Exporter を使用するには、otelcol-contrib v0.145.0 以降が必要です。

既存の Collector を確認する

1. which otelcol-contrib を実行して PATH 上にあるか確認するか、プロジェクト内の ./otelcol-contrib を確認します。
2. 見つかった場合は、適切なバージョン確認コマンドを実行し、バージョン番号を解析します。
3. 後続のステップで使用するため、Collector のパスを記録します（PATH 上にある場合は otelcol-contrib、ローカルにある場合は ./otelcol-contrib など）。

既存のバージョン	対応
≥ 0.145.0	ステップ 3 に進みます — 既存の Collector は互換性があります
< 0.145.0	以下のインストールに進みます
未インストール	以下のインストールに進みます

インストール

Collector の実行方法をユーザーに尋ねます。

• バイナリ：GitHub リリースからダウンロードします。Docker は不要です。
• Docker：コンテナとして実行します。Docker のインストールが必要です。

バイナリのインストール

GitHub から最新リリースのバージョンを取得します。

curl -s https://api.github.com/repos/open-telemetry/opentelemetry-collector-releases/releases/latest | grep '"tag_name"' | cut -d'"' -f4

重要：GitHub API が返すバージョンには v のプレフィックスが付きます（例：v0.145.0）。ダウンロード URL のパスには v プレフィックス付きの完全なタグが必要ですが、ファイル名と Docker タグにはプレフィックスなしの数字のみのバージョンを使用します（例：0.145.0）。

ユーザーのプラットフォームを検出して、バイナリをダウンロードします。

1. uname -s と uname -m を実行して、OS とアーキテクチャを検出します。
2. リリース値に対応付けます。
   • Darwin + arm64 → darwin_arm64
   • Darwin + x86_64 → darwin_amd64
   • Linux + x86_64 → linux_amd64
   • Linux + aarch64 → linux_arm64
3. ダウンロードして展開します。

curl -LO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v<numeric_version>/otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz
tar -xzf otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz
chmod +x otelcol-contrib

例：バージョンが v0.145.0 の場合、URL のパスには v0.145.0 を使用しますが、ファイル名には 0.145.0 を使用します。

ユーザーに代わってこれらの手順を実行してください。コマンドを提示するだけにしないでください。

4. ダウンロードした tarball を削除してディスク容量（約 50MB）を節約するかどうか、ユーザーに尋ねてください。
   • 削除する：tarball を削除します。
   • 残しておく：tarball はそのままにします。

**ユーザーの回答を待ってください。**明示的に削除を選んだ場合にのみ削除します。

rm otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz

Docker のインストール

1. docker --version を実行して、Docker がインストールされていることを確認します。
2. GitHub から最新のリリースタグを取得します（上記と同じです）。
3. v プレフィックスなしの数字のみのバージョンを使用して、イメージをプルします。

docker pull otel/opentelemetry-collector-contrib:<numeric_version>

例：GitHub のタグが v0.145.0 の場合は、docker pull otel/opentelemetry-collector-contrib:0.145.0 を使用します。

docker run コマンドは、設定ファイルを作成した後のステップ 6 で使用します。

ステップ 3：Sentry プロジェクト作成の設定

Sentry プロジェクトの自動作成を有効にするか、ユーザーに確認します。どちらの選択肢も推奨しないでください。

• はい：service.name からプロジェクトを作成します。Sentry 組織に少なくとも 1 つのチームが必要です。新しく作成されるプロジェクトはすべて、最初に見つかったチームに割り当てられます。作成中に初期データが破棄される場合があります。
• いいえ：テレメトリが到着する前に、Sentry にプロジェクトが存在している必要があります。

ステップ 4 に進む前に、ユーザーの回答を待ってください。

ユーザーが「はい」を選んだ場合：エクスポーターはすべてのプロジェクトをスキャンし、最初に見つかったチームを使用することを警告します。自動作成されるプロジェクトはすべて、そのチームに割り当てられます。まだチームがない場合は、先に Sentry でチームを作成するよう案内してください。

ステップ 4：Collector 設定ファイルの作成

ステップ 1 での決定を使用します。既存の設定ファイルを変更する選択をした場合は、そのファイルを編集します。別の設定ファイルを作成する選択をした場合は、新しいファイルを作成します。ステップ 5 と 6 で使用するため、設定ファイルのパスを記録してください。

Sentry Exporter のドキュメントから最新の設定を取得します。

• 設定例（テンプレートとして使用）：https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/example-config.yaml
• 完全な仕様（利用可能なすべてのオプション）：https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/spec.md

WebFetch を使用して設定例を取得し、開始用のテンプレートとして使用します。ユーザーが設定例にない高度なオプションを必要とする場合は、仕様を参照してください。

既存の設定ファイルを編集する場合（ステップ 1 での決定に従う）

sentry エクスポーターを exporters: セクションに追加し、適切なパイプライン（traces、logs）に含めます。ユーザーからの依頼がない限り、他のエクスポーターを削除または変更しないでください。

新しい設定ファイルを作成する場合（ステップ 1 での決定に従う）

取得した設定例を基に collector-config.yaml を作成します。認証情報には環境変数の参照（${env:SENTRY_ORG_SLUG}、${env:SENTRY_AUTH_TOKEN}）を使用してください。

ユーザーがステップ 3 で自動作成を選択した場合は、sentry エクスポーターに auto_create_projects: true を追加します。

Debug Exporter の追加（推奨）

セットアップ中のトラブルシューティング用に、verbosity: detailed を指定した debug エクスポーターをパイプラインに追加します。これにより、すべてのテレメトリがコンソールに記録されます。セットアップが検証できたら削除してください。

ステップ 5：環境変数のプレースホルダーを追加する

Sentry Exporter には、2 つの環境変数が必要です。ユーザー自身が後で入力するプレースホルダー値を追加します。実際の認証情報は絶対に追加しないでください。

言語上の制約：「認証情報を追加する」「環境変数を追加する」「トークンを追加する」と述べる場合は、これらがプレースホルダーであることを必ず明記してください。ユーザーが後で入力することも、必ず明確にしてください。

次のようには言わないでください：

• 「環境変数を追加します」
• 「.env に認証情報を追加します」
• 「Sentry の認証トークンを追加します」

代わりに、次のように言ってください：

• 「入力していただくための環境変数のプレースホルダーを追加します」
• 「プレースホルダー値を追加します。実際の認証情報に置き換えてください」
• 「プレースホルダー値で環境変数のキーを設定します」

glob **/.env を使って、プロジェクト内に既存の .env ファイルがないか検索します。必ずユーザーに使用するファイルを尋ねてください。コンテキストから推測したり、開いているファイルを見て決めたりしないでください。

見つかった選択肢を提示します：

• [見つかった .env ファイルのパス]：既存のファイルに追加（見つかった各パスを列挙）
• ルートに新規作成：プロジェクトのルートに .env を作成

**ユーザーが明示的に選択するまで待ってください。**選択されるまで先に進んではいけません。ステップ 5（検証）とステップ 6（実行）で使用するため、環境変数ファイルのパスを記録します。

選択したファイルに、次のプレースホルダー値を追加します：

SENTRY_ORG_SLUG=your-org-slug
SENTRY_AUTH_TOKEN=your-token-here

プレースホルダーを追加した後、Sentry で実際の値を取得する方法をユーザーに説明します：

1. Sentry の組織スラッグ：Sentry で Settings → Organization Settings → Organization Slug に移動します。これはサブドメインでもあります（例：https://myorg.sentry.io の myorg）。
2. Sentry の認証トークン：Sentry で Internal Integration を作成します。
   • Sentry で Settings → Developer Settings → Custom Integrations に移動します。
   • Create New Integration をクリックし、Internal Integration を選択します。
   • 権限を設定します：
     • Organization: Read — 必須
     • Project: Read — 必須
     • Project: Write — auto_create_projects を使用する場合のみ必須
   • 保存した後、Create New Token をクリックしてトークンをコピーします。

選択した .env ファイルが .gitignore に含まれていることを確認します。

ユーザーが認証情報を設定するまで待つ

値の取得方法を説明した後、ユーザーに .env ファイルを更新したら知らせるよう依頼します：

• はい、認証情報を設定しました：コレクターの検証と実行に進みます。
• まだです：.env ファイルの更新が終わるまで待ちます。

ユーザーが「まだです」を選択した場合は、待ってからもう一度尋ねます。認証情報の設定が確認されるまで、ステップ 6 に進まないでください。

設定を検証する

認証情報が設定されたら、ステップ 2 で選んだインストール方法に応じた適切な方法で設定を検証します。

ステップ 1 の設定ファイルのパスを使用します（変更した既存の設定ファイル、または新しい collector-config.yaml のいずれか）。

バイナリの検証

ステップ 2 で記録したコレクターのパスを使用します（PATH 上にある場合は otelcol-contrib、ローカルにある場合は ./otelcol-contrib）。

最初に環境変数を読み込んでから、検証を実行します：

set -a && source "<env_file>" && set +a && "<collector_path>" validate --config "<config_file>"

Docker の検証

注：Docker のボリュームマウントには絶対パスが必要です。<config_file> または <env_file> が相対パスの場合は、$(pwd)/ を先頭に付けてください。すでに絶対パスの場合は、そのまま使用してください。

docker run --rm \
  -v "<absolute_config_path>":/etc/otelcol-contrib/config.yaml \
  --env-file "<env_file>" \
  otel/opentelemetry-collector-contrib:<numeric_version> \
  validate --config /etc/otelcol-contrib/config.yaml

ステップ 5 で選択した .env ファイルのパスを使用します。

検証に失敗した場合：

1. エラーメッセージを注意深く確認します。
2. 設定ファイルの問題を修正します。
3. もう一度検証を実行します。
4. 検証に合格するまで繰り返します。

検証に合格したら、コレクターを実行する準備ができているかユーザーに尋ねます：

• はい、今すぐ実行してください：ステップ 6 に進み、コレクターを起動します。
• まだです：待ちます。ユーザーは設定を確認したり、先に環境を準備したりする場合があります。

ステップ 6 に進む前に、必ずユーザーの確認を待ってください。

ステップ 6：コレクターを実行する

ユーザーがコレクターを実行する準備ができたことを確認してから、このステップに進んでください。

ユーザーに実行コマンドを提示しますが、自動的に実行しないでください。 ユーザー自身が実行します。

ステップ 2 で選択したインストール方法に応じて、適切なコマンドを提示してください。

先ほど選択した実際のパスを使用してください：

• 設定ファイル：ステップ 1 のもの（既存の設定、または新しい collector-config.yaml）
• 環境変数ファイル：ステップ 5 のもの（ユーザーが選択した .env ファイル）
• コレクターのパス：ステップ 2 のもの（PATH 上にある場合は otelcol-contrib、ローカルにある場合は ./otelcol-contrib）

バイナリ

まず環境変数を読み込んでから、コレクターを実行します：

set -a && source "<env_file>" && set +a && "<collector_path>" --config "<config_file>"

Docker

注：Docker のボリュームマウントには絶対パスが必要です。<config_file> または <env_file> が相対パスの場合は、$(pwd)/ を先頭に付けてください。すでに絶対パスの場合は、そのまま使用してください。

再実行する場合：まず既存のコンテナを停止して削除します：

docker stop otel-collector 2>/dev/null; docker rm otel-collector 2>/dev/null

docker run -d \
  --name otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 13133:13133 \
  -v "<absolute_config_path>":/etc/otelcol-contrib/config.yaml \
  --env-file "<env_file>" \
  otel/opentelemetry-collector-contrib:<numeric_version>

ステップ 2 で取得したものと同じ数値のバージョン（v 接頭辞なし）を使用してください。

コマンドを提示したら、準備ができたときに実行するようユーザーに伝えてから、検証のステップ 7 に進んでください。

ステップ 7：セットアップを検証する

1. コレクターのログを確認し、正常に起動していることを確認します（無効な設定や接続失敗に関するエラーがないこと）
2. Sentry への接続を示すログメッセージを確認します
3. 計装済みサービスからテストテレメトリを送信し、Sentry に表示されることを確認します

成功基準：

• コレクターがエラーなく起動する
• 送信後 60 秒以内に、トレースおよび／またはログが Sentry に表示される

Docker を使用している場合は、docker logs otel-collector でログを確認してください。

トラブルシューティング

エラー	原因	対処方法
"failed to create project"	Project:Write 権限がありません	Sentry で Internal Integration の権限を更新します
"no team found"	組織にチームがありません	自動作成を有効にする前に、Sentry でチームを作成します
"invalid auth token"	トークンの種類が誤っているか、期限切れです	ユーザー認証トークンではなく、Internal Integration トークンを使用します
4317/4318 で "connection refused"	コレクターが実行されていないか、ポートが競合しています	コレクターのログを確認し、ポートが使用可能であることを確認します
環境変数エラーで検証に失敗する	.env ファイルが読み込まれていないか、プレースホルダーが置き換えられていません	.env に実際の認証情報が設定されていて、ファイルが読み込まれていることを確認します
"container name already in use"	前回のコンテナが残っています	docker stop otel-collector && docker rm otel-collector を実行します