Article by: James W.
もしすでに OpenTelemetry でアプリを計装しているなら、Sentry を使うためにわざわざ外す必要はありません。環境変数を2つ設定するだけで、Logs を Sentry に送れるようになります。SDK の変更も再計装も不要です。この記事では、サンプルアプリでの設定方法とネイティブ Sentry SDK を使うべきケースについてご紹介します。
なぜネイティブ SDK ではなく OTLP を使うのか
OTLP の主な利点は、ログ記録のコードを特定のオブザーバビリティ基盤から切り離したままにできることです。数行の設定を変更するだけで、ログの送信先を切り替えられます。
次のような場合に役立ちます。
- すでに OpenTelemetry によるロギングを導入している
- ログを複数のバックエンドに送りたい
- ベンダー中立な計装が必要である
- OpenTelemetry をデフォルトで使用する AI や LLM のフレームワークを扱っている
- より広い OpenTelemetry のエコシステムを活用したい
一方、ゼロから導入するのであれば、必要なのが Sentry のみの場合は ネイティブの Sentry SDK のほうが適しています。ネイティブ SDK では、Logs からの Issue 作成、Session Replay との統合、自動的な Breadcrumbs、組み込みのエラー相関といった機能を利用できます。OTLP エンドポイント経由で OpenTelemetry の Traces や Logs を Sentry に取り込む機能は現時点ではまだベータ版であり、まだこうした統合機能は備わっていません。
ガイドの前提条件
始める前に、以下が必要です。
- Sentry アカウント（無料プランで利用できます）
- Node.js 18 以降がインストールされていること
- Express.js の基本的な知識
まだ Sentry のプロジェクトを作成していない場合は、この時点で作成してください。プラットフォームには Express を選択します。今回は OTLP エンドポイントを使うため、DSN の設定手順はスキップして問題ありません。
Sentry の OTLP 認証情報を取得する
Sentry では Logs 用と Traces 用にそれぞれ別の OTLP エンドポイントが用意されています。このガイドでは、Logs エンドポイントに焦点を当てます。
OTLP の認証情報を確認する手順は以下のとおりです。
- 左側のサイドバーで Settings をクリックします。
- Settings サイドバーの Organization セクションで Projects をクリックします。
- 一覧から対象のプロジェクトを見つけてクリックし、プロジェクト設定を開きます。
- プロジェクト設定のサイドバーで、SDK Setup セクションの Client Keys (DSN) をクリックします。
- OpenTelemetry タブを選択します。Expand ボタンをクリックすると、すべての OTLP エンドポイントの値を確認できます。
このタブは開いたままにしておいてください。次の手順で、以下の値を使用します。
- OTLP Logs Endpoint: Sentry が Logs を受け取る URL
（例:https://o{ORG_ID}.ingest.us.sentry.io/api/{PROJECT_ID}/integration/otlp/v1/logs） - OTLP Logs Endpoint Headers: 認証用ヘッダー
（例:x-sentry-auth=sentry sentry_key={YOUR_PUBLIC_KEY}）
一点、知っておくと良いことがあります。多くの OTLP エクスポーターは、ヘッダーを完全な文字列としてではなく、生のキー／値ペアとして受け取ることを想定しています。そのためアプリ側でこのヘッダーをパースする必要があります。この設定は、以下のセットアップで対応します。
OpenTelemetry アプリを Sentry に接続する
ここでは、すでに OpenTelemetry によるロギング計装が組み込まれている、サンプルの決済処理サービスを使います。ロギングのコード自体に手を加える必要はありません。Sentry の OTLP エンドポイントを送信先として指定するだけです。
スターターアプリをクローンする
以下のコマンドを実行して、決済処理アプリをクローンします。
このアプリには設定済みの OpenTelemetry SDK、アプリ全体にわたる構造化ログ、複数のログ重大度レベル（INFO、DEBUG、WARN、ERROR）、そして各ログエントリに付与された豊富なログ属性が含まれています。
Sentry を OTLP の送信先として設定する
プロジェクトのルートに .env ファイルを作成します。
次に、.env を編集し、前の手順で確認した Sentry の OTLP 認証情報を追加します。
プレースホルダーを実際の Sentry 認証情報に置き換えてください。OTEL_SERVICE_NAME を設定しておくと、あとで Sentry 上でサービス単位に Logs を絞り込めるようになります。
これで完了です。設定は2行だけで、OpenTelemetry の Logs が Sentry に送られるようになります。
連携をテストする
アプリを起動します。
次に、.env を編集し、前の手順で確認した Sentry の OTLP 認証情報を追加します。
Sentry で Logs を確認する
では、これが Sentry の Logs ビューでどのように見えるか確認してみましょう。
- Sentry のプロジェクトを開きます。
- 左側のサイドバーで Explore に移動し、Logs をクリックします。
決済処理ワークフローから送られたログエントリの一覧が表示されます。各ログには、タイムスタンプ、重大度インジケーター（色付きのドット）、メッセージが表示されます。
ログ属性を確認する
任意のログエントリをクリックして展開すると、そのログに含まれるすべての属性を確認できます。
たとえば、High-risk transaction detected というログには、次のような属性が含まれています。
fraud_check.score: 97.98fraud_check.threshold: 70fraud_check.reason: unusual_amount_patternuser.id: user123transaction.id: txn_1762164637756_0hscczobmseverity: warn
これらはすべて検索可能です。任意の属性をフィルターとして追加するには、その項目にカーソルを合わせ、オーバーフローメニュー（三点リーダー）をクリックして、Add to filter を選択します。
logger.emit() を呼び出すたびに、重大度レベル、メッセージ本文、属性のセットを渡します。ログを検索可能にしているのはこの属性です。ここに追加するコンテキストが多いほど、あとで特定のイベントを見つけやすくなります。
ログ重大度レベル
OpenTelemetry では、6 つの重大度レベルがサポートされています。
豊富な属性を追加する
追加する属性が多いほど、問題のデバッグはしやすくなります。以下は、不正検知の処理経路における例です。
これらの属性はすべて Sentry 上で検索できるため、ログ本文を一つひとつ確認しなくても、特定のトランザクションをすばやく見つけられます。
OTLP とネイティブ Sentry SDK の違い
どちらの方法でも Logs を Sentry に送信できます。違いは自動的に利用できる機能にあります。
セットアップと設定
OTLP
Sentry.logger を使うには、Sentry JavaScript SDK v9.41.0 以上が必要である点に注意してください。
Logs の出力
OTLP
ネイティブ Sentry SDK
OpenTelemetry では、severityNumber と severityText の両方を手動で指定します。一方、Sentry SDK では、呼び出すメソッド（info()、warn() など）に基づいて、その両方が自動的に推論されます。さらに SDK は追加の設定をしなくても、Logs をエラー、トランザクション、ユーザーセッションに自動で関連付けます。
ログレベル
OTLP
ネイティブ Sentry SDK
次にできること
これで、OpenTelemetry の Logs を Sentry に送れるようになりました。ここからさらに活用する方法をいくつか紹介します。
- Logs にコンテキストを追加する。 属性を多く追加するほど、問題のデバッグはしやすくなります。ユーザー ID、リクエスト ID、トランザクション ID、機能フラグ、その他ビジネス上重要なコンテキストを、各ログエントリに追加してください。
- 属性名に一貫性を持たせる。 標準化された属性名を使うために、OpenTelemetry Semantic Conventions に従ってください。これにより、サービス横断で Logs の一貫性が保たれ、検索もしやすくなります。
- アラートを設定する。 特定のログパターンが現れたときに通知されるよう、Sentry のアラートを設定します。たとえば、ERROR ログが閾値を超えた場合や、高リスクのトランザクションが不正スコアの基準値を超えた場合などです。
- Logs と Traces を組み合わせる。 Traces も Sentry に送っている場合は、Logs と関連付けることで、アプリケーションの挙動をより包括的に把握できます。
OTLP によるロギングのサポートは、現在もオープンベータ段階です。ここに記載されていない制限に遭遇した場合は、GitHub で Issue を作成してください。私たちがその問題を把握するための最も早い方法です。
OTLP Logging に関する FAQ
■どのような場合にネイティブの Sentry SDK を使うべきですか？
ゼロから始める場合で、Sentry が唯一のオブザーバビリティツールであるなら、ネイティブ SDK のほうがより少ない設定で多くの機能を最初から利用できます。追加の設定をしなくても、Sentry プラットフォーム全体とのより密接な統合を利用できます。特に、次のような場合にはネイティブ SDK のほうが適しています。
- 既存の計装がない状態から新しく始める
- オブザーバビリティに Sentry だけを使っている
- Logs からの自動的な Issue 作成が必要である
- Session Replay との統合を使いたい
- エラー、トランザクション、ユーザーセッションとの自動的な相関が必要である
- 配列属性を検索可能にしたい（現状、OTLP ベータでは制限があります）
- Sentry のエラートラッキングや Breadcrumbs との自動統合が必要である
■どのような場合に OTLP を使うべきですか？
OTLP はすでに OpenTelemetry のエコシステムを活用していて、既存の計装を入れ替えたくない場合に適しています。また、複数のバックエンドに Logs を送信したい場合や、コードをベンダー中立に保ちたい場合など、柔軟性が必要なときにも有効です。特に、次のような場合は OTLP を検討するとよいでしょう。
- コードベースにすでに OpenTelemetry によるロギングが入っている
- Logs を複数のオブザーバビリティバックエンドに送信している
- ベンダー中立な計装が必要である
- デフォルトで OpenTelemetry を使う AI や LLM のフレームワークを扱っている
- Logs の処理に OpenTelemetry Collector を使っている
■Logs が Sentry に表示されないのはなぜですか？
まずは認証情報を確認してください。.env ファイルに設定した OTLP エンドポイントとヘッダーが、Settings → Client Keys (DSN) → OpenTelemetry (OTLP) に表示されている値と一致しているかを確認します。認証情報に問題がなさそうであれば、少し待ってみてください。Logs は送信されてから表示されるまでに、30〜60秒ほどかかることがあります。それでも Logs が表示されない場合は、アプリ起動時のコンソール出力を確認してください。次の内容が表示されるはずです。
これが表示されない場合は、OpenTelemetry のデバッグログを有効にして、そもそも Logs がエクスポートされているかどうかを確認してください。
デバッグ方法をさらに確認したい場合は、OpenTelemetry のトラブルシューティングガイドを参照してください。
■なぜ一部のログ属性が欠けているのですか？
OpenTelemetry の属性にはシンプルな型しか使えません。使えるのは、文字列、数値、真偽値です。複雑なオブジェクトは OTLP プロトコル経由では正しくシリアライズされません。代わりにフラットな形にしてください。
これは Sentry 固有の制限ではなく、OpenTelemetry 側の要件です。詳細は OpenTelemetry の attribute specification を参照してください。
■配列属性で検索やフィルタリングはできますか？
配列属性は取り込まれ、ログ詳細ビューでは表示されますが、現時点ではそれらを使って検索、フィルタリング、集計を行うことはできません。これは、OTLP ベータ版における現在の制限です。検索可能なデータが必要な場合は、属性を個別に分けるか、配列をカンマ区切りの文字列に結合して使ってください。
■メモリ使用量が高いのはなぜですか？
BatchLogRecordProcessor が一度に多くのログをバッチ処理しすぎている可能性があります。instrument.js でバッチサイズを調整してください。
バッチ処理の設定についてさらに詳しく知りたい場合は、BatchLogRecordProcessor のドキュメントを参照してください。
Original Page: Routing OpenTelemetry logs to Sentry using OTLP
IchizokuはSentryと提携し、日本でSentry製品の導入支援、テクニカルサポート、ベストプラクティスの共有を行なっています。Ichizokuが提供するSentryの日本語サイトについてはこちらをご覧ください。またご導入についての相談はこちらのフォームからお気軽にお問い合わせください。
