監視・オブザーバビリティ

Sentry OpenTelemetry連携の3経路|OTLP直送とSDK併用の判断

Sentry OpenTelemetry連携の3経路|OTLP直送とSDK併用の判断

OpenTelemetryで計装済みのアプリケーションから、エラー監視SaaSであるSentryへテレメトリを渡す経路は、2026年9月時点の公式ドキュメントで3通りに整理されています。Sentry SDKにOTLP Integrationを足す構成、OTLPエンドポイントへ直送する構成、そしてOpenTelemetry CollectorからSentryへ転送する構成です。この記事では3経路のエンドポイント設定値と認証ヘッダ、オープンベータゆえに欠ける取り込み仕様、エラーイベントとトレースを同一trace_idで結ぶ実装、スパンが二重に登録される条件、そして既存のOTelパイプラインへSentryを足すか置き換えるかの判断までを、実装する側の材料として整理します。設定例は公式ドキュメントの記載に沿って、そのまま貼って動かせる形で載せます。

まとめ:3経路の選び分けとエラー相関を落とさない条件

結論を先に置きます。Sentryをエラー監視として使い続けながらOTelのトレースも見たいなら、Sentry SDKにOTLP Integrationを足す構成が第一候補です。トレースとログの保管先としてだけSentryを使うならOTLPエンドポイントへの直送、複数サービスを1つのCollectorから別々のSentryプロジェクトへ振り分けたいならSentry Exporterという順で候補を絞ると迷いません。

経路選択より先に確認すべきなのは、OTLP経由の取り込みが2026年9月時点でオープンベータであるという前提です。Sentry公式のOTLP概説は、受け取れるシグナルをトレースとログの2つとし、メトリクスは現時点で非対応と明記しています。スパンイベントは取り込み時に破棄され、スパンリンクと配列属性は表示はされるものの検索・フィルタ・集計の対象外です。「OTelで計装すればSentryの機能が全部そのまま使える」という前提で提案すると、実装フェーズで崩れます。

経路 送る対象 主な制約
OTLP Integration併用 トレース・ログ・エラー SDK側の追跡設定は切る
OTLPエンドポイント直送 トレース・ログ エラーとリプレイは別系統
Collector+otlphttp 1プロジェクト分 振り分けは連結器が要る
Collector+Sentry Exporter 複数プロジェクト分 安定度はアルファ段階

SentryがOpenTelemetryを受け取る3経路と適用範囲の切り分け

3経路は優劣ではなく、テレメトリの正規化とプロジェクトへの振り分けをどこで行うかの違いです。OTLPやCollectorという語が何を指すかについてはOpenTelemetry(OTel)の3つのシグナルとOTLP・Collectorの役割を先に押さえておくと、以降の設定項目が読み解けます。公式の分類は「Sentry SDKと連携させる」側と「OTelのデータをSentryへ送る」側の2軸で、後者には直送・転送に加えて、Vercel・Cloudflare・Herokuなどマネージド基盤からのログ/トレースドレインという受け口も並んでいます。

OTLP IntegrationでSDKのエラーとOTel計装を束ねる構成

Sentry SDKを従来どおり初期化したうえで、OTLP Integrationを有効にする構成です。公式は「同じバックエンドサービス内でSentry SDKとOTel計装の両方を動かしているなら、OTLP Integrationを使う」と位置づけています。Sentry with OTelのページによれば、この統合が構成するのは2つで、OTelスパンをSentryへ送るエクスポータと、Sentryのエラーやログを稼働中のOTelトレースへ結びつけるイベント紐付けです。

ここは以前の記載から整理し直された箇所で、サービスをまたぐトレースの伝播は統合の仕事ではないと公式が明示するようになりました。伝播はOTel既定のW3C traceparentプロパゲータが担い、標準的なOTel SDKのセットアップなら追加設定なしで有効になっています。エラー監視という本来の使い方を維持したまま、トレースの計装はOTel側の資産に寄せられるのがこの経路の値打ちです。

OTLP直送でSentryをトレースとログの保存先に限定する構成

計装コードには一切手を入れず、既存のOTLPエクスポータの向き先をSentryのエンドポイントへ変えるだけの構成です。公式は直送を選ぶ条件として、最も単純な設定で済ませたい場合、送信前にテレメトリを加工しない場合、複数の発生源を集約しない場合の3つを挙げています。Sentry SDKを入れないため、エラーイベント・Session Replay・自動ブレッドクラムといったSentry固有の機能は載りません。

トレース保管先の乗り換え検証や、既にエラー監視を別系統で持っている案件に向いた経路です。逆に言えば、Sentryを選ぶ最大の理由であるエラー起点の調査は、この構成では手に入りません。他社バックエンドと横並びで評価しているなら、Datadog OpenTelemetry連携の4方式と機能差と比較しておくと、保管先としての条件の違いが見えます。

Sentry ExporterをCollectorに挟む複数プロジェクト振り分け

OpenTelemetry Collectorにsentryという名前のエクスポータを設定し、1つのCollectorインスタンスから複数のSentryプロジェクトへテレメトリを振り分ける構成です。サービスごとにDSNを配って回る必要がなくなります。既定ではservice.nameリソース属性の値と同じスラッグのプロジェクトへ送られ、service.nameがpayments-apiのサービスなら格納先はpayments-apiプロジェクトです。

ただし安定度はトレース・ログともにアルファ段階と明記されています。振り分け属性が欠けたテレメトリは失われ、自動作成されたプロジェクトでは最初のバッチが落ちることがあり、削除済みプロジェクト宛ての送信はキャッシュが退避するまで403を返し続けます。マイクロサービスが数十本ある組織向けの経路であって、サービス2〜3本の構成で持ち出す道具ではありません。

環境変数を2行設定してOTLP直送でトレースとログを送る手順

直送経路は設定項目が2つだけと軽い一方、取り込み側の仕様に明示された欠落があります。数値と対象を押さえておくと採否を即断できます。

トレースとログのエンドポイントURLと認証ヘッダを設定する手順

送信先はシグナルごとに分かれています。トレースは https://o〈組織ID〉.ingest.sentry.io/api/〈プロジェクトID〉/integration/otlp/v1/traces 、ログは末尾が v1/logs になったURLです。認証はAPIトークンではなくDSNの公開鍵を使い、ヘッダ値は x-sentry-auth に「sentry sentry_key=公開鍵」の形で渡します。Direct OTLP Tracesのドキュメントが示す最短の設定は、次の環境変数を並べるだけです。

# トレースの送信先と認証ヘッダ
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://o00000.ingest.sentry.io/api/1111111/integration/otlp/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="x-sentry-auth=sentry sentry_key=example-public-key"

# ログも送る場合は同じ形でLOGS側を指定する
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="https://o00000.ingest.sentry.io/api/1111111/integration/otlp/v1/logs"
export OTEL_EXPORTER_OTLP_LOGS_HEADERS="x-sentry-auth=sentry sentry_key=example-public-key"

# Sentry側でサービス単位に絞り込めるようにする
export OTEL_SERVICE_NAME="payments-api"

組織IDとプロジェクトID、公開鍵の実値は画面から取得する値です。Sentryの Settings から Projects を開き、対象プロジェクトの Client Keys(DSN)にある OpenTelemetry のタブを見ると、エンドポイントURLと公開鍵がそのまま表示されます。アプリケーション側のコードで指定したい場合は、OTel SDKのエクスポータにurlとheadersを渡す形になります。

公式ドキュメントが示す設定例はHTTPのエクスポータに限られており、gRPCでの送信手順は記載されていません。既存のCollectorがgRPCでバックエンドへ送っている構成なら、Sentry向けのパイプラインだけHTTPに分ける必要があります。ログ側のパイプライン設計はOpenTelemetryのログを直接送信とfilelog receiverで選び分ける手順と併せて詰めてください。

スパンイベント破棄とスパンリンク部分対応という取り込み時の欠落

取り込み仕様には明示された欠落が3つあります。最も影響が大きいのはスパンイベントで、公式は「スパンイベントは非対応。取り込み時にすべて破棄される」と記載しています。例外情報をスパンイベントとして載せている計装は、Sentry側でその情報が消えます。

項目 取り込み 検索・集計
スパンイベント 破棄される 不可
スパンリンク 取り込み・表示 不可
配列属性 取り込み・表示 不可
メトリクス 非対応 ―

スパンリンクと配列属性は取り込みも表示もされますが、検索・フィルタ・集計はできません。トレースビュー上には出るので、実装者は「入っている」と判断しがちです。実際には「画面に出ているのにダッシュボードで集計できない」という形で表面化するため、非同期処理のリンク関係をアラート条件に使う設計は、この段階では成立しないと見ておくべきです。

OTLPメトリクス非対応がバックエンド統合に与える制約と回避策

SentryはOTLP経由のメトリクスを受け取りません。3シグナルすべてを1つのバックエンドへ集約する構想でSentryを選ぶと、メトリクスだけ行き場を失います。実務上の回避策は2つです。メトリクスをPrometheusなど別系統に残して二系統で運用するか、Collectorのパイプラインをシグナル別に分けて宛先を変えるか。

後者はCollectorの設定ファイル内でtracesとlogsのパイプラインだけSentryへ向け、metricsは既存の送信先を維持する形になります。どの計器で何を測るかを決め直すならOpenTelemetryのメトリクス実装と計器選定が判断材料になります。3シグナル統合を優先要件に置くなら、そもそも受け口の広いバックエンドを見るほうが早いです。

Collectorのエクスポータを書いてSentryへ転送する設定手順

アプリケーションから直送せず、Collectorで受けてからSentryへ渡す構成では、エクスポータの選択肢が2つあります。単一プロジェクトへ送るだけなら汎用のotlphttp、複数プロジェクトへ振り分けるならsentryという使い分けです。

otlphttpエクスポータに結合エンドポイントと認証ヘッダを書く

Collector経由の場合、シグナルごとにURLを分ける必要はありません。OpenTelemetry Collector Setupのドキュメントは、結合エンドポイントを1つ書けばCollector側が v1/traces と v1/logs を自動で付けると説明しています。圧縮とエンコーディングまで含めた最小構成は次の形です。

# otel-collector.yaml(トレースとログを1つのSentryプロジェクトへ)
exporters:
  otlphttp/sentry:
    endpoint: https://o00000.ingest.sentry.io/api/1111111/integration/otlp
    headers:
      x-sentry-auth: "sentry sentry_key=example-public-key"
    compression: gzip
    encoding: proto

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/sentry]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/sentry]

トレースだけ、あるいはログだけを送るなら、endpointの代わりにtraces_endpointやlogs_endpointへ個別のURLを書く方式です。この形のままでは宛先プロジェクトが1つに固定されるため、サービスごとに送り先を変えたい場合はルーティングコネクタを挟み、サービス名の属性で条件分岐させたうえで、プロジェクトごとのエクスポータへ流す構成になります。設定量はそれなりに増えます。

sentryエクスポータで複数プロジェクトへ振り分ける設定手順

振り分けが主目的なら、コネクタを挟まずに済むsentryエクスポータが素直です。Sentry Exporterのドキュメントが示す必須項目は、Sentryインスタンスのベースurl、組織スラッグ、内部インテグレーションの認証トークンの3つです。

# otel-collector-config.yaml(service.nameでプロジェクトへ振り分け)
exporters:
  sentry:
    url: https://sentry.io
    org_slug: ${env:SENTRY_ORG_SLUG}
    auth_token: ${env:SENTRY_AUTH_TOKEN}
    auto_create_projects: true
    routing:
      project_from_attribute: service.name
      attribute_to_project_mapping:
        orders-service: ecommerce-orders
        products-service: ecommerce-products

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry]

project_from_attributeをdeployment.environmentのような別属性へ差し替えれば、環境やチーム単位での振り分けにも回せます。既定のタイムアウトは30秒、レート制限はX-Sentry-Rate-Limitsヘッダをエクスポータ側が解釈してプロジェクト別・カテゴリ別に待ち時間を管理し、ヘッダのない429応答では60秒のバックオフに落ちる挙動です。キューに戻して再送するため、瞬間的な制限で即データ損失にはなりません。

内部インテグレーションのトークンと権限を事前に用意する作業手順

認証トークンはDSNの公開鍵ではなく、Sentryの Custom Integrations から内部インテグレーション(Internal Integration)を作って発行します。公開用ではなく内部用を選ぶ点と、権限の付け方に注意が要ります。

  1. 組織設定の Custom Integrations で Create New Integration を選ぶ
  2. Internal Integration を選び、用途がわかる名前を付ける
  3. 権限に Organization: Read と Project: Read を与える
  4. プロジェクトの自動作成を使うなら Project: Write も加える
  5. 保存後に Create New Token でトークンを発行し、環境変数へ格納する

トークンは発行直後にしか表示されないため、その場で秘密情報の管理先へ入れてください。Collector側の準備としては、sentryエクスポータがotelcol-contribの配布物に同梱されている点が、作業を短くする材料です。自前でビルドする必要はなく、配布バイナリを設定ファイルとともに起動するだけで済みます。coreとcontribの違いや自作ディストリビューションの作り方はOpenTelemetry Collector Contribとocbで作る自作distroで整理しています。

エラーイベントとOTelトレースを同一trace_idで相関させる実装

SentryをOTelと組み合わせる価値は、ほぼこの一点に集約されます。エラーをクリックすれば原因のOTelトレースに飛べる、逆にトレースの遅いスパンからそこで起きたエラーへ辿れる、という導線です。

OTLPIntegrationをinitへ渡してtrace_idを刻む実装手順

相関の実体は、OTLP Integrationが稼働中のOTelトレース文脈を読み、Sentryのエラー・ログ・メトリクスといったイベントへtrace_idとspan_idを付与する処理です。これによりエラーがトレースのウォーターフォール上の正しいスパンに現れます。Pythonでの導入は、Python SDKのOTLP Integrationドキュメントのとおり、エクストラ付きでインストールして初期化時に統合を1つ足すだけです。

# pip install "sentry-sdk[opentelemetry-otlp]"
import sentry_sdk
from sentry_sdk.integrations.otlp import OTLPIntegration

sentry_sdk.init(
    dsn="https://[email protected]/0",
    send_default_pii=True,
    integrations=[
        OTLPIntegration(),
    ],
)

クラス名はOTLPIntegrationで、送信先はDSNから自動的に導出されます。引数で挙動を変えられる点も押さえておくとよいでしょう。自前のCollectorへ送るならcollector_url、TracerProviderを手で組むならsetup_otlp_traces_exporterを偽にする設定です。capture_exceptionsは既定が偽で、真にするとOTelスパンに記録された例外もSentry側で拾います。なお自動でのプロパゲータ設定は次のメジャーバージョンで削除予定と告知されているため、伝播はOTelのAPIで自分で組む前提に寄せておくと移行が軽くなります。

この統合が使える言語は、公式の一覧でPython・Node.js・Java・.NET・Go・Ruby・PHPです。PHPはLaravelとSymfony向けの手順も別途用意されています。JavaはSentry製のjavaagentを読み込む従来のディープ統合も維持されている状況です。Python側の要件はPython 3.7以上、opentelemetry-distroは0.35b0以上とされています。Sentry製品そのものの機能範囲はSentryのエラー監視・APM機能と料金体系で確認できます。

traces_sample_rate併用でスパンが二重化する条件と回避手順

連携で最も多い事故がこれです。OTel側でトレースを取りながらSentry SDK側でもtraces_sample_rateやtraces_samplerを設定すると、同じ処理に対して両方がスパンを作り、Sentryに重複したスパンが登録されます。公式も「OTelのトレースを使うならSentry SDKで追跡設定をしないこと」と注記しています。

回避策は単純で、1サービスにつきトレースの発生元を1つに固定することです。OTLP Integrationを使うならSentry SDKの追跡設定は書かない。逆にSentry SDKのトレースを使うなら、OTelのエクスポータをSentryへ向けない。Node.jsで既存のOTelセットアップをそのまま使う場合は、Lightweight Modeのドキュメントにあるとおり、TracerProviderを先に登録してから統合を足す形が用意されています。

// 既存のOTelセットアップへSentryを橋渡しする(v10.47.0以降)
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: "https://[email protected]/0",
  integrations: [otlpIntegration()],
});

この経路では自動のスパン生成が走らないため、二重化そのものが起きにくくなります。送信先を自前のCollectorへ変えたい場合は、統合の引数にcollectorUrlを渡します。従来からある重量級のセットアップでskipOpenTelemetrySetupを立て、スパンプロセッサやプロパゲータを自分で組み込む方法も残っていますが、配線の検証関数を呼ばずに本番へ出すと、文脈の分離だけが静かに壊れた状態に気づけません。

propagateTraceparentとサンプラー設定が招く判断の食い違い

フロントエンドからバックエンドまで1本のトレースにする場合、propagateTraceparentを有効にするとフロント側SDKがサンプリング判断をW3Cのtraceparentヘッダに載せ、バックエンドがそれを引き継ぎます。ここで公式が注意しているのが、OTel側のサンプラーをalways_onにしておくという点です。既定のparentbased_always_onのままだと、親の判断を尊重してCollectorのテールベースのサンプラーを素通りします。

結果として、エラー時だけ全スパンを残す設計を組んでいる案件では、この一行の違いで「落ちたリクエストのトレースだけ欠けている」という最悪の欠落が起きます。環境変数OTEL_TRACES_SAMPLERにalways_onを指定し、判断はCollector側へ寄せるのが公式の推奨です。ヘッドベースとテールベースの使い分けはトレースサンプリングの仕組みと率の決め方で整理しているので、フロントを含む分散トレースを組むなら、どの層で判断を下すかを先に決めてください。

既存のOTelパイプラインにSentryを足すか置き換えるかの判断基準

ここは判断を言い切ります。既にOTelでトレースを取っている環境にSentryを持ち込む価値があるのは、エラー監視をSentryに寄せる場合に限られます。トレース保管先としての置き換えを検討しているなら、現時点では見送りが妥当です。

エラー監視を主目的にSentryを足す構成の採用条件と運用前提

足す構成を採用してよいのは、次の2つを同時に満たすときです。第一に、エラーの調査導線をSentryに集約したい、あるいは既にSentryでエラー監視をしていること。第二に、対象言語がOTLP Integrationの対応言語(Python・Node.js・Java・.NET・Go・Ruby・PHP)に含まれていること。

この条件下なら、既存のOTel計装をそのままトレースの供給源にしつつ、エラーとトレースが同一trace_idで結ばれます。運用面の前提は1つだけ、サービスごとにトレースの発生元がSentry SDKかOTelかのどちらに寄っているかを台帳で管理することです。ここが曖昧なまま担当者が入れ替わると、重複スパンが再発します。

OTLP直送だけで組んだ場合に落ちるSentry固有機能と見送り判断

Sentry SDKを入れずOTLP直送だけで組む構成は、新規にSentryを導入する案件では見送るべきです。ログからのIssue生成、Session Replayとの連携、自動ブレッドクラム、そしてエラー相関は、いずれもネイティブSDK側に組み込まれた機能で、ベータ段階のOTLP経由の取り込みには載っていません。Sentryを選ぶ理由の大半がこれらであるため、機能を捨てた状態で比較すると、そもそも他のバックエンドのほうが条件が良くなります。

ベンダー中立性を最優先し、トレースとログの保管先を将来差し替える前提なら、判断は逆です。その場合はSentryに限定せず、Grafanaの構成でOTLPを受けて3シグナルを統合する手順のようなメトリクスまで受けられる選択肢を含めて評価してください。メトリクス非対応という制約が、Sentryを汎用バックエンドとして選びにくくしています。

小規模構成でSentry Exporterを立てる運用コストの損益分岐

サービス数が2〜3、送信先プロジェクトも1つという規模でCollectorにSentry Exporterを組むのは過剰です。Collector本体の可用性・バージョン追従・設定管理という運用対象が増えるうえ、エクスポータ自体がアルファ段階で、振り分け属性の欠落がそのままデータ損失になります。この規模なら各サービスにDSNを配ってOTLP Integrationで直接送るほうが、管理点も障害点も少なく済みます。

損益分岐は、プロジェクト数が2桁に届き、DSNの配布と更新が手作業で回らなくなったあたりにあります。単一プロジェクトのままCollectorだけ挟みたいなら、sentryではなくotlphttpで十分です。監視基盤の経路設計から運用体制まで含めて相談したい場合は、システムの保守運用・内製化支援で構成レビューから引き受けています。

よくある質問

SentryとOpenTelemetryの連携について、実装前に確認されることの多い5問に答えます。

SentryはOpenTelemetryのメトリクスを取り込めますか?

取り込めません。2026年9月時点の公式ドキュメントは、OTLP経由で受け取れるシグナルをトレースとログの2つとし、メトリクスについては現時点で非対応と明記しています。3シグナルすべてを1つのバックエンドに集約したい要件がある場合、メトリクスはPrometheusなど別系統に残すか、Collectorのパイプラインをシグナル別に分けて宛先を変える設計になります。

OTelで計装すればSentryの機能はすべて使えますか?

使えません。OTLP経由の取り込みはオープンベータで、ログからのIssue生成、Session Replayとの連携、自動ブレッドクラムといったネイティブSDK側の機能は載っていません。取り込み仕様にも欠落があり、スパンイベントは破棄され、スパンリンクと配列属性は表示のみで検索・フィルタ・集計の対象外です。エラー起点の調査導線が要件なら、Sentry SDKにOTLP Integrationを足す構成を選んでください。

Sentry SDKとOTelを併用するとスパンが重複しませんか?

設定次第で重複が生じる構成です。OTel側でトレースを取りながらSentry SDKにもtraces_sample_rateやtraces_samplerを設定すると、同じ処理に対して両方がスパンを生成します。公式もこの点を明示して警告しています。回避策は、1サービスにつきトレースの発生元を1つに固定することです。PythonならOTLPIntegrationを足したうえで、SDK側の追跡設定は書かないでください。

OTLPエンドポイントへgRPCで送ることはできますか?

公式ドキュメントが示す設定例はHTTPのエクスポータにurlとheadersを渡す形式、およびCollectorのotlphttpエクスポータのみで、gRPCでの送信手順は記載されていません。既存のCollectorがgRPCでバックエンドへ送っている構成では、Sentry向けのパイプラインだけHTTPに分ける必要があります。認証はDSNの公開鍵をx-sentry-authヘッダに載せて渡します。

複数サービスを別々のSentryプロジェクトへ振り分けられますか?

CollectorにSentry Exporterを設定すれば可能です。既定ではservice.nameリソース属性の値と同じスラッグのプロジェクトへ送られ、project_from_attributeで振り分けの基準属性を変更したり、attribute_to_project_mappingで明示的な対応表を持たせたりすることも可能です。汎用のotlphttpでも、ルーティングコネクタを併用すれば同じことが実現します。ただしSentry Exporterの安定度はトレース・ログともアルファ段階で、振り分け属性が欠けたテレメトリは失われます。

関連記事

お気に入りに入れた記事の一覧

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.09.28 テックブログ タイムズカーの不正アクセスと約660万件の流出|免許証画像を退会者まで残さない保管設計
  2. 2026.09.25 コラム 最低賃金引き上げ【令和8年度】47都道府県の改定額・発効日と企業の対応手順
  3. 2026.09.25 コラム 障害者雇用の助成金一覧:月いくら・支給要件と申請書類を勤怠データで揃える方法
  4. 2026.04.03 テックブログ マイナビ情報漏洩11万件|不正アクセスの経緯・対象確認と「登録は危険か」の判断材料
  5. 2026.09.05 コラム 犯罪収益移転防止法の本人確認:2027年4月の対面IC読み取り義務化と改修要件

RELATED POSTS 関連記事

目次