Kafka 標頭移轉

摘要

Instana 將在未來幾個月變更其 Kafka 追蹤相關性的標頭格式。 您不需要採取任何動作。 您可能想要仔細查看的唯一原因是您非常關心訊息大小。 當移轉正在進行時，訊息大小會稍微增加。 幾乎所有使用案例都可以忽略 Instana 新增至訊息的額外負擔。 但如果您要為每個訊息儲存幾個位元組，請閱讀。

背景

為了啟用分散式追蹤， Instana 會將追蹤相關性資訊新增至要求和訊息。 確切的格式取決於基礎通訊協定。 對於 Kafka 訊息， Instana 目前會以二進位格式傳送追蹤相關性資訊。 Kafka 通訊協定容許標頭的任意二進位值，因此此行為完全符合 Kafka 訊息格式。 不過，部分 Kafka 用戶端實作無法妥善處理二進位標頭。 因此， Instana 將移至具有 string 值而非 binary 值的追蹤相關性標頭。 變更通訊協定的追蹤相關性標頭格式並不簡單，因為 Instana 無法控制應用程式的追蹤程式元件更新的時間點。 Instana 無法假設同時更新參與任何給定追蹤的所有追蹤程式。 此外，追蹤程式注入訊息中的標頭格式需要由監視接收該訊息之服務的追蹤程式來瞭解。 因此，必須以與舊版相容的方式來執行移轉。 我們已準備好這項動作一段時間，而且所有追蹤程式都可以同時處理舊及新標頭格式。

總之，此移轉將以多個階段實作，並容許過渡期間，以確保 Kafka 之間的追蹤相關性一律現成可用。

追蹤器版本

下列追蹤程式版本已準備好處理新的字串標頭格式，它們也容許配置傳送訊息時要使用的標頭格式。 您不需要立即更新至這些追蹤程式版本，除非您想要針對傳送 Kafka 訊息的服務明確 配置 標頭格式。 雖然如此， Instana 始終建議定期更新追蹤程式。

執行時期 版本 發行日期 評論
Golang instasarama@v1.2.0 2022 年 5 月 25 日 透過安裝最新套件版本來手動更新此追蹤程式。
Java Java 追蹤感應器 1.2.413 2022 年 5 月 31 日 這個追蹤程式通常會由 Instana 代理程式自動更新。
.NET Core Instana.Tracing.Core@1.228.1 2022 年 7 月 7 日 通過安裝最新模型區塊版本 (除非您使用 Kubernetes AutoTrace Webhook) 來手動更新此追蹤程式。
Node.js @instana/collector@2.3.0 2022 年 5 月 24 日 此追蹤程式是透過安裝最新 npm 套件版本來手動更新 (除非您使用 Kubernetes AutoTrace Webhook)。

除了這裡列出的執行時期之外，其他執行時期不受此變更影響。

此外，依預設，下列追蹤程式版本會傳送這兩種標頭格式:

執行時期 版本 發行日期 評論
Golang instasarama@v1.5.0 2022 年 10 月 4 日 透過安裝最新套件版本來手動更新此追蹤程式。
Java Java 追蹤感應器 1.2.425 2022 年 10 月 4 日 這個追蹤程式通常會由 Instana 代理程式自動更新。
.NET Core Instana.Tracing.Core@1.235.1 2022 年 10 月 5 日 通過安裝最新模型區塊版本 (除非您使用 Kubernetes AutoTrace Webhook) 來手動更新此追蹤程式。
Node.js @instana/collector@2.10.0 2022 年 10 月 5 日 此追蹤程式是透過安裝最新 npm 套件版本來手動更新 (除非您使用 Kubernetes AutoTrace Webhook)。

移轉階段

階段 0

在此階段中，依預設，追蹤程式只會傳送二進位標頭 X_INSTANA_C 及 X_INSTANA_L 。

可以傳送字串標頭而非二進位標頭，也可以同時傳送這兩組標頭。 如需相關資訊，請參閱 配置選項。

當收到訊息時，追蹤程式會尋找這兩組標頭，且能夠從這兩種標頭格式繼續追蹤。

此階段已結束，並開始 階段 1。

階段 1

** 附註: ** 這是移轉的現行階段。

目前，依預設，所有追蹤程式都會同時傳送二進位和字串標頭，亦即 X_INSTANA_C 和 X_INSTANA_L 以及 X_INSTANA_T 和 X_INSTANA_S。 此過渡階段可讓追蹤程式在您的 IT 基礎架構中逐步升級。

如果您擔心附加四個 Instana 標頭，而不是兩個 Instana 標頭，則可以套用下列移轉策略來最佳化訊息標頭額外負擔:

  1. 將傳送 Kafka 訊息的所有服務配置為僅傳送二進位標頭。 請參閱 配置選項。
  2. 在 2023 年 9 月之前的某個時間點，請確定所有追蹤程式都已升級至同時支援這兩種標頭格式的 版本 。
  3. 將傳送 Kafka 訊息的所有服務配置為僅傳送 string 標頭。 請參閱 配置選項。 透過使用此設定，服務不再受到進行中移轉的影響。
  4. 將所有追蹤程式升級至階段 2 版本之後，即可移除標頭格式的配置。 但如果配置維持不變，也不是問題，只會被忽略。

如果所有追蹤程式都已升級至足夠新的 版，您也可以跳過步驟 1 ，並直接使用新的標頭格式。

階段 2

此階段大約將在 2023 年 9 月開始。

從這個階段開始， Instana 追蹤程式依預設會從傳送舊式二進位標頭格式切換成新的字串標頭格式。 將忽略標頭格式 (如果有的話) 的配置。 這是移轉的最終階段。

配置選項

在 主機代理程式配置 中，或使用 環境變數，可以使用兩種不同的方法來配置 Kafka 標頭格式。

代理程式配置選項

將 com.instana.tracing.kafka.header-format 設為 binary、 string或 both。 以下是配置範例：

com.instana.tracing:
  kafka:
    header-format: both # possible values: binary, both, string

提供了一個選項，可完全停用將標頭注入 Kafka 訊息。 請參閱下列範例設定:

附註: 此設定將完全停用 Kafka 的追蹤相關性。 不建議設定此項，因為它會分割追蹤-第一個追蹤將在產生 Kafka 訊息的服務結束，而接收 Kafka 訊息的服務將啟動新的追蹤。

com.instana.tracing:
  kafka:
    trace-correlation: false

環境變數

  • 在受監視處理程序上設定環境變數 INSTANA_KAFKA_HEADER_FORMAT 。 環境變數的有效值為 binary、 string或 both。
  • 還提供了一個選項，可完全停用將標頭注入 Kafka 訊息。 這也會停用 Kafka的追蹤相關性。 此設定為 INSTANA_KAFKA_TRACE_CORRELATION=false。

標頭名稱

標頭格式在 Kafka 追蹤標頭一節中有詳細說明。

舊式/二進位標頭

在舊式模式中， Kafka 訊息的追蹤相關性會使用具有二進位內容的兩個標頭 X_INSTANA_C 和 X_INSTANA_L。

現代/字串標頭

移轉之後，或當您配置為傳送字串標頭時， Kafka 訊息的追蹤相關性會使用標頭 X_INSTANA_T、 X_INSTANA_S (以及選擇性地使用 X_INSTANA_L_S)。 這三個標頭都以字串值傳送。