這很重要
本頁包含使用 Kubernetes 部署清單管理 Azure IoT Operations 元件的說明，該清單已在預覽中。 這項功能隨附 數個限制，不應用於生產工作負載。
請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。
OpenTelemetry 資料流端點可用來將計量和記錄傳送至 OpenTelemetry 收集器，然後可將資料轉送至 Grafana 儀表板和 Azure 監視器等可檢視性平台。 您可以設定端點設定、驗證、傳輸層安全性 (TLS) 和批次處理選項。
先決條件
- Azure IoT 作業的實例
- 從 Azure IoT 操作叢集部署和存取的 OpenTelemetry 收集器
OpenTelemetry 端點概觀
OpenTelemetry 端點可讓您使用 OpenTelemetry 通訊協定 (OTLP) 將遙測資料從 Azure IoT 操作資料流程匯出至 OpenTelemetry 收集器。 這可讓您將裝置和系統遙測整合到現有的可檢視性基礎結構中。
常見場景
- 裝置診斷：將溫度、壓力和其他感應器讀數匯出為監視裝置健康情況的計量
- 工廠監視：將生產線遙測傳送至 Grafana 儀表板以取得作業可見度
- 系統可檢視性：將應用程式記錄和計量轉送至 Azure 監視器以進行集中式監視
- 自訂計量：將工廠識別碼或位置等內容屬性新增至計量，以取得更好的篩選和分析
資料格式需求
OpenTelemetry 端點需要資料符合具有 metrics 陣列和/或 logs 陣列的特定 JSON 結構描述。 不符合此結構描述的訊息會遭到捨棄並認可，以防止訊息遺失。
JSON 承載必須使用這個最上層結構：
{
"metrics": [ /* array of metric objects */ ],
"logs": [ /* array of log objects */ ]
}
至少有一個 metrics 或 logs 必須存在。
所有傳入訊息都會根據所需的結構描述進行驗證。 失敗驗證的訊息會遭到捨棄、認可回代理程式，並記錄以進行疑難排解。 常見的驗證失敗包括遺失必要的欄位、無效的資料類型、不支援的計量類型或記錄層級，以及格式錯誤的時間戳記。 如果 MQTT 訊息包含到期時間戳記，則會在處理之前篩選出到期的訊息。
計量格式
metrics 陣列中的每個計量物件都必須包含下列欄位：
必要欄位：
-
name(字串)：計量名稱 -
type(字串)：計量類型 (請參閱支援的計量類型) -
value(數值)：計量的數值
選擇性欄位：
-
description(字串)：人類可讀的計量描述 -
timestamp(數值)：記錄計量時，Unix Epoch 時間戳記以奈秒為單位 -
attributes(陣列)：計量標記和篩選的索引鍵/值組
{
"metrics": [
{
"name": "temperature",
"description": "The temperature reading from sensor",
"type": "f64_gauge",
"value": 72.5,
"timestamp": 1754851200000000000,
"attributes": [
{
"key": "factoryId",
"value": "factory1"
},
{
"key": "location",
"value": "warehouse"
}
]
}
]
}
attributes 陣列中的每個屬性都必須具有：
-
key(字串)：屬性名稱 -
value(字串)：屬性值 (必須是字串)
記錄格式
logs 陣列中的每個記錄物件都必須包含下列欄位：
必要欄位：
-
value(字串)：記錄訊息內容 -
level(字串)：記錄層級 (請參閱支援的記錄層級)
選擇性欄位：
-
timestamp(數值)：記錄記錄時，Unix Epoch 時間戳記以奈秒為單位 -
attributes(陣列)：記錄內容和篩選的索引鍵/值組
{
"logs": [
{
"value": "Device temperature sensor initialized",
"level": "info",
"timestamp": 1754851200000000000,
"attributes": [
{
"key": "deviceId",
"value": "sensor001"
},
{
"key": "component",
"value": "temperature-sensor"
}
]
}
]
}
attributes 陣列中的每個屬性都必須具有：
-
key(字串)：屬性名稱 -
value(字串)：屬性值 (必須是字串)
支援的計量類型
支援下列 OpenTelemetry 計量類型：
- 計數器：
u64_counter、f64_counter- 單調增加值 - 向上/向下計數器：
i64_up_down_counter、f64_up_down_counter- 可增加或減少的值 - 量測計：
u64_gauge、i64_gauge、f64_gauge- 時間點值 - 長條圖：
f64_histogram、u64_histogram- 值的分佈
支援的記錄層級
支援下列記錄層級：
tracedebuginfowarnerrorfatal
建立 OpenTelemetry 端點
您可以使用作業體驗、Bicep 或 Kubernetes 來建立 OpenTelemetry 資料流程端點。
若要在 作業體驗中建立OpenTelemetry資料流程，請移至 資料流程端點。
從資料流程端點頁面中，識別 Open Telemetry ，然後選取 [+ 新增]。
在 [建立新的資料流程端點：開啟遙測 ] 窗格中，選取 [ 基本 設定] 索引標籤，並提供下列資訊：
- 名稱：端點的唯一名稱。
-
主機：OpenTelemetry 收集器端點的格式為
<host>:<port>，例如otel-collector.monitoring.svc.cluster.local:4317。 -
驗證方法：選擇下列其中一種驗證方法：
- Kubernetes 服務帳戶權杖：使用 Kubernetes 服務帳戶權杖向 OpenTelemetry 收集器進行驗證。 提供 OpenTelemetry 收集器設定的對象值。 如需詳細資訊，請參閱服務帳戶權杖 （SAT）。
- 匿名：當 OpenTelemetry 收集器不需要驗證時使用。
- X509 憑證：使用用戶端憑證進行相互 TLS 驗證。 提供包含用戶端憑證的 Kubernetes 密碼名稱。 如需詳細資訊，請參閱 X.509 憑證 。
選取 進階 組態 索引標籤，並提供下列資訊：
- 批次處理延遲 （以秒為單位）：傳送批次之前等待的時間上限。 預設值為5秒。
- 訊息計數：批次中的訊息數目上限。 預設值為 100000 則訊息。
-
TLS 模式：選擇下列其中一種 TLS 模式：
- 已啟用：啟用 TLS 以與 OpenTelemetry 收集器進行安全通訊。 提供包含受信任 CA 憑證的 Kubernetes ConfigMap 名稱。
- 已停用：停用 TLS。
- 受信任的 CA 憑證組態對應名稱：包含受信任 CA 憑證的 Kubernetes ConfigMap 名稱。
選取 [套用] 以建立 OpenTelemetry 端點。
設定選項
本節說明 OpenTelemetry 資料流程端點的設定選項。
主辦人
host 屬性會指定 OpenTelemetry 收集器端點 URL。 包含通訊協定 (http:// 或 https://) 和連接埠號碼。
範例：
https://otel-collector.monitoring.svc.cluster.local:4317http://localhost:4317https://otel-collector:4317
認證
OpenTelemetry 端點支援數個驗證方法，以安全地連線到收集器。
服務帳戶權杖 (SAT)
服務帳戶權杖 (SAT) 驗證會使用 Kubernetes 服務帳戶權杖向 OpenTelemetry 收集器進行驗證。
將 <OTEL_AUDIENCE> 取代為 OpenTelemetry 收集器設定的對象值。 此值必須符合收集器上預期的對象。
在 [建立新的資料流程端點：開啟遙測] 窗格的 [ 基本 設定] 索引標籤下，選取 [Kubernetes 服務帳戶權杖 ] 作為驗證方法。
提供 OpenTelemetry 收集器設定的 Service audience 值。
這很重要
您只能在建立新的 OpenTelemetry 資料流程端點時選擇驗證方法。 建立 OpenTelemetry 資料流程端點之後，您無法變更驗證方法。 如果您想要變更現有資料流程的驗證方法，請刪除原始資料流程，並使用新的驗證方法建立新的資料流程。
X.509 憑證
X.509 憑證驗證會使用用戶端憑證進行相互 TLS 驗證。
在 [ 建立新的資料流程端點：開啟遙測 ] 窗格的 [ 基本 設定] 索引標籤下，選取 [X509 憑證 ] 作為驗證方法。
從 Azure 金鑰保存庫提供下列資訊：
- 同步的密碼名稱：包含用戶端憑證的 Kubernetes 密碼名稱。
- X509 用戶端憑證：用戶端憑證。
- X509 用戶端金鑰：用戶端憑證的私密金鑰。
- X509 中繼憑證：用戶端憑證鏈的中繼憑證。
使用 X.509 憑證驗證之前，請先使用用戶端憑證建立 Kubernetes 祕密：
kubectl create secret tls <X509_SECRET_NAME> \
--cert=client.crt \
--key=client.key \
-n azure-iot-operations
匿名驗證
當 OpenTelemetry 收集器不需要驗證時，系統會使用匿名驗證。
在 [建立新的資料流程端點：開啟遙測 ] 窗格中，在 [基本 設定] 索引標籤下，選取 [ 匿名 ] 作為驗證方法。 不需要其他設定。
TLS 組態
設定傳輸層安全性 (TLS) 設定，以便與 OpenTelemetry 收集器進行安全通訊。
已啟用具有受信任 CA 的 TLS
- 在 [建立新的資料流程端點：開啟遙測 ] 窗格的 [ 進階 設定] 索引標籤下，選取 [已啟用] 作為 TLS 模式。
- 在 [受信任的 CA 憑證設定對應名稱] 中，提供包含受信任 CA 憑證的 Kubernetes ConfigMap 名稱。
已停用 TLS
在 [建立新的資料流程端點：開啟遙測 ] 窗格的 [ 進階 設定] 索引標籤下，選取 [已停用] 作為 TLS 模式。
批次處理
在傳送至收集器之前，先將多個訊息分組，以設定批處理設定，進而以將效能最佳化。
在 [建立新的資料流程端點：開啟遙測 ] 窗格的 [ 進階 設定] 索引標籤下，提供下列批次處理設定：
- 批次處理延遲 （以秒為單位）：傳送批次之前等待的時間上限。 預設值為5秒。
- 訊息計數：批次中的訊息數目上限。 預設值為 100000 則訊息。
錯誤處理和疑難排解
訊息驗證
OpenTelemetry 端點會根據必要的結構描述驗證傳入訊息。 無效的訊息會遭到捨棄並認可，以避免資料流程管線中的訊息遺失。
常見的驗證錯誤：
- 遺漏必要的欄位 (
name、type、value用於計量，value、level用於記錄) - 無效的計量類型或記錄層級
- 計量
value欄位中的非數值 - 格式錯誤的時間戳記值
傳遞保證
OpenTelemetry 端點會提供傳遞保證給收集器本身，但無法傳遞至收集器可以轉送資料的上游服務。 一旦資料到達收集器，Azure IoT 操作就不會看到它是否到達最終目的地。