DDTrace 接入觀測雲：單服務切換、驗證與復原

評估觀測雲，不必從重寫 DDTrace 插樁開始。先保留現有 DDTrace SDK 或 Java Agent，只把一個低風險預發佈服務的追蹤鏈路傳送地址切到 DataKit。在觀測雲找到同一組測試請求，核對服務名稱、錯誤和下游調用；條件不滿足，就恢復已經記錄的原傳送地址，並確認舊後端重新收到新的追蹤鏈路。

本文討論的是單個服務的追蹤鏈路接收端切換。儀表板、監控器、SLO、RUM、可用性監測、Profiling、日誌、安全資料、合同和歷史記錄，都不在自動遷移範圍內。設定與協議已於 2026 年 10 月 27 日對照官方文檔復核；本輪沒有執行應用→DataKit→觀測雲的實機傳輸，也沒有完成回復原設定演練。用於生產操作前，需要在自己的預發佈環境完成這兩項驗證。

先分清三個連接埠

應用繼續使用現有 DDTrace 庫生成 Span，DataKit 接收和處理追蹤鏈路，再傳送到選定的觀測雲工作空間。DDTrace 採集器文檔區分了三條容易混淆的路徑。

DataKit 的 ddtrace 採集器負責追蹤鏈路。Profiling 使用獨立採集器；運行時指標、JMX 可能需要 StatsD 或其他集成。看到一條追蹤鏈路，只能證明該追蹤鏈路路徑可用，不能據此認定兩個平台功能完全等價。

第一次切換只選一個服務

保留 SDK 或 Agent，只改測試服務的傳送地址。比較期間固定 service、env、version、上下文傳播和採樣設置，分別檢查接收端、上傳路徑和實際故障排查過程。觸發停止條件，就恢復舊地址。

這不是雙寫方案。不能假定普通 DDTrace tracer 會把每個請求獨立傳送給兩個後端。若以後需要並行比較，應在服務能輸出 OTLP 的階段單獨設計 OpenTelemetry Collector 的多個 exporter，並評估隊列、重試、出口流量、接收費用和故障影響。

先約定什麼時候停止

選擇一個可以獨立重啓、會調用至少一個下游依賴的非生產服務，例如預發佈的登錄、商品或結算介面。準備正常請求和可控的測試錯誤，不使用真實客戶資料，也不向生產環境注入故障。

出現以下情況就停止擴大範圍，按約定回復原設定：

• 必須擴大公網訪問規則才能連接 DataKit。
• 啓動、請求延遲或錯誤率超出團隊預先確定的容忍範圍。
• 入口 Span 或已知下游調用缺失，且無法解釋。
• 採樣或過濾不同，導致兩段資料不可比。
• 追蹤鏈路屬性包含憑據、請求正文或個人資訊。
• 無法在變更窗口內恢復原傳送地址。

“等了五分鐘”不是成功標準。批處理、網路、緩衝和負載都會影響到達時間，應先測量本環境正常情況下的延遲，再在相同條件下比較。

保存能用於回復原設定的基線

回復原設定要依賴實際設定，而不是記憶。未設置的值記為 unset，不要用猜測填補。

只讀取必要且不含秘密的設定項，不要把完整環境變量或整個 DD_ 前綴的變量輸出到支援單、截圖或 CI 日誌中。

Python tracer 設定說明，設置 DD_TRACE_AGENT_URL 後，它會優先於分開的 host、port。當前 Python、Java、Node.js 文檔使用 DD_TRACE_AGENT_PORT，不要照搬舊示例中的 DD_AGENT_PORT。應查看實際安裝版本的語言文檔，清除衝突地址，並在部署或注入後核對處理程序的生效設定。

啟用 DataKit DDTrace 接收端

主機安裝方式下，從 DataKit 的 conf.d/samples 複製 ddtrace.conf.sample，以 ddtrace.conf 管理。最小設定保留兼容路徑：

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

  # 只提取確有用途、穩定且基數較低的屬性。
  # customer_tags = ["team", "deployment.region"]

不要為了讓設定更短而刪除 endpoint。也不要留下缺少採樣率的 [inputs.ddtrace.sampler] 表：缺失的 rate 會按 0 處理。不打算在接收端採樣，就移除或注釋掉整個表。

錯誤追蹤鏈路預設會繞過這個 sampler，設定 omit_err_status 後相應狀態不再享有該例外；上游 sampling priority 引發的提前丟棄又是另一層判斷。因此，接收端 rate 為 1.0 也不能證明每個應用請求都會進入觀測雲。

按既有 DataKit 設定流程應用變更，只重啓受影響的實例。用狀態管理確認 ddtrace 已啟用、沒有崩潰和新增初始化錯誤：

datakit monitor --input ddtrace

記錄版本、輸入狀態、錯誤計數變化和測試時間窗口，不把某張截圖當成唯一成功標準。

9529 只開放給需要連接的工作負載

DataKit 預設監聽 localhost:9529。應用和 DataKit 同主機時可使用該地址；跨 Pod 或跨主機時，需要可達的監聽地址：

[http_api]
  listen = "0.0.0.0:9529"

0.0.0.0 只是監聽範圍。還需用 Kubernetes Service、NetworkPolicy、安全組或主機防火牆限制來源，不能直接向公網開放追蹤鏈路接收端。同一 HTTP 服務可能提供其他 DataKit API，過寬的入口規則會影響更多功能。

Kubernetes 中可以使用私有 ClusterIP Service。以下片段的 namespace 和 selector 必須與實際部署一致：

apiVersion: v1
kind: Service
metadata:
  name: datakit-trace
  namespace: observability
spec:
  type: ClusterIP
  selector:
    app: datakit
  ports:
    - name: datakit-http
      port: 9529
      targetPort: 9529

從測試服務所在的網路環境檢查 DNS 與 HTTP 可達性：

curl --fail --silent --show-error \
  --output /dev/null --write-out '%{http_code}\n' \
  http://datakit-trace.observability.svc.cluster.local:9529/v1/ping

/v1/ping 返回運行資訊，只能確認 HTTP 服務可達，不能證明 DDTrace 採集器接受了 Span。不要為了得到響應而放寬訪問控制。

切換傳送地址，保持服務標識不變

在當前 tracer 支持的形式中選一種，不要同時保留兩組地址。以下佔位值須替換為變更前記錄的實際值。

export DD_AGENT_HOST="datakit-trace.observability.svc.cluster.local"
export DD_TRACE_AGENT_PORT="9529"
export DD_SERVICE="<existing-service>"
export DD_ENV="<existing-env>"
export DD_VERSION="<existing-version>"

# 按既有流程啓動或部署該測試服務。

如果使用的 tracer 支持 URL 形式，也可以選擇：

export DD_TRACE_AGENT_URL="http://datakit-trace.observability.svc.cluster.local:9529"
export DD_SERVICE="<existing-service>"
export DD_ENV="<existing-env>"
export DD_VERSION="<existing-version>"

# 按既有流程啓動或部署該測試服務。

比較期間保持原 SDK 採樣規則不變。如果同時改服務名稱、環境或採樣，追蹤鏈路缺失就可能來自檢索條件和分組變化，而非傳送路徑。需要 100% 採樣時，另做低流量實驗並記錄範圍。

接收端可達不代表 tracer 已加載。檢查最終運行命令：Java 的 -javaagent 要位於 -jar 之前；Node.js 的 dd-trace 要先於被插樁模塊初始化；Python 保留原來的 ddtrace-run 或框架集成，ddtrace-run --info 僅用於設定檢查。使用注入時，核對實際 NODE_OPTIONS 等啓動參數。Guance Operator 的注入變更作用於新建 Pod，應只重建測試 Pod，不要假定已有 Pod 會原地改變。

用正常請求和可控錯誤驗證

選擇不含客戶標識的預發佈介面、合成事務或測試夾具。請求量只需足以觀察採樣，不要無意間變成壓測：

for attempt in 1 2 3 4 5; do
  curl --fail --silent --show-error \
    "https://staging.example.test/health/trace-canary?attempt=${attempt}" \
    --output /dev/null
done

把示例 URL 換成自己的測試介面，再調用一次已知狀態碼與下遊行為的可控錯誤路徑。記錄請求時間、預期狀態、入口資源和下游服務，不保存敏感請求正文。

正常請求用於檢查入口和拓撲；錯誤請求檢查錯誤分類及保留行為；下游調用檢查上下文傳播和父子關係。

分開檢查接收、上傳和查詢

第一步，在 datakit monitor --input ddtrace 和運行日誌中確認輸入持續啟用，測試期間沒有新增錯誤。無資料排查可幫助區分啓動、採集器、監聽、時間和網路問題。

第二步，檢查 DataKit 到選定站點的 DataWay 出口、代理、時間同步、隊列和錯誤信號。接收端正常不代表上傳成功；記錄證據時不要複製工作空間憑據。

第三步，在目標工作空間的追蹤鏈路查看器中選擇測試時間，用原先記錄的 service、env、version 篩選。至少確認：

• 存在非空 Trace ID，服務標識與實際傳送值一致。
• 能查看入口 Span 的資源、耗時、狀態和錯誤。
• 已知下游關係存在，缺失時有明確解釋。
• 可以找到可控錯誤產生的錯誤追蹤鏈路。
• 整個測試期間 SDK 與接收端採樣規則沒有改變。

截圖需脫敏。兩邊的請求集合和採樣條件不同，不能只比較 Trace 總數。

沿著資料路徑故障排查

一次只改一個變量。多個設置同時變動後恢復正常，很難知道哪一項起了作用。

DDTrace 與 OpenTelemetry 共存時保住父子關係

採集成功仍可能出現拓撲斷裂。Datadog、W3C tracecontext、B3 的支持範圍和預設值要按語言與版本確認。DataKit 提供以下關聯設置：

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

compatible_otel 讓 Span ID 和 Parent ID 使用十六進制表示；trace_128_bit_id 在 DDTrace 元資料攜帶 _dd.p.tid 高位時重建完整 ID。要按實際傳播協議設定，然後發出一條跨 DDTrace/OpenTelemetry 邊界的請求，檢查父子調用鏈。設置存在不等於兼容性已經驗證。

不要一次替換所有服務的 propagator。逐條調用路徑推進，並保留舊注入、提取設定供回復原設定。

同時控制採樣和標籤

SDK 與 DataKit 的採樣獨立。SDK 留下一半、接收端再從剩餘資料留下一半，並不等於最終保留了一半；錯誤和稀有資源的例外也會改變結果。

比較時固定請求集合、SDK 規則、DataKit sampler/filter、服務標識、傳播設置及屬性名單。DataKit 1.21.0 起不再自動把全部 Span 元資料提取到頂層，1.22.0 起可用 customer_tags 選擇條目。meta 中的字串成為標籤，metrics 中的數值成為字段，名稱中的 . 轉為 _，如 deployment.region 變成 deployment_region。

用戶 ID、請求 ID、會話 ID 不應批量提取為頂層標籤。可搜索並不意味著值得承擔高基數和隱私風險。

新加坡與東南亞部署還要檢查出口路徑

應用到 DataKit 盡量保持在同一主機、集群或受控網路內；DataKit 到 DataWay 是另一條出口路徑。記錄工作負載的雲地域、VPC、集群、工作空間站點、實際 DataWay 地址、DNS、代理、TLS 檢查和出口白名單，還要確認跨境傳輸、留存、支持和私有部署是否有合同要求。

觀測雲 OpenAPI 列表把 Asia Pacific Region 1 標為 Singapore，但該標籤不能證明某一工作空間的全部存儲、處理、備份位置或合同承諾。本文針對新加坡場景，也不因此承諾資料駐留；應以適用合同和區域服務資訊為準。

使用企業代理時，遵循DataKit 代理設定，驗證正常 DataWay 路由，不在支援單中貼 Token、完整含憑據的 DataWay URL 或代理密碼。

OpenTelemetry 是後續決策

第一次切換要回答：現有 DDTrace 追蹤鏈路是否能支持觀測雲中的故障調查。之後再決定哪些服務保留 DDTrace、哪些改用 OpenTelemetry，以及是否調整採集層。

OpenTelemetry Collector支持多個 pipeline 和 exporter，能在服務輸出 OTLP 後開展並行評估，但會增加隊列、出口流量、接收、存儲成本和故障路徑。它不保證零丟失或免費複製。

通過 DataKit 接收 OTLP 時，核對官方集成文檔中的版本、協議、連接埠和 /otel 路徑。不要把普通 DDTrace payload 發往 OTLP endpoint，也不能把 Preview exporter 當作所有語言通用的遷移橋梁。

舊後端重新收到新追蹤鏈路，才算回復原設定完成

1. 只為測試服務恢復原 URL、主機、連接埠、傳播與採樣設置。
2. 按原發佈流程重啓或重新部署該服務。
3. 重新傳送正常請求與可控錯誤請求。
4. 在舊後端確認新追蹤鏈路、服務標識和下游 Span 正常。
5. 考慮正常緩衝延遲後，確認觀測雲不再收到新的測試追蹤鏈路。
6. 舊路徑穩定後，再清理臨時設定和網路許可。

常見 Datadog Agent 路徑可能是原主機加 DD_TRACE_AGENT_PORT=8126，也可能使用 URL；必須恢復變更前真正生效的值。關閉 Operator 注入註解也需重建 Pod。DD_TRACE_ENABLED=false 只關閉追蹤，不會把資料發回 Datadog。

如果 Kubernetes 的目標 revision 只包含這次地址切換，可以有針對性地撤回：

kubectl rollout status deployment/checkout-api --namespace staging

# 僅在記錄的 revision 只包含發送地址變更時使用。
kubectl rollout undo deployment/checkout-api --namespace staging

若同一 revision 包含業務變更，不能盲目撤回。舊 Agent、監控器和原設定要保留到回復原設定演練結束。

擴大範圍前，留下可復核的評估記錄

可以安排覆蓋日常流量、發佈和故障調查的約 30 天評估，但時間長短不能替代證據。檢查主要介面覆蓋、正常與錯誤查詢、超時和慢追蹤鏈路、混合傳播拓撲、DataKit 資源與出口、敏感屬性、相鄰信號、回復原設定及成本。

每項都應有可追溯結果：關鍵路徑缺口有解釋；團隊能復現一次已知故障的調查；CPU、記憶體和隊列沒有持續飽和；日誌、指標、Profiling、儀表板、監控器、SLO 有保留、重建或退出方案；舊後端在回復原設定後收到新資料。成本模型使用相同流量、信號範圍、採樣、留存和並行運行週期。

哪些已經有文檔依據，哪些仍需自己的證據

連接埠、協議路徑、屬性提取、Python 的 URL 優先級已有官方依據。真正需要現場驗證的是：準確的運行時/SDK/DataKit 組合、部署後的生效設置、採樣與傳播、負載下的丟失和延遲，以及回復原設定。

合同、工作空間地域、存儲和處理位置、SLA、支持與私有部署條款，應通過客戶對應資料確認；一次追蹤鏈路測試無法回答這些問題。儀表板、監控器、SLO、RUM、可用性監測、日誌、Profiling、安全和歷史記錄的遷移，也需要獨立方案。

因此，本文不承諾全功能直接替換、一鍵遷移、零停機、無丟失、預設雙寫或必然降本。缺少證據就保持小範圍，設計能回答該問題的下一項測試。

用技術驗證支持平台選擇

新加坡 Datadog 替代方案討論運行模式與取捨，新加坡價格指南解釋站點、計費和估算假設，本文負責接收端切換、驗證與回復原設定。

三方面條件都成立後，再結合觀測雲 APM確定拓撲、安全、區域約束和下一批服務。一個服務成功，不代表整個 Datadog 平台已經可以退出。

官方資料

以下設定與協議資料於 2026 年 10 月 27 日復核；這項復核不包含實機兼容或合同審核。

1. TrueWatch DDTrace；觀測雲 DDTrace：接收範圍、連接埠、採樣、屬性和 ID。
2. Datadog Python、Java、Node.js：傳送地址、優先級和啓動設定。
3. Datadog SDK；上下文傳播：語言接入與跨服務傳播。
4. Operator DDTrace 注入；狀態管理：Pod 注入和採集器檢查。
5. DataKit 無資料排查；架構；HTTP API：接收、上傳與可達性邊界。
6. 追蹤鏈路查看器；OpenAPI 站點；代理設定：查詢、地域標籤與網路。
7. OpenTelemetry Collector；設定；DataKit OpenTelemetry：並行 exporter 和 OTLP 接入。