Article by: James W.
アプリにOpenTelemetryを組み込むのに何ヶ月も費やしてきたはずです。それを新しい可観測性バックエンドに移行するためにすべてやり直すという選択肢は現実的ではありません。
SentryのOTLPエンドポイントを使えば、その必要はありません。実際のところ、必要なのは環境変数を2つ設定するだけで、既存のトレースがSentryのトレースエクスプローラーに表示されるようになります。
SentryのOTLPサポートは現在オープンベータです。つまり、すぐに利用を開始できますが、いくつかの既知の制限があります（これについては後ほど説明します）。
なぜOTLPなのか：計測はそのままに、送信先だけを変更する
- すでにOpenTelemetryエコシステムに大きく投資している場合
- 計測の柔軟性を維持したい、またはスタックの他の部分ですでにOpenTelemetryを使用している場合
一方で、ゼロから始めてSentryのみを使用する場合は、ネイティブのSentry SDKの方が、すべてのSentry機能（spanイベント、Session Replay、プロファイリングを含む）を完全にサポートしています。OTLPサポートはまだベータであり、いくつかの制限があります。本ガイドの後半で両者を比較します。
前提条件
開始する前に、以下が必要です。
- Sentry アカウント（無料プランで問題ありません）
- Node.js 18以上がインストールされていること
- Express.jsの基本的な知識
まだSentryプロジェクトを作成していない場合は、ここで作成してください。作成時にはプラットフォームとしてExpressを選択します。DSNの設定手順はスキップして構いません。代わりにOTLPエンドポイントを使用します。
SentryのOTLP認証情報を取得する
Sentryはプロジェクトごとに専用のOTLPエンドポイントを提供しています。
取得方法は以下の通りです。
- 左側のサイドバーでSettingsをクリックします。
- SettingsサイドバーのOrganizationセクションでProjectsをクリックします。
- 一覧から対象のプロジェクトを見つけてクリックし、プロジェクト設定を開きます。
- プロジェクト設定のサイドバーで、SDK Setupセクション内のClient Keys（DSN）をクリックします。
- OpenTelemetryタブを選択し、ExpandボタンをクリックしてすべてのOTLPエンドポイントの値を表示します。
このタブは開いたままにしておいてください。次のステップで以下の値を使用します。
- OTLP Traces Endpoint：Sentryがトレースを受信するURL（例：https://o{ORG_ID}.ingest.us.sentry.io/api/{PROJECT_ID}/integration/otlp/v1/traces）
- OTLP Traces Endpoint Headers：認証ヘッダーの値。x-sentry-auth=の後ろにある値のみをコピーします（例：sentry sentry_key={YOUR_PUBLIC_KEY}）。デモアプリのinstrument.jsファイルでは、この値がx-sentry-authヘッダーとして送信されます。ヘッダー名ではなく、値のみを指定します。
スターターアプリをクローンする
以下のコマンドを実行して、書籍レコメンドアプリをクローンします。
このアプリには以下が含まれています。
- OpenTelemetry SDK（すでに設定済み）
- コード全体にわたるカスタムトレーシングスパン
- マルチレベルのトレース計測（データベースクエリ、API呼び出し、並列処理）
SentryをOTLPの送信先として設定する
プロジェクトのルートに.envファイルを作成します。
プレースホルダーの値を実際のSentry認証情報に置き換えてください。OTEL_SERVICE_NAMEは、後でSentry上でトレースをフィルタリングする際に役立ちます。
これで完了です。たった2行の設定で、OpenTelemetryをSentryに接続できました。
トレースを生成して、Sentryに表示されるのを確認する
アプリケーションを起動します。
次のような結果が表示されるはずです。
トレースを生成する
新しいターミナルウィンドウを開き、書籍レコメンドを作成するためのリクエストを送信します。
トレースをSentryで確認する
では、このトレースがSentryのTracesビューでどのように表示されるか見てみましょう。
- Sentryのプロジェクトを開きます。
- 左側のサイドバーで「Explore」に移動し、「Traces」をクリックします。
スパンのサンプルが表示されたSentryのTracesページ
このページには、トレースから収集されたスパンの一覧が表示されます。各行は1つのスパンを表し、その実行時間と説明が確認できます。「Trace Samples」タブをクリックすると、完全なトレースの表示に切り替えることができます。
すべてのスパンが展開されたトレースを表示する「Trace Samples」タブ
トレースをクリックすると、ウォーターフォールビューが開きます。ここでは、ネストされた処理や並列処理を含む、リクエスト全体の流れをマルチレベルのトレースとして確認でき、それぞれの処理にどれくらい時間がかかっているかも分かります。
スパン属性パネルが表示されたトレースのwaterfallビュー
waterfallビューを使うと、どの処理に時間がかかっているのかを直感的に把握でき、どの非同期処理が遅延の原因になっているのかを推測する必要がなくなります。
例えば、getUserProfileスパンには次のような属性が含まれています。
- action: SELECT
- category: db
- db.operation: SELECT
- db.system: postgresql
これらの属性により、トレースを検索可能になります。ユーザーIDやデータベース操作、あるいは追加したカスタム属性でトレースをフィルタリングできます
OpenTelemetryの計測の仕組み
アプリがどのようにトレースを生成しているのかを見てみましょう。ここでは、同じパターンを自分のアプリでも再利用できるよう、内部で何が行われているのかを説明します。
OpenTelemetry SDKの初期化
instrument.jsファイルでは、OpenTelemetry SDKをセットアップし、OTLPエクスポーターを設定しています。
主なポイントは以下の通りです。
- OTLPTraceExporter は、トレースをSentryのOTLPエンドポイントへ送信します。
- NodeSDK は、自動計測を含めてOpenTelemetryを初期化します。
- getNodeAutoInstrumentations() は、HTTPリクエストやデータベース呼び出しなどの処理を自動的にトレースします。
カスタムスパン
index.jsファイルでは、最初にinstrument.jsを読み込み、その後でビジネスロジックに対応するカスタムスパンを作成します。
データベースクエリ用のスパンは、次のように作成します。
startActiveSpanメソッドは新しいスパンを作成し、それを「アクティブなスパン」として設定します。この関数内で作成された子スパンは、自動的にこのスパンの子として関連付けられます。
ネストされたスパン
これにより、Sentryのwaterfallビューで見たようなネスト構造が作られます。
並列処理
同時に実行される処理については Promise.all を使用します。
Sentryではこれらのスパンがwaterfallビュー上で並列に実行されている様子が表示されるため、どの処理を最適化すべきかが明確になります。
OTLPとネイティブSentry SDKの比較
すでにOpenTelemetryを使用している場合は、無理に移行する必要はなく、適切なタイミングまでそのまま使い続けることができます。
一方で、新規に始める場合でSentryのみを使うのであれば、ネイティブSDKの方がより多くの機能を利用でき、設定もシンプルです。ここでは、それぞれの実装の違いを見ていきます。
セットアップと設定
OTLP：
ネイティブSentry SDK：
OTLPを使うべき場合
以下に当てはまる場合は、OpenTelemetry + OTLPの利用が適しています。
- すでにコードベースにOpenTelemetryの計測が組み込まれている場合
- 複数の可観測性バックエンドにトレースを送信している場合
- ベンダーに依存しない計測を維持したい場合
- OpenTelemetryを標準で使用するAIやLLMフレームワークと連携する場合
- トレース処理にOpenTelemetry Collectorを使用している場合
ネイティブSentryを使うべき場合
以下に当てはまる場合は、ネイティブのSentry SDKが適しています。
- 既存の計測がなく、新規に始める場合
- 可観測性バックエンドとしてSentryのみを使用する場合
- OTLPベータで制限されている機能（spanイベント、完全なspanリンクサポート、検索可能な配列属性など）が必要な場合
- Sentryのエラートラッキングやセッションリプレイとの自動連携を利用したい場合
既知の制限（オープンベータ）
本記事執筆時点では、SentryのOTLPサポートはオープンベータ段階であり、いくつか未対応の点があります。主な注意点は以下の通りです。
イベントを追跡する必要がある場合は、スパン属性を使用するか、別のスパンとして作成してください。
スパンリンクのサポートは限定的
配列属性のサポートも限定的
配列属性もスパンリンクと同様の扱いです。Sentryには取り込まれて表示されますが、検索クエリや集計には使用できません。
参考資料
OpenTelemetryトレースに関するFAQ
■ なぜトレースがSentryに表示されないのですか？
.envに設定したOTLPエンドポイントとヘッダーが、Settings → Client Keys（DSN）→ OpenTelemetry（OTLP） の値と一致しているか確認してください。トレースは送信後、表示されるまでに30〜60秒ほどかかる場合があります。また、OpenTelemetryのトレーシングが初期化されているか、コンソールログも確認してください。
エクスポーターがデータを送信しているか確認するには、instrument.jsに以下を追加してデバッグログを有効化します。
さらに詳しくは、OpenTelemetryのトラブルシューティングガイドを参照してください。
■ なぜスパンがネストされずフラットに表示されるのですか？
startSpanではなくstartActiveSpanを使用している可能性があります。アクティブスパンは、そのスコープ内で作成される子スパンの親として機能します。
■ トレーシングによるメモリ使用量を減らすにはどうすればよいですか？
サンプリングレートを下げてください。本番環境で100%のトレースを収集する必要はほとんどありません。以下を.envに追加すると、10%のみサンプリングされます。
■ スパンにもっとコンテキストを追加するにはどうすればよいですか？
span.setAttribute() を使用して、ユーザーID、リクエストID、フィーチャーフラグなどの関連データを付加できます。コンテキストが多いほど、Sentryでのフィルタリングやデバッグが容易になります。
■ アプリ内の遅い処理を見つけるにはどうすればよいですか？
ボトルネックと思われる箇所にスパンを追加し、Sentryのwaterfallビューで処理時間を確認します。
■ トレースデータに対してアラートを設定できますか？
はい。Sentryのアラート機能を使えば、パフォーマンスの閾値超過やエラーパターンに基づいて通知を受け取ることができます。
■ 複数サービスにまたがるリクエストをトレースできますか？
はい。OpenTelemetryの自動コンテキスト伝播により、追加の計測なしで対応できます。
Original Page: Send your existing OpenTelemetry traces to Sentry
IchizokuはSentryと提携し、日本でSentry製品の導入支援、テクニカルサポート、ベストプラクティスの共有を行なっています。Ichizokuが提供するSentryの日本語サイトについてはこちらをご覧ください。またご導入についての相談は「お問い合わせ」からお気軽にお問い合わせください。
