DDTraceをGuanceへ送信する方法：切り替え・検証・ロールバック

DDTraceをすぐに置き換える必要はありません。最初の検証では、既存のDDTrace SDKやJava Agentを残したまま、非本番の1サービスだけTrace送信先をDataKitへ切り替えます。GuanceでTraceの到着、サービス名、エラー、レイテンシ、タグ、呼び出し関係を確認し、条件を満たさなければ送信先を元へ戻します。

その後にOpenTelemetryへ移行するか、DDTrace計装を継続するかを判断します。この順序なら、計装の書き換えとバックエンド評価を同時に行わずに済みます。ただし、本稿は2026年8月1日時点の公式資料を照合した手順であり、Guanceによる実機テスト済み手順ではありません。必ず自社のSDK、DataKit、ネットワーク、サンプリング条件で非本番検証を行ってください。

DDTraceをGuanceへ送るときに変わるもの

このQuickstartで変更するのは、検証対象サービスのTrace送信先です。DDTraceはここではDatadogの各言語Tracerが生成するTraceと、その送信プロトコルを指します。Datadogの監視製品全体、過去データ、Dashboard、Monitor、SLO、RUM、Synthetic Monitoring、Security、ログパイプラインを自動移行する手順ではありません。

TrueWatchのDDTrace collector資料によると、DataKitはDDTraceのTraceを通常HTTPポート9529で受信します。一方、一般的なDatadog AgentのTraceポートは8126、DogStatsDは8125です。似た番号ですが用途が異なります。

DataKitのDDTrace collectorが受け取るのはTraceです。Profiling、JMXやruntime metricsは別のcollectorが必要です。「Traceが見えた」ことを「Datadogの全機能が移行できた」と解釈しないでください。

構成：DDTrace SDKからDataKitを経由してGuanceへ

検証経路は次のとおりです。

関連ガイドPrometheus remote_read設定ガイド：仕組み・検証・Guanceとの境界→

1. アプリケーションは既存のDDTrace SDKまたはAgentでTraceを生成する。
2. DD_AGENT_HOSTとDD_TRACE_AGENT_PORT、または対象SDKがサポートするTrace URLでDataKitを明示する。
3. DataKitのDDTrace collectorがTraceを受信し、Guanceへ送る。
4. Guanceでservice、env、versionを使って対象Traceを特定する。
5. 合格条件を満たさない場合は、検証サービスの送信先だけを元の値へ戻す。

この方式は「設定を戻せる」という構成上の利点がありますが、ゼロダウンタイムやデータ欠損ゼロを保証するものではありません。設定反映にアプリケーション再起動が必要な言語やデプロイ方式があります。

対象範囲と開始前の条件

最初の対象は、非本番環境の低リスクな1サービスに限定します。代表的な下流サービスを1つ以上呼び出し、成功応答と意図的に発生させた安全なテストエラーの両方を確認できるサービスが適しています。実際のユーザー情報や本番障害を使う必要はありません。

開始前に次を確認します。

• DataKitが起動し、検証サービスからDataKitの受信先へ到達できる。
• DDTrace SDKまたはAgentが現在のアプリケーションで正常にロードされている。
• 元のTrace送信先、SDKバージョン、DataKitバージョン、デプロイ方法を記録できる。
• 検証サービスだけを再起動または再デプロイできる。
• 元の送信先へ戻す担当者と判断時間を決めている。
• Traceへ個人情報、認証情報、リクエスト本文を追加しない規則がある。

本稿ではKubernetes、VM、各言語の全組み合わせを実機検証していません。DataKitが別ホストや別Podにいる場合、デフォルトのlocalhost:9529では届きません。到達可能なlistenerを設定し、Firewall、Security Group、Kubernetes ServiceやNetworkPolicyで接続元を制限します。Trace endpointをインターネットへ直接公開しないでください。

作業前に保存する設定とバージョン

ロールバックの成否は、変更前の状態をどれだけ正確に保存したかで決まります。少なくとも次の表をチケットへ記録します。値が未設定の場合は「未設定」と書き、推測で埋めません。

環境変数を確認するときは、必要な名前だけを個別に読み取ります。env全体を出力したり、DD_で一括抽出したりすると、同じ環境にあるAPI keyなどをチケットやCIログへ露出させる危険があります。本稿の例にもAPI key、Token、パスワードは含めません。

DD_TRACE_AGENT_URLのようなURL形式の設定は、言語やSDKバージョンによってhost/port設定より優先される場合があります。Datadogの各言語Tracer資料で対象バージョンの優先順位を確認し、相反する設定を同時に残さないでください。

DataKitのDDTrace collectorを有効にする

DataKitのconf.d/samplesからddtrace.conf.sampleをコピーしてddtrace.confとして管理する方法が公式資料に示されています。最小構成では、既定のTrace endpointを変更しません。

[[inputs.ddtrace]]
  endpoints = ["/v0.3/traces", "/v0.4/traces", "/v0.5/traces"]

  # 必要な低カーディナリティ項目だけをトップレベルへ昇格する
  # customer_tags = ["team", "deployment.region"]

endpointsは互換性に関わるため、理由なく削除・変更しません。customer_tagsは、spanのmetaにある項目をトップレベルのタグとして扱うためのallowlistです。DataKit 1.22.0以降では、追加項目をトップレベルへ出す場合に使用します。user ID、request ID、session IDのような高カーディナリティ値を一括で昇格しないでください。

DataKitとアプリケーションが同じホストでない場合、DataKitの主要設定側で到達可能なHTTP listenerを設定します。次は公式資料にある例ですが、0.0.0.0を使うならネットワーク制御が必須です。

[http_api]
  listen = "0.0.0.0:9529"

設定後は自社のDataKit運用手順に従って再起動し、collectorの初期化エラーがないことを確認します。サンプリングをまだ使わない場合、空または不完全な[inputs.ddtrace.sampler]テーブルを追加しないでください。rateのないsampler設定によってTraceを落とす可能性があります。

1サービスのDDTrace送信先を切り替える

次は非本番canary用の設定例です。実際の変数名と優先順位は、使用中の言語とDDTrace SDKバージョンで確認してください。DD_TRACE_SAMPLE_RATE=1.0は比較を単純にするための短時間の例であり、高トラフィックの本番へそのまま適用しません。

export DD_AGENT_HOST="datakit-service"
export DD_TRACE_AGENT_PORT="9529"
export DD_SERVICE="checkout-api"
export DD_ENV="staging"
export DD_VERSION="canary-2026-08-01"
export DD_TRACE_SAMPLE_RATE="1.0"

  # ここで対象アプリケーションを通常の手順で起動する

service、env、versionは評価中に値を変えません。名前を変えると、バックエンド差とタグ差を区別できなくなるためです。既存のデプロイテンプレートを編集する場合は、canaryのWorkloadだけに差分を限定し、他サービスへ一括反映しないでください。

DataKitがlocalhostにいる場合は127.0.0.1を使えます。別Podや別ホストの場合は、名前解決、Service、port、NetworkPolicy、Firewallを先に確認します。受信先が到達可能であることと、外部へ公開されていないことを同時に満たす必要があります。

テストリクエストと正常時の確認項目

自社のstaging用health endpoint、テストAPI、または合成テストから、追跡可能なリクエストを少数送ります。本番障害の注入や、実ユーザーの個人情報を含むリクエストは不要です。下流呼び出しを含むリクエストを1つ用意すると、Trace Contextの連続性も確認できます。

DataKit側ではmonitorや運用ログでDDTrace endpointへの受信を確認します。Guance側ではAPMのTrace Explorerを開き、記録したservice=checkout-api、env=staging、version=canary-2026-08-01で対象時間を絞ります。Guance APMのTrace Explorer資料も併せて確認してください。

正常判定に最低限必要なのは次の項目です。

• 対象時間帯に空でないTrace IDが表示される。
• service、env、versionが送信時の値と一致する。
• 入口Spanを開き、resource、duration、status、errorの有無を確認できる。
• 既知の下流呼び出しが同じTraceに含まれる、または欠落理由を説明できる。
• テストエラーがエラーTraceとして識別できる。
• SDK側とDataKit側のサンプリング条件を記録し、比較期間中に変えていない。

固定の「数秒以内」などは合格条件にしません。到着時間はbatch、network、buffer、負荷によって変わるため、まず自社環境の平常値を測定します。単純なTrace件数も、両側のサンプリングとテストリクエスト数が一致しなければ比較指標になりません。

Traceが出ない・一部欠けるときの排障

DataKitのno-data troubleshootingも利用できますが、最初に「生成」「送信先」「ネットワーク」「受信」「転送」「検索条件」のどこで止まっているかを分離してください。一度に複数の設定を変えると、原因を特定できません。

DDTraceとOpenTelemetryが混在する場合

DatadogのTrace Context Propagation資料では、現在の既定値としてDatadog形式、W3C tracecontext、baggageの注入・抽出が説明されています。ただし、実際の対応形式や旧設定との互換性は言語とバージョンで確認が必要です。移行期間は「既定値だろう」と仮定せず、呼び出し元と呼び出し先の設定を記録します。

DDTraceサービスとOpenTelemetryサービスを同じ呼び出し経路でつなぐ場合、DataKit側で次の互換設定を検討します。

[[inputs.ddtrace]]
  endpoints = ["/v0.3/traces", "/v0.4/traces", "/v0.5/traces"]
  compatible_otel = true
  trace_128_bit_id = true

compatible_otel=trueはspan IDとparent IDの表現をOpenTelemetryとの関連付けに合わせる設定で、trace_128_bit_idは既定で有効です。設定後は、DDTrace計装の上流からOpenTelemetry計装の下流まで通る実際のテストリクエストを1つ流し、同じTrace IDで親子関係がつながるかを確認します。プロトコル不一致は「データがない」ではなく「サービスマップだけ切れる」形で現れることがあります。

W3Cへ統一することは有力な選択ですが、全サービスへ一斉適用しません。propagatorを変更すると、未対応サービスとのTrace連続性に影響します。1つの呼び出し経路ごとに変更し、失敗時に元のinject/extract設定へ戻せるようにします。

OpenTelemetryへ段階移行する場合

DDTraceの送信先切り替えと、計装をOpenTelemetryへ置き換える作業は別です。最初のcanaryでGuance側の調査経路を評価した後、必要ならサービス単位でOpenTelemetry計装へ移行します。OpenTelemetry Collectorはテレメトリーを受信、処理し、1つ以上のexporterへ送るコンポーネントで、agentまたはgatewayとして配置できます。Collectorの設定資料では、pipelineに複数exporterを設定できることが示されています。

複数exporterはOTLPへ移行した段階の並行評価には使えますが、同じデータを2つのバックエンドへ送るため、egress、ingestion、保存の費用と障害面が増えます。通常のDDTrace payloadを既存tracerから2つのバックエンドへ安全に同時送信できるとは、本稿では主張しません。

DataKitでOTLPを受ける場合、TrueWatchのOpenTelemetry資料はgRPC 4317を推奨し、HTTPでは9529上の/otel/v1/traces、/otel/v1/metrics、/otel/v1/logsを示しています。DataKit 1.85.0以降はHTTP/JSONを受け付けず、HTTP/Protobufのみです。一般的な/v1/tracesをそのまま使わず、DataKitの/otel付きpathを明示してください。

Datadog SDKのネイティブOTLP出力を初手にしない理由

DatadogのSDKからOTLP Traceを出力する機能は2026年8月1日時点でPreviewです。言語ごとに最低バージョンと対応プロトコルが異なり、Traceは引き続きDatadog semanticsを使います。Datadog側の一部機能が失われる、またはAgentが必要な場合もあるため、最初の移行経路として「全言語でそのままDataKitへ直結できる」とは扱いません。

関連ガイドAPMとは？仕組み・監視項目・オブザーバビリティとの違いを実務で解説→

この表は互換性保証ではなく、公式に記載されたprotocolの交差を整理したものです。バージョンやPreview条件は変わるため、実装直前にDatadogとDataKitの両方の資料を再確認してください。安定した移行境界が必要なら、サービスを標準OpenTelemetry SDK/Agentへ移行し、OpenTelemetry Collectorを中継する構成を別途評価します。

サンプリング・タグ・費用を同じ条件で比べる

DD_TRACE_SAMPLE_RATEなどのSDK側サンプリングと、DataKit receiver側のsamplerは独立しています。片側だけを見て「100%送った」「同じ件数になった」と判断しないでください。評価期間は、入力リクエスト数、SDK設定、receiver設定、error/rare resourceの扱いを固定します。

タグも同様です。Datadog側のfacetとGuance側のトップレベルtagは自動的な一対一対応ではありません。最初はservice、env、versionと、teamやregionなど少数の安定属性に限定します。高カーディナリティ値を増やすと検索性だけでなくデータ量や運用負荷へ影響します。

費用比較は、同じホスト数だけでは成立しません。Trace数、Span数、サンプリング、保持期間、ログ、カスタムメトリクス、Profiling、サポート、二重送信期間を同じ業務条件で測ります。この技術ページでは「常に何%安い」とは主張しません。価格差を検証するときも、まず同じテレメトリー範囲と合格条件を揃えてください。

ロールバック手順

次の順序で、検証対象サービスだけを戻します。

1. 変更前に保存したTrace destination、port、URL、sampling、propagation設定を承認済みのデプロイ設定へ戻す。
2. 通常のリリース手順でcanaryサービスだけを再起動または再デプロイする。
3. 元のバックエンドで新しいTraceが再び到着し、service、env、versionと下流Spanが正しいことを確認する。
4. Guance側への新規Traceが止まったことを確認する。bufferに残ったデータによる短時間の遅延を考慮する。
5. 元の経路が安定してから、検証用DataKit設定や一時的なネットワーク許可を整理する。

アプリケーション全体に対する汎用的なrollout undoを初手にすると、DDTrace以外の同時変更まで戻す可能性があります。送信先変更を独立した差分として管理し、その差分だけを戻せるようにしてください。ロールバック確認が終わる前にDatadog Agent、既存設定、元のMonitorを削除しません。

30日評価の合格条件

1回Traceが見えただけでは本番移行の根拠になりません。代表的な負荷、障害、デプロイを含む期間で、次を記録します。

• 主要サービスと重要endpointのTrace到着率を、固定したsampling条件で説明できる。
• 成功、エラー、timeout、遅いTraceを検索し、既知の障害調査を再現できる。
• DDTraceとOpenTelemetryが混在する経路でTrace Contextが切れない。
• 必要な低カーディナリティtagだけが検索・集計に使える。
• DataKitのCPU、メモリ、buffer、networkに持続的な飽和がない。
• 個人情報や認証情報がTraceへ混入していない。
• Profiling、runtime metrics、logs、Dashboard、Monitor、SLOを別々に棚卸しした。
• 送信先を元へ戻す演習を行い、担当者と所要時間を記録した。
• 並行運用のegress、ingestion、保存と運用工数を含めて費用を比較した。

どれかを説明できない場合は、全サービス展開を止めて公開資料に記載されていませんとして残します。評価期間を延ばすこと自体ではなく、未確定項目を一つずつ検証することが重要です。

公開資料に記載されていませんと公開できない主張

本稿の公開前に、最低でも日本語ネイティブ編集、DataKit担当、APM製品担当によるレビューが必要です。さらに、本番向け手順として公開するには、指定したDataKit、runtime、DDTrace SDK、デプロイ方式でのhands-on testとロールバック演習が必要です。

現時点で公開資料に記載されていませんとして残す項目は次のとおりです。

• 各読者環境で使われる正確なSDKと設定優先順位。
• 既存のDatadog contract、sampling、retention、カスタム設定。
• Dashboard、Monitor、SLO、Security、RUM、Synthetic、ログ、履歴データの移行方法。
• 日本または韓国のTrueWatch SaaSデータ保管場所。公開endpoint一覧だけではデータレジデンシーを証明できない。
• SaaSとプライベート配置の機能、SLA、サポート条件の完全な同等性。

したがって、「完全互換」「そのまま全機能を移行」「ゼロダウンタイム」「無損失」「自動移行」「DDTraceから2社へ標準で同時送信」とは表現しません。これらは公式資料の確認だけでは証明できません。

Guanceで確認できる範囲と次のステップ

Guance APMでは、サービス、Trace、サービスマップ、エラー追跡などの調査経路を案内しています。まず本稿のcanaryで、同じ障害を調べられるかを確認してください。APMの基本指標や製品評価軸を先に整理したい場合は、APMとは何かを解説した実務ガイドを参照できます。

この検証でGuance側の調査経路が合格しても、全プラットフォーム移行が完了したわけではありません。次は、対象サービスを増やす前に、OpenTelemetryへ移行する理由、残すDDTraceサービス、移行しない機能、二重運用期間、価格モデル、データ保管とサポート条件を決定記録へ残します。

公式資料

本稿は次の一次資料を2026年8月1日に確認し、設定事実と運用上の推論を分けて記載しました。

1. TrueWatch Docs — DDTrace — DataKitの受信port、endpoint、listener、collector範囲、sampling、tag、Trace Context互換設定。
2. Guance Docs — DDTrace — Guance側のDDTrace collector設定と環境変数。
3. Datadog Docs — Add the Datadog SDK — 各言語Tracerの導入とTrace destinationの設定入口。
4. Datadog Docs — Trace Context Propagation — Datadog、W3C、B3の注入・抽出設定。
5. Datadog Docs — Unified Service Tagging — service、env、versionの統一。
6. OpenTelemetry — Collector — Collectorの役割とベンダー中立の収集経路。
7. OpenTelemetry — Configuration — receivers、processors、exporters、pipelinesと複数exporter。
8. OpenTelemetry — Gateway deployment pattern — 集中endpointとしてのgateway配置。
9. TrueWatch Docs — OpenTelemetry — DataKitのOTLP port、HTTP path、protocol制約。
10. Datadog Docs — Export Traces from Datadog SDKs in OTLP Format — Preview、言語別最低バージョンとprotocol。
11. Datadog Docs — OpenTelemetry Compatibility — OpenTelemetry経路におけるDatadog機能の対応範囲。
12. Guance Docs — Trace Explorer — GuanceでのTrace検索と確認。
13. Guance Docs — DataKit no data troubleshooting — DataKitのno-data調査入口。