Configurer des points de terminaison de flux de données OpenTelemetry (préversion)

Les points de terminaison de flux de données OpenTelemetry (OTEL) envoient des métriques et des journaux aux collecteurs OpenTelemetry, qui peuvent ensuite transférer les données vers des plateformes d’observabilité telles que Grafana et Azure Monitor. Vous pouvez configurer les paramètres de point de terminaison, l’authentification, le protocole TLS (Transport Layer Security) et les options de traitement par lots.

Cet article explique comment créer et configurer un point de terminaison de flux de données OpenTelemetry pour exporter des données de ressources de votre répartiteur MQTT vers un collecteur OpenTelemetry. L’article décrit le point de terminaison de flux de données OTEL, qui achemine les données des ressources du broker MQTT vers des collecteurs OTEL externes. Vous pouvez également envoyer des données de ressources aux points de terminaison d’observabilité à l’aide du point de terminaison de flux de données OpenTelemetry si vous souhaitez acheminer les données de télémétrie vers des plateformes telles que Grafana ou Azure Monitor.

Cette fonctionnalité est destinée au routage des données d’appareil et de ressources, et non à la collecte des métriques ou journaux d’intégrité des composants Opérations Azure IoT. Pour l’observabilité du cluster (surveillance de l’intégrité du répartiteur MQTT, des composants de flux de données, et ainsi de suite), consultez Configurer l’observabilité et la surveillance.

Prerequisites

• Une instance d’Opérations Azure IoT.
• Un collecteur OpenTelemetry déployé et accessible à partir de votre cluster Opérations Azure IoT.
• Accès administratif à votre cluster Opérations Azure IoT.

Terminologie

Vue d’ensemble du point de terminaison OpenTelemetry

En utilisant les points de terminaison OpenTelemetry, vous pouvez exporter les données de télémétrie des appareils et des ressources depuis les flux de données d'Opérations Azure IoT vers des collecteurs OpenTelemetry en utilisant le protocole OpenTelemetry (OTLP). Grâce à cette fonctionnalité, vous pouvez intégrer des données de télémétrie d’appareil et système à votre infrastructure d’observabilité existante.

Dans Opérations Azure IoT, OpenTelemetry vous permet de :

• Exportez les données de télémétrie des actifs en tant que métriques OTEL : envoyez des données de capteurs, des données de production ou l’état de l’équipement aux plateformes d’observabilité.
• Acheminer les données sans modifier les appareils : transformez les messages MQTT au format OTEL à la couche de flux de données.
• Collectez et exportez des données de télémétrie vers votre plateforme d’observabilité préférée.
• Intégrer à des pipelines d’observabilité existants : envoyez des données à n’importe quel back-end compatible OTLP (Grafana, Prometheus, Azure Monitor et Datadog).

Les points de terminaison de flux de données OTEL sont des points de terminaison de première classe dans les Opérations IoT d'Azure. Ils apparaissent dans la liste des points de terminaison de flux de données disponibles dans le portail d’expérience opérateur et peuvent être sélectionnés lors de la configuration des graphiques de flux de données modernes. Cette approche simplifie l’acheminement de la télémétrie vers des back-ends compatibles avec OTEL tout en conservant une expérience de configuration cohérente.

Scénarios courants

Voici des scénarios courants d’utilisation de points de terminaison OpenTelemetry dans Opérations Azure IoT :

• Diagnostics des appareils : exportez la température, la pression et d’autres lectures de capteur en tant que métriques pour surveiller l’intégrité des appareils.
• Surveillance des fabriques : envoyez des données de télémétrie de ligne de production aux tableaux de bord Grafana pour une visibilité opérationnelle.
• Observabilité du système : transférez les journaux d’application et les métriques à Azure Monitor pour la supervision centralisée.
• Métriques personnalisées : ajoutez des attributs contextuels tels que l’ID d’usine ou l’emplacement aux métriques pour améliorer le filtrage et l’analyse.

Configuration requise pour le format des données

Les points de terminaison OpenTelemetry exigent que les données respectent un schéma JSON précis avec un tableau metrics, un tableau logs, ou les deux. Le système supprime et reconnaît les messages qui ne sont pas conformes à ce schéma pour empêcher la perte de messages.

La charge utile JSON doit utiliser cette structure de niveau supérieur :

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

Vous devez inclure au moins une valeur metrics ou logs.

Le système valide tous les messages entrants par rapport au schéma requis. Il supprime et reconnaît les messages qui échouent à la validation en les renvoyant au courtier, et consigne les erreurs pour le dépannage. Les échecs de validation courants incluent les champs obligatoires manquants, les types de données non valides, les types de métriques non pris en charge ou les niveaux de journalisation et les horodatages mal formés. Si les messages MQTT incluent des horodatages d’expiration, le système filtre les messages expirés avant le traitement.

Format des métriques

Chaque objet de métrique du metrics tableau doit avoir les champs suivants :

Champs obligatoires :

• name (chaîne) : nom de la métrique.
• type (chaîne) : type de métrique (voir types de métriques pris en charge).
• value (nombre) : valeur numérique de la métrique.

Champs facultatifs :

• description (chaîne) : description lisible par l’homme de la métrique.
• timestamp (nombre) : timestamp d'époque Unix en nanosecondes indiquant le moment où la métrique a été enregistrée.
• attributes (tableau) : paires clé-valeur pour l’étiquetage et le filtrage des métriques.

{
  "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"
        }
      ]
    }
  ]
}

Chaque attribut du attributes tableau doit avoir :

• key (chaîne) : nom de l’attribut.
• value (chaîne) : valeur d’attribut (doit être une chaîne).

Format de logs

Chaque objet journal du logs tableau doit contenir les champs suivants :

Champs obligatoires :

• value (chaîne) : contenu du message de log.
• level (chaîne) : niveau de log (voir niveaux de log pris en charge).

Champs facultatifs :

• timestamp (nombre) : timestamp d’époque Unix en nanosecondes lorsque le journal a été enregistré.
• attributes (tableau) : paires clé-valeur pour le contexte de journalisation et le filtrage.

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

Chaque attribut du attributes tableau doit avoir :

• key (chaîne) : nom de l’attribut.
• value (chaîne) : valeur d’attribut (doit être une chaîne).

Types de métriques pris en charge

Les types de métriques OpenTelemetry suivants sont pris en charge :

• Compteurs : u64_counter, f64_counter - Augmentation monotonique des valeurs.
• Compteurs haut/bas : i64_up_down_counter, f64_up_down_counter - Valeurs pouvant augmenter ou diminuer.
• Jauges : u64_gauge, i64_gauge, f64_gauge - Valeurs à un instant dans le passé.
• Histogrammes : f64_histogram, u64_histogram - Distribution des valeurs.

Niveaux de journal pris en charge

Les niveaux de journal suivants sont pris en charge :

• trace
• debug
• info
• warn
• error
• fatal

Créer un point de terminaison OpenTelemetry

Vous pouvez créer un point de terminaison de flux de données OpenTelemetry à l’aide de l’expérience d’opérations IoT, de Bicep ou de Kubernetes.

Le point de terminaison de flux de données apparaît dans la liste des points de terminaison de flux de données disponibles dans l’expérience de Opérations Azure IoT. Cet ajout garantit que vous pouvez facilement identifier et sélectionner le point de terminaison OpenTelemetry lors de la configuration des pipelines de télémétrie, en favorisant une meilleure intégration et une meilleure visibilité entre les outils de supervision. En mettant en avant le point de terminaison OTEL avec d’autres options de flux de données, vous pouvez router les données de télémétrie et maintenir des normes d’observabilité cohérentes entre les ressources de manière plus efficace.

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
      }
    }
  }
}

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

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

kubectl apply -f <FILE>.yaml

Options de configuration

Cette section décrit les options de configuration pour les points de terminaison de flux de données OpenTelemetry.

Host

Spécifiez l’URL du point de terminaison du collecteur OpenTelemetry dans la host propriété. Incluez le protocole (http:// ou https://) et le numéro de port.

Exemples :

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

Authentication

Les points de terminaison OpenTelemetry prennent en charge plusieurs méthodes d’authentification pour se connecter en toute sécurité aux collecteurs.

Jeton de compte de service (SAT)

L’authentification par jeton de compte de service (SAT) utilise des jetons de compte de service Kubernetes pour s’authentifier auprès du collecteur OpenTelemetry.

Remplacez <OTEL_AUDIENCE> par la valeur d’audience de votre configuration du collecteur OpenTelemetry. Cette valeur doit correspondre au public cible attendu sur le collecteur.

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

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

X.509 certificate

L’authentification par certificat X.509 utilise des certificats clients pour l’authentification TLS mutuelle.

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

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

Avant d’utiliser l’authentification par certificat X.509, créez un secret Kubernetes avec votre certificat client :

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

Authentification anonyme

Utilisez l’authentification anonyme lorsque le collecteur OpenTelemetry ne nécessite pas d’authentification.

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

authentication:
  method: Anonymous
  anonymousSettings: {}

Configuration TLS

Configurez les paramètres TLS (Transport Layer Security) pour la communication sécurisée avec le collecteur OpenTelemetry.

TLS activé avec autorité de certification approuvée

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

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

TLS désactivé

tls: {
  mode: 'Disabled'
}

tls:
  mode: Disabled

Batching

Configurez les paramètres de traitement par lots pour optimiser les performances en regroupant plusieurs messages avant de les envoyer au collecteur.

batching: {
  latencySeconds: 5
  maxMessages: 100
}

batching:
  latencySeconds: 5
  maxMessages: 100

Utiliser des points de terminaison OpenTelemetry dans des graphiques de flux de données

Sélectionnez des points de terminaison de flux de données OTEL comme destinations dans les graphes de flux de données modernes. À l’aide de cette fonctionnalité, vous pouvez router les métriques et les journaux directement vers des backends compatibles OTEL. Les points de terminaison OTEL ne sont pas disponibles comme destinations dans les flux de données classiques. Cette restriction garantit la compatibilité avec les back-ends qui ne prennent pas en charge les points de terminaison OTEL.

Procédure pas à pas : configurer un point de terminaison de flux de données OTEL

Cette section fournit des étapes détaillées pour créer et configurer un point de terminaison de flux de données OTEL dans Opérations Azure IoT.

Étape 1 : Créer un point de terminaison de flux de données OTEL

Lorsque vous créez un nouveau point de terminaison de flux de données, sélectionnez OpenTelemetry (OTEL) comme type de point de terminaison. Vérifiez que l’hôte est préfixé avec http://.

Suivez les étapes décrites dans Déployer les ressources d’observabilité et configurez les journaux.

Étape 2 : Créer un graphique de flux de données à l’aide du point de terminaison OTEL

Créez un flux de données avec la ressource comme source. Vérifiez que la métrique que vous souhaitez envoyer à OTEL est un point de données dans l'actif. L’exemple suivant utilise une valeur de température. Sélectionnez le graphe de flux de données OTEL :

Étape 3 : Configurer le point de terminaison OTEL comme destination

Sélectionnez le nœud source et entrez les détails. Dans cet exemple, vous sélectionnez la métrique de température comme point de données à envoyer au point de terminaison SEE.

Sélectionnez OTEL comme destination, puis entrez les détails requis.

Gestion des erreurs et dépannage

Cette section décrit la gestion des erreurs et les informations de résolution des problèmes pour les points de terminaison OpenTelemetry.

Validation des messages

Les points de terminaison OpenTelemetry valident les messages entrants par rapport au schéma requis. Le système supprime les messages non valides et les reconnaît pour empêcher la perte de messages dans le pipeline de flux de données.

Les erreurs de validation courantes sont les suivantes :

• Champs obligatoires manquants (name, type et value pour les métriques ; value et level pour les journaux)
• Types de métriques ou niveaux de journal non valides
• Valeurs non numériques dans les champs de métrique value
• Valeurs d'horodatage malformées

Garanties de livraison

Le point de terminaison OpenTelemetry fournit des garanties de remise au collecteur lui-même, mais pas aux services en amont auxquels le collecteur peut transférer des données. Une fois que les données atteignent le collecteur, Opérations Azure IoT n’a pas de visibilité sur la destination finale.

Contenu connexe

• Créer un flux de données
• Configurer des points de terminaison de flux de données
• Configurer des points de terminaison de flux de données MQTT