OpenTelemetry

OpenTelemetry 資源與基礎架構相關性

Instana 支援 OpenTelemetry的 Resource 屬性。 Instana 代理程式在相同主機上執行時，可以加強 OpenTelemetry 資源。 若要讓 Instana OpenTelemetry 資源偵測器運作，您需要部署 Instana 代理程式，並讓代理程式在相同主機上執行。

Instana OpenTelemetry 資源偵測器使用其他資源屬性來強化 OpenTelemetry 追蹤資訊。 其他屬性有助於建立追蹤資料與基礎架構實體之間的鏈結。

下列欄位會附加至資源:

• process.pid: 根 PID 名稱空間中處理程序的 PID。
• instana.host.id: 此主機上 Instana 代理程式的 UUID。
• service.instance.id: OpenTelemetry 服務的 ID。 此 ID 用來使追蹤資料與程序實體產生關聯。

如需 Linux 主機上基礎架構相關性的詳細資訊，請參閱 代理程式的 HTTP API 端點。

請參閱下列可用的 Instana OpenTelemetry 資源偵測器:

• Node.js: @opentelemetry/resource-偵測器-instana。

OpenTelemetry 追蹤

正在進行工作，以使 OpenTelemetry 與 Instana 自己的 AutoTrace 技術完全可交互作業

Instana 可以與 OpenTelemetry 追蹤資料無縫整合。 Instana 使用 Instana 產生且使用預設 W3C 追蹤環境定義的追蹤資料，來關聯 OpenTelemetry 追蹤資料。

Instana 支援大部分 OpenTelemetry 追蹤語意使用慣例。

OpenTelemetry 度量值

OpenTelemetry 度量值顯示為與從中收集它們的代理程式、主機或處理程序相關聯的 "OpenTelemetry 自訂度量值"。 OpenTelemetry 實體位於「基礎架構分析」下，類型為 OpenTelemetry。 對於「事件與警示」或「基礎架構圖」，您可以使用「動態焦點」搭配 entity.type:opentelemetry 或 entity.type:otel來查詢 OpenTelemetry 自訂度量值。

感應器會收集下列度量類型:

• 量規
• 直方圖
• 摘要

OpenTelemetry 日誌

OpenTelemetry 日誌的集合仍在開發和測試中。 如果主機代理程式收到 OpenTelemetry 日誌資料，則會顯示一些良性異常狀況。 使用下列方式，將 OpenTelemetry 日誌汲取至 Instana 後端:

1. 直接使用 OTLP 通訊協定或透過 OpenTelemetry 收集器將日誌傳送至 Instana 後端 otlp-acceptor 。

2. 與 Instana 代理程式一起汲取日誌，以收集 Instana 的資料。

   

將 OTLP 資料傳送至 Instana 代理程式

透過使用主機代理程式作為 Proxy ， OpenTelemetry 可以將追蹤及度量資料傳送至 Instana 代理程式。 然後，資料會傳送至 Instana 後端進行處理。

依預設會取消啟動主機代理程式中的 OpenTelemetry 汲取，以不干擾主機上的其他收集器。 若要在主機代理程式中啟用 OpenTelemetry 資料的接收，請將下列 Snippet 新增至主機代理程式的 configuration.yaml:

com.instana.plugin.opentelemetry:
  enabled: <boolean>   # legacy setting, will only enable grpc, defaults to false
  grpc:
    enabled: <boolean> # takes precedence over legacy settings above, defaults to true if "grpc:" is present
  http:
    enabled: <boolean> # allows to enable http endpoints, defaults to true if "http:" is present

啟動配置之後，主機代理程式會自動啟動 OpenTelemetry的預設 OTLP (OpenTelemetry 通訊協定) 匯出器 (在 gRPC 的埠 4317 上，以及在 HTTP 或 HTTP 連線的埠 4318 上) 的收集器。

將 OTLP 資料傳送至 Instana 後端

應用程式或系統可以使用 OTLP 通訊協定，將資料直接傳送至 Instana 後端。 使用 otlp-acceptor 元件的特殊端點。 確定已啟用 Instana 後端的 otlp-acceptor 元件。 您也需要設定必要的 Instana 金鑰，以進行驗證。 請參閱下列使用 OpenTelemetry Collector (用來連接至 Instana otlp-acceptor 元件) 的範例配置:

exporters:
  otlp:
    endpoint: otlp-xxxx-saas.instana.io:4317
    headers:
      x-instana-key: xxxxxxx

附註: 針對目標 Instana 後端，使用 Instana 代理程式的金鑰來設定 x-instana-key 欄位。 在 endpoint 欄位中使用 Instana 後端的正確主機名稱。 自行管理的 Instana 後端可以有任何主機名稱，且不必是 "otlp-xxxx-saas.instana.io"。

使用 Instana Exporter 將原生資料傳送至 Instana 後端

您需要將對應的語言型 Instana Exporter 載入至應用程式，才能使用對應的語言型 OpenTelemetry SDK。 雖然越來越多 OpenTelemetry 社群中的人員選擇原生 OTLP 通訊協定，但此簡單解決方案仍可運作。 以下是可用的 Instana OpenTelemetry Exporters:

• 無伺服器 Node.js Instana OpenTelemetry 匯出程式: @instana/opentelemetry-exporter
• 無伺服器 .NET Instana OpenTelemetry 匯出程式: OpenTelemetry.Exporter.Instana
• 無伺服器 Go Instana OpenTelemetry 匯出程式: github.com/instana/go-otel-exporter

使用 OpenTelemetry Contrib Collector

應用程式或系統可以使用 OTLP 通訊協定，將資料傳送至 OpenTelemetry Contrib 收集器。 然後， OpenTelemetry Contrib 收集器 會使用其 Instana Exporter ，將資料轉遞至 Instana 後端無伺服器接收器。 若要將資料傳送至 Instana 後端無伺服器接收器，請配置主機代理程式的 configuration.yaml 檔案，如下所示:

exporters:
  instana:
    endpoint: "https://xxxxxx/serverless"
    agent_key: "xxxxxxxxxx"

使用 Instana 代理程式的金鑰來設定 agent_key 欄位。 附註: 無伺服器接收器的 "Content-Length" 限制是 50000000。 如果要求岔斷限制，您會看到「413 要求實體太大」錯誤。 因此，您也需要變更 otel contrib 收集器的收集器配置檔: 1. 建立批次處理器的特殊實例，以與 instana 匯出程式一起使用。 2. 將批次處理器的 send_batch_max_size 參數設為適當的值 (依預設沒有限制)。 如需相關資訊，請參閱 Readme 檔。

分析 OpenTelemetry 呼叫

我們努力讓 OpenTelemetry 成為一流公民，並與 Instana 自己的 AutoTrace 技術具有完整交互作業能力。 因此，如果使用 OpenTelemetry啟用的應用程式或系統產生追蹤的所有文字段或部分文字段，與來自原生 Instana 追蹤程式的所有追蹤資料相比，幾乎沒有任何不同。 可以使用相同的 Call Analytics 方式。

若要過濾來自 OpenTelemetry的呼叫，請將過濾器查詢設為 OpenTelemetry 資源屬性 service.name 及 is present。 您需要設定此過濾器查詢，因為 資源語意使用慣例的 OpenTelemetry 規格 需要 OpenTelemetry 資源屬性 service.name。 OpenTelemetry 有各種指定服務名稱的方法。 如需相關資訊，請參閱 OpenTelemetry 官方文件。

每一個 OpenTelemetry 屬性及 OpenTelemetry 資源屬性都以下列標籤表示:

• 動態標籤: 這些標籤是從傳送至 Instana 且存在於呼叫標籤型錄中的所有 OpenTelemetry 屬性計算而來。 可以直接從標籤型錄直接依名稱 (例如 http.method) 輕鬆搜尋動態標籤。 放入標籤型錄中的動態標籤數目限制為 500 個不同的屬性名稱。 如果您超出此限制，則只使用靜態標籤來作為過濾依據及分組依據，因為它們沒有此限制。

  

• 靜態標籤: 這些標籤可讓您存取傳送至 Instana 的所有 OpenTelemetry 屬性或 OpenTelemetry 資源屬性。 若要依靜態標籤來過濾或分組，您必須先選取 OpenTelemetry 標籤 或 OpenTelemetry 資源標籤 ，然後指定屬性名稱作為其索引鍵。

  

如果您超出 500 OpenTelemetry 屬性的限制，則需要檢閱自訂 OpenTelemetry 屬性的命名慣例。 例如，如果您要追蹤 A/B 測試，而不是為每個使用者建立新屬性 (例如 user-123-ab-test=a) ，則可以使用兩個屬性 user-id=123 和 ab-test=a。 透過使用兩個個別標籤，您可以輕鬆地過濾或分組資料，同時保持不同的 OpenTelemetry 標籤總數偏低。

服務對映

您可以使用多個資源和追蹤屬性，利用預設服務規則來對映 Instana 服務。 如先前所述， OpenTelemetry 資源屬性 service.name 經常用來對映為本端 Instana 服務。 您也可以使用其他屬性，如下所示:

• OpenTelemetry 追蹤跨距屬性 peer.service 用來對映為遠端 Instana 服務。
• OpenTelemetry 追蹤跨距屬性 messaging.destination 用來根據使用內部轉換的現有 call.messaging.address 規則，對映為遠端 Instana 服務。

OpenTelemetry 傳播器

傳播器會在供應商特定的追蹤相關性標頭與 OpenTelemetry 追蹤環境定義之間進行轉換。 如果送入的 HTTP 要求包含專有 Instana 追蹤相關性標頭 (X-INSTANA-T 和 X-INSTANA-S) ， Instana OpenTelemetry 傳播器會從那些標頭建立具有追蹤 ID 和跨距 ID 的 OpenTelemetry 追蹤環境定義。 OpenTelemetry 追蹤程式可以從該追蹤環境定義繼續追蹤。 此外，如果 OpenTelemetry 追蹤環境定義存在， Instana OpenTelemetry 傳播器會使用它，將專有 Instana 追蹤相關性標頭注入送出的要求中。

附註: Instana 追蹤程式支援 W3C 追蹤環境定義 規格，這是 OpenTelemetry使用的預設相關性標頭格式。 因此，您通常不需要將 Instana OpenTelemetry 傳播器新增至應用程式。 如需確切支援層次的相關資訊，請參閱 W3C 追蹤環境定義支援。

OpenTelemetry 取樣程式

OpenTelemetry 取樣器會做出 取樣決策，也就是說，它會決定是否針對特定要求擷取追蹤資料。 Instana OpenTelemetry 範例程式會根據追蹤環境定義的 sampled 旗標來做出此決策。 如果 sampled 旗標的值不是 false，則取樣器將決定擷取要求。

OTel C++ 用戶端 SDK 套件

OTel C++ Client SDK 套件是適用於 C++ 的 OpenTelemetry OTLP 匯出程式。 套件以 Opentelemetry-cpp為建置基礎。 如需相關資訊，請參閱 安裝 OTel C++ 用戶端 SDK 套件。