sentry-otel-exporter-setup

Sentry OTel Exporter のセットアップ

用語：「Sentry 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
- [ ] Step 8: Enable trace connectedness with OTLPIntegration (Python/Ruby/Node.js)

ステップ 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 での決定に従う）

exporters: セクションに sentry エクスポーターを追加し、適切なパイプライン（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 の org slug：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 "<config_file>":/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 "<config_file>":/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 でログを確認します。

ステップ 8：OTLPIntegration でトレースの関連付けを有効にする

ユーザーのアプリケーションが Sentry SDK（Python、Ruby、または Node.js）を使用している場合は、 OTLPIntegration を有効にすることを推奨してください。 これにより、トレースの関連付けが可能になります。OTel のトレースを Sentry のエラー、ログ、 cron、メトリクスに関連付け、自動的に分散トレーシングの伝搬を設定します。

このステップを行わない場合、コレクター経由で送信されたトレースは Sentry に表示されますが、 同じサービスからの他の Sentry イベント（エラー、ログ）には関連付けられません。

ユーザーに次のように尋ねてください：アプリケーションでは Sentry Python SDK、Sentry Ruby SDK、または Sentry Node.js SDK を使用していますか？

• Python：以下の Python の設定手順に従います
• Ruby：以下の Ruby の設定手順に従います
• Node.js：以下の Node.js の設定手順に従います
• いずれも使用していない／その他の SDK：このステップはスキップします。 OTLPIntegration によるトレースの関連付けは、現在 Python、Ruby、Node.js で利用できます。

Python OTLPIntegration

ドキュメント：https://docs.sentry.io/platforms/python/integrations/otlp/

1. 追加パッケージをインストールします：

pip install "sentry-sdk[opentelemetry-otlp]"

2. 既存の sentry_sdk.init() 呼び出しに OTLPIntegration を追加し、 collector_url にコレクターの OTLP トレースエンドポイントを設定します：

from sentry_sdk.integrations.otlp import OTLPIntegration

sentry_sdk.init(
    dsn="___PUBLIC_DSN___",
    integrations=[
        OTLPIntegration(collector_url="http://localhost:4318/v1/traces"),
    ],
)

コレクターの実際の OTLP HTTP エンドポイントを使用してください。 ローカルで実行している場合のデフォルトは http://localhost:4318/v1/traces です。

Ruby OTLPIntegration

ドキュメント：https://docs.sentry.io/platforms/ruby/integrations/otlp/

1. Gemfile に gem を追加します：

gem "sentry-opentelemetry"
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"
gem "opentelemetry-instrumentation-all"

2. bundle install を実行します

3. OpenTelemetry のインストルメンテーションを設定します：

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

4. 既存の Sentry.init ブロックで OTLP を有効にし、collector_url にコレクターの OTLP トレースエンドポイントを設定します：

Sentry.init do |config|
  config.dsn = "___PUBLIC_DSN___"
  config.otlp.enabled = true
  config.otlp.collector_url = "http://localhost:4318/v1/traces"
end

コレクターの実際の OTLP HTTP エンドポイントを使用してください。 ローカルで実行している場合のデフォルトは http://localhost:4318/v1/traces です。

Node.js OTLPIntegration

ドキュメント：https://docs.sentry.io/platforms/javascript/guides/node/

1. 軽量な Sentry SDK と OpenTelemetry の依存関係をインストールします：

npm install @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

2. OTel と Sentry をまとめて設定するインストルメントファイル（instrument.mjs）を作成します：

import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import * as Sentry from '@sentry/node-core/light';
import { otlpIntegration } from '@sentry/node-core/light/otlp';

const provider = new NodeTracerProvider();
provider.register();

Sentry.init({
  dsn: '___PUBLIC_DSN___',
  integrations: [
    otlpIntegration({
      collectorUrl: 'http://localhost:4318/v1/traces',
    }),
  ],
});

3. --import フラグを付けてアプリを起動します：

node --import ./instrument.mjs app.mjs

コレクターの実際の OTLP HTTP エンドポイントを使用してください。 ローカルで実行している場合のデフォルトは http://localhost:4318/v1/traces です。

otlpIntegration の使用時は tracesSampleRate を設定しないでください。サンプリングは OTel が制御します。 設定すると、OTLP の経路と競合します。

トラブルシューティング

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