OpenTelemetry データフローエンドポイントの構成 (プレビュー)

2025-08-12

Von Bedeutung

このページには、プレビュー段階にある Kubernetes デプロイマニフェストを使用して Azure IoT Operations コンポーネントを管理する手順が含まれます。この機能は、いくつかの制限を設けて提供されているため、運用環境のワークロードには使用しないでください。

ベータ版、プレビュー版、または一般提供としてまだリリースされていない Azure の機能に適用される法律条項については、「Microsoft Azure プレビューの追加使用条件」を参照してください。

OpenTelemetry データフローエンドポイントは、メトリックとログを OpenTelemetry コレクターに送信するために使用されます。これにより、データを Grafana ダッシュボードや Azure Monitor などの可観測プラットフォームに転送できます。エンドポイントの設定、認証、トランスポート層セキュリティ (TLS)、バッチ処理のオプションを構成できます。

[前提条件]

Azure IoT Operations のインスタンス
Azure IoT Operations クラスターからデプロイされ、アクセス可能な OpenTelemetry コレクター

OpenTelemetry エンドポイントの概要

OpenTelemetry エンドポイントを使用すると、OpenTelemetry Protocol (OTLP) を使用して Azure IoT Operations データフローから OpenTelemetry コレクターにテレメトリデータをエクスポートできます。これにより、デバイスとシステムのテレメトリを既存の監視インフラストラクチャに統合できます。

一般的なシナリオ

デバイス診断: 温度、圧力、およびその他のセンサーの測定値をメトリックとしてエクスポートしてデバイスの正常性を監視する
工場の監視: 運用ラインテレメトリを Grafana ダッシュボードに送信して運用を可視化する
システムの可観測性: アプリケーションログとメトリックを Azure Monitor に転送して一元的な監視を行う
カスタムメトリック: フィルター処理と分析を向上させるために、ファクトリ ID や場所などのコンテキスト属性をメトリックに追加する

データ形式の要件

OpenTelemetry エンドポイントでは、データが、 metrics 配列、 logs 配列、またはその両方を持つ特定の JSON スキーマに準拠している必要があります。このスキーマに準拠していないメッセージは削除され、メッセージの損失を防ぐために確認されます。

JSON ペイロードでは、次の最上位構造を使用する必要があります。

{
  "metrics": [ /* array of metric objects */ ],
  "logs": [ /* array of log objects */ ]
}

少なくとも 1 つの metrics または logs が存在する必要があります。

すべての受信メッセージは、必要なスキーマに対して検証されます。検証に失敗したメッセージは削除され、ブローカーに受信確認され、トラブルシューティングのためにログに記録されます。一般的な検証エラーには、必須フィールドの不足、無効なデータ型、サポートされていないメトリックの種類またはログレベル、形式が正しくないタイムスタンプなどがあります。 MQTT メッセージに有効期限のタイムスタンプが含まれている場合、期限切れのメッセージは処理の前に除外されます。

メトリックの形式

metrics配列内の各メトリックオブジェクトには、次のフィールドが含まれている必要があります。

必須フィールド:

name (文字列): メトリック名
type (文字列): メトリックの種類 ( サポートされているメトリックの種類を参照)
value (数値): メトリックの数値

省略可能なフィールド:

description (文字列): メトリックの人間が判読できる説明
timestamp (数値): メトリックが記録されたときの Unix エポックタイムスタンプ (ナノ秒単位)
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 (string): 属性値 (文字列である必要があります)

ログの形式

logs配列内の各ログオブジェクトには、次のフィールドが含まれている必要があります。

必須フィールド:

value (文字列): ログメッセージの内容
level (文字列): ログレベル ( サポートされているログレベルを参照)

省略可能なフィールド:

timestamp (数値): ログが記録されたときの Unix エポックタイムスタンプ (ナノ秒単位)
attributes (配列): ログコンテキストとフィルター処理のキーと値のペア

{
  "logs": [
    {
      "value": "Device temperature sensor initialized",
      "level": "info",
      "timestamp": 1754851200000000000,
      "attributes": [
        {
          "key": "deviceId",
          "value": "sensor001"
        },
        {
          "key": "component",
          "value": "temperature-sensor"
        }
      ]
    }
  ]
}

attributes配列内の各属性には、次のものが必要です。

key (文字列): 属性名
value (string): 属性値 (文字列である必要があります)

サポートされているメトリックの種類

次の OpenTelemetry メトリックの種類がサポートされています。

カウンター: u64_counter、 f64_counter - 単調に値を増加させる
アップ/ダウンカウンター: i64_up_down_counter、 f64_up_down_counter - 増減できる値
ゲージ: u64_gauge、 i64_gauge、 f64_gauge - ポイントインタイム値
ヒストグラム: f64_histogram、 u64_histogram - 値の分布

サポートされているログレベル

次のログレベルがサポートされています。

trace
debug
info
warn
error
fatal

OpenTelemetry エンドポイントを作成する

Bicep または Kubernetes を使用して、OpenTelemetry データフローエンドポイントを作成できます。

二頭筋
Kubernetes（クバネティス）

次の内容を含む Bicep .bicep ファイルを作成します。必要に応じて設定を更新し、 <AIO_INSTANCE_NAME> などのプレースホルダーの値を実際の値に置き換えます。

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param endpointName string = '<ENDPOINT_NAME>'
param collectorHost string = '<COLLECTOR_HOST>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource openTelemetryEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'OpenTelemetry'
    openTelemetrySettings: {
      host: collectorHost
      authentication: {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audience: '<OTEL_AUDIENCE>'
        }
      }
      tls: {
        mode: 'Enabled'
        trustedCaCertificateConfigMapRef: '<CA_CONFIGMAP_NAME>'
      }
      batching: {
        latencySeconds: 5
        maxMessages: 100
      }
    }
  }
}

次の Azure CLI コマンドを実行して、ファイルをデプロイします。

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

次の内容を含む Kubernetes マニフェスト .yaml ファイルを作成します。

apiVersion: connectivity.iotoperations.azure.com/v1beta1
kind: DataflowEndpoint
metadata:
  name: <ENDPOINT_NAME>
  namespace: azure-iot-operations
spec:
  endpointType: OpenTelemetry
  openTelemetrySettings:
    host: <COLLECTOR_HOST>
    authentication:
      method: ServiceAccountToken
      serviceAccountTokenSettings:
        audience: <OTEL_AUDIENCE>
    tls:
      mode: Enabled
      trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>
    batching:
      latencySeconds: 5
      maxMessages: 100

マニフェストファイルを Kubernetes クラスターに適用します。

kubectl apply -f <FILE>.yaml

構成オプション

このセクションでは、OpenTelemetry データフローエンドポイントの構成オプションについて説明します。

ホスト

host プロパティは、OpenTelemetry コレクターエンドポイント URL を指定します。プロトコル (http:// または https://) とポート番号を含めます。

例：

https://otel-collector.monitoring.svc.cluster.local:4317
http://localhost:4317
https://otel-collector:4317

認証

OpenTelemetry エンドポイントでは、コレクターに安全に接続するためのいくつかの認証方法がサポートされています。

サービスアカウントトークン (SAT)

サービスアカウントトークン (SAT) 認証では、Kubernetes サービスアカウントトークンを使用して OpenTelemetry コレクターで認証します。

<OTEL_AUDIENCE>を OpenTelemetry コレクター構成の対象ユーザーの値に置き換えます。この値は、コレクターで予想される対象ユーザーと一致する必要があります。

二頭筋
Kubernetes（クバネティス）

authentication: {
  method: 'ServiceAccountToken'
  serviceAccountTokenSettings: {
    audience: '<OTEL_AUDIENCE>'
  }
}

authentication:
  method: ServiceAccountToken
  serviceAccountTokenSettings:
    audience: <OTEL_AUDIENCE>

X.509 証明書

X.509 証明書認証では、相互 TLS 認証にクライアント証明書が使用されます。

二頭筋
Kubernetes（クバネティス）

authentication: {
  method: 'X509Certificate'
  x509CertificateSettings: {
    secretRef: '<X509_SECRET_NAME>'
  }
}

authentication:
  method: X509Certificate
  x509CertificateSettings:
    secretRef: <X509_SECRET_NAME>

X.509 証明書認証を使用する前に、クライアント証明書を使用して Kubernetes シークレットを作成します。

kubectl create secret tls <X509_SECRET_NAME> \
  --cert=client.crt \
  --key=client.key \
  -n azure-iot-operations

匿名認証

匿名認証は、OpenTelemetry コレクターが認証を必要としない場合に使用されます。

二頭筋
Kubernetes（クバネティス）

authentication: {
  method: 'Anonymous'
  anonymousSettings: {}
}

authentication:
  method: Anonymous
  anonymousSettings: {}

TLS の構成

OpenTelemetry コレクターとの安全な通信用にトランスポート層セキュリティ (TLS) 設定を構成します。

tls: {
  mode: 'Enabled'
  trustedCaCertificateConfigMapRef: '<CA_CONFIGMAP_NAME>'
}

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

無効な TLS

二頭筋
Kubernetes（クバネティス）

tls: {
  mode: 'Disabled'
}

tls:
  mode: Disabled

バッチ処理

コレクターに送信する前に複数のメッセージをグループ化してパフォーマンスを最適化するようにバッチ設定を構成します。

二頭筋
Kubernetes（クバネティス）

batching: {
  latencySeconds: 5
  maxMessages: 100
}

batching:
  latencySeconds: 5
  maxMessages: 100

プロパティ	説明	既定値
`latencySeconds`	バッチを送信するまでの最大待機時間。	60 秒
`maxMessages`	バッチ内のメッセージの最大数。	100000 メッセージ

エラー処理およびトラブルシューティング

メッセージの検証

OpenTelemetry エンドポイントは、必要なスキーマに対して受信メッセージを検証します。データフローパイプラインでメッセージが失われないように、無効なメッセージが削除され、確認されます。

一般的な検証エラー:

必要なフィールドがない (メトリックのname、 type、 value 、ログの value、 level )
メトリックの種類またはログレベルが無効です
メトリック value フィールドの数値以外の値
形式が正しくないタイムスタンプ値

配信の保証

OpenTelemetry エンドポイントはコレクター自体に配信保証を提供しますが、コレクターがデータを転送できるアップストリームサービスには提供しません。データがコレクターに到達すると、Azure IoT Operations は最終的な宛先に到達したかどうかの可視性を持ちません。