All Skills > Feature Setup > OTel Exporter

Sentry OTel Exporter Setup

用語: Exporterコンポーネントを指すときは、常に「Sentry Exporter」と大文字で表記します。

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

Setup Overview

このチェックリストをコピーして進捗を追跡します:

OTel Exporter Setup:
- [ ] ステップ 1: 既存の設定を確認
- [ ] ステップ 2: コレクターのバージョンを確認し、必要に応じてインストール
- [ ] ステップ 3: プロジェクト作成設定を設定
- [ ] ステップ 4: コレクター設定を記述
- [ ] ステップ 5: 環境変数プレースホルダーを追加
- [ ] ステップ 6: コレクターを実行
- [ ] ステップ 7: セットアップを検証
- [ ] ステップ 8: 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: コレクターのバージョンを確認

Sentry Exporterには otelcol-contrib v0.145.0 以上 が必要です。

既存のコレクターを確認

1. which otelcol-contrib を実行してPATHで確認するか、プロジェクト内の ./otelcol-contrib を確認します
2. 見つかった場合、適切なバージョンコマンドを実行してバージョン番号を解析します
3. コレクターパスを記録 (例: PATHの場合は otelcol-contrib、ローカルの場合は ./otelcol-contrib) してあとのステップで使用します

既存のバージョン	操作
≥ 0.145.0	ステップ 3 へスキップ — 既存のコレクターは互換性があります
< 0.145.0	以下のインストールに進みます
インストールされていない	以下のインストールに進みます

インストール

ユーザーにコレクターの実行方法を質問します:

• バイナリ: 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 に進む前にユーザーの回答を待ちます。

ユーザーが「はい」を選択した場合: Exporterがすべてのプロジェクトをスキャンし、見つかった最初のチームを使用することを警告します。すべての自動作成されたプロジェクトはそのチームに割り当てられます。まだチームがない場合は、Sentryで最初にチームを作成する必要があります。

ステップ 4: コレクター設定を記述

ステップ 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 Exporterを追加し、適切なパイプライン (traces、logs) に含めます。ユーザーがリクエストしない限り、他のExporterを削除または変更しないでください。

新しい設定を作成する場合 (ステップ 1 の決定による)

取得した例に基づいて collector-config.yaml を作成します。認証情報は環境変数参照を使用します (${env:SENTRY_ORG_SLUG}、${env:SENTRY_AUTH_TOKEN})。

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

デバッグExporterを追加 (推奨)

セットアップ中のトラブルシューティング用に、verbosity: detailed を使用してパイプラインに debug Exporterを追加します。これはすべてのテレメトリーをコンソールにログします。セットアップが検証されたら削除します。

ステップ 5: 環境変数プレースホルダーを追加

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

言語制約: 明示的に プレースホルダー であると述べずに「認証情報を追加」「環境変数を追加」「トークンを追加」と言わないでください。常にユーザーが後でそれらを入力することを明確にしてください。

言わないでください:

• 「環境変数を追加させてください」
• 「認証情報を .env に追加します」
• 「Sentry認証トークンを追加しています」

代わりに言ってください:

• 「入力するプレースホルダー環境変数を追加します」
• 「プレースホルダー値を追加します — あなたが実際の認証情報に置き換えます」
• 「プレースホルダー値を使用して環境変数キーを設定します」

グロブ **/.env を使用してプロジェクト内の既存の .env ファイルを検索します。どのファイルを使用するかをユーザーに常に質問 — コンテキストから推測したり、開いているファイルに基づいて推測しないでください。

発見されたオプションを表示します:

• [発見された .env ファイルへのパス]: 既存ファイルに追加 (発見された各パスをリストします)
• ルートに新規作成: プロジェクトルートに .env を作成

ユーザーの明示的な選択を待ちます。 選択するまで進まないでください。ステップ 5 (検証) と 6 (実行) で使用する環境ファイルパスを記録します。

選択したファイルにこれらのプレースホルダー値を追加します:

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

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

1. Sentryオーガナイゼーションスラッグ: Sentryで 設定 → オーガナイゼーション設定 → オーガナイゼーションスラッグ に移動します。これはサブドメインでもあります (例: https://myorg.sentry.io の myorg)
2. Sentry認証トークン: Sentryで内部インテグレーションを作成します:
   • Sentryで 設定 → デベロッパー設定 → カスタムインテグレーション に移動
   • 新規インテグレーション作成 → 内部インテグレーション を選択
   • パーミッションを設定:
     • Organization: Read — 必須
     • Project: Read — 必須
     • Project: Write — auto_create_projects を使用している場合のみ必須
   • 保存した後、新規トークン作成 をクリックしてコピー

選択した .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のエラー、ログ、クロン、メトリクスとリンク — し、自動的に分散トレース伝播を設定します。

このステップがないと、コレクターを通じて送信されたトレースは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"	間違ったトークンタイプまたは期限切れ	ユーザー認証トークンではなく内部インテグレーショントークンを使用
"connection refused" on 4317/4318	コレクターが実行されていないか、ポート競合	コレクターログを確認し、ポートが利用可能であることを確認
環境変数エラーで検証が失敗	.env ファイルがロードされていないか、プレースホルダーが置き換えられていない	実際の認証情報が .env にあり、ファイルがソースされていることを確認
"container name already in use"	前のコンテナが存在する	docker stop otel-collector && docker rm otel-collector を実行