Configurare gli endpoint del flusso di dati OpenTelemetry (anteprima)

Importante

Questa pagina include istruzioni per la gestione dei componenti di Operazioni IoT di Azure usando i manifesti di distribuzione kubernetes, disponibile in ANTEPRIMA. Questa funzionalità viene fornita con diverse limitazioni e non deve essere usata per i carichi di lavoro di produzione.

Vedere le condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure per termini legali aggiuntivi che si applicano a funzionalità di Azure in versione beta, in anteprima o in altro modo non ancora disponibili a livello generale.

Gli endpoint del flusso di dati OpenTelemetry vengono usati per inviare metriche e log agli agenti di raccolta OpenTelemetry, che possono quindi inoltrare i dati a piattaforme di osservabilità come dashboard di Grafana e Monitoraggio di Azure. È possibile configurare le impostazioni dell'endpoint, l'autenticazione, Tls (Transport Layer Security) e le opzioni di invio in batch.

Prerequisiti

Istanza delle operazioni di Azure IoT
Raccoglitore OpenTelemetry distribuito e accessibile dal cluster Azure IoT Operations.

Panoramica dell'endpoint OpenTelemetry

Gli endpoint OpenTelemetry consentono di esportare i dati di telemetria dai flussi di dati delle operazioni di Azure IoT agli agenti di raccolta OpenTelemetry usando il protocollo OTLP (OpenTelemetry Protocol). In questo modo è possibile integrare i dati di telemetria del dispositivo e del sistema nell'infrastruttura di osservabilità esistente.

Scenari comuni

Diagnostica dei dispositivi: esportare temperatura, pressione e altre letture dei sensori come metriche per monitorare l'integrità dei dispositivi
Monitoraggio della fabbrica: inviare la telemetria di produzione alle dashboard di Grafana per una visibilità operativa
Osservabilità del sistema: inoltrare i log e le metriche delle applicazioni a Monitoraggio di Azure per il monitoraggio centralizzato
Metriche personalizzate: aggiungere attributi contestuali come l'ID factory o la posizione alle metriche per migliorare il filtro e l'analisi

Requisiti relativi al formato dei dati

Gli endpoint OpenTelemetry richiedono che i dati siano conformi a uno schema JSON specifico con una matrice metrics, una matrice logs o entrambe. I messaggi che non sono conformi a questo schema vengono eliminati e riconosciuti per evitare la perdita di messaggi.

Il payload JSON deve usare questa struttura di primo livello:

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

Almeno uno di metrics o logs deve essere presente.

Tutti i messaggi in arrivo vengono convalidati rispetto allo schema richiesto. I messaggi che non superano la convalida vengono eliminati, riconosciuti al broker e loggati per la risoluzione dei problemi. Gli errori di convalida comuni includono campi obbligatori mancanti, tipi di dati non validi, tipi di metriche o livelli di log non supportati e timestamp non validi. Se i messaggi MQTT includono timestamp di scadenza, i messaggi scaduti vengono filtrati prima dell'elaborazione.

Formato delle metriche

Ogni oggetto metrica nella metrics matrice deve contenere i campi seguenti:

Campi obbligatori:

name (stringa): nome della metrica
type (string): tipo di metrica (vedere tipi di metriche supportati)
value (numero): valore numerico della metrica

Campi facoltativi:

description (stringa): Descrizione leggibile della metrica
timestamp (numero): timestamp del periodo Unix in nanosecondi quando la metrica è stata registrata
attributes (matrice): coppie chiave-valore per l'etichettatura e il filtro delle metriche

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

Ogni attributo nella attributes matrice deve avere:

key (string): nome dell'attributo
value (string): il valore dell'attributo (deve essere una stringa)

Formato dei log

Ogni oggetto di log nella logs matrice deve contenere i campi seguenti:

Campi obbligatori:

value (string): Registrare il contenuto del messaggio
level (stringa): livello di log (vedere livelli di log supportati)

Campi facoltativi:

timestamp (numero): timestamp del periodo Unix in nanosecondi quando il log è stato registrato
attributes (array): coppie chiave-valore per il contesto di log e il filtro

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

Ogni attributo nella attributes matrice deve avere:

key (string): nome dell'attributo
value (string): il valore dell'attributo (deve essere una stringa)

Tipi di metriche supportati

Sono supportati i tipi di metrica OpenTelemetry seguenti:

Contatori: u64_counter, f64_counter - Valori che aumentano in modo monotonico
Contatori su/giù: i64_up_down_counter, f64_up_down_counter - Valori che possono aumentare o diminuire
Misuratori: u64_gauge, i64_gauge, f64_gauge - Valori in uno specifico momento
Istogrammi: f64_histogram, u64_histogram - Distribuzione dei valori

Livelli di log supportati

Sono supportati i livelli di log seguenti:

trace
debug
info
warn
error
fatal

Creare un endpoint OpenTelemetry

È possibile creare un endpoint del flusso di dati OpenTelemetry usando l'esperienza operativa, Bicep o Kubernetes.

Per creare un flusso di dati OpenTelemetry nell'esperienza operativa, passare agli endpoint del flusso di dati.
Nella pagina endpoint del flusso di dati, identificare Open Telemetry e selezionare + Nuovo.
Nel riquadro Crea nuovo flusso di dati: Apri telemetria selezionare la scheda Configurazione di base e specificare le informazioni seguenti:
- Nome: nome univoco per l'endpoint.
- Host: endpoint del raccoglitore OpenTelemetry nel formato<host>:<port>, ad esempiootel-collector.monitoring.svc.cluster.local:4317.
- Metodo di autenticazione: scegliere uno dei metodi di autenticazione seguenti:
  - Token dell'account del servizio Kubernetes: usa i token dell'account del servizio Kubernetes per l'autenticazione con l'agente di raccolta OpenTelemetry. Fornire il valore del gruppo di destinatari per la configurazione dell'agente di raccolta OpenTelemetry. Per altri dettagli, vedere Service Account Token (SAT).
  - Anonimo: usare quando l'agente di raccolta OpenTelemetry non richiede l'autenticazione.
  - Certificato X509: usa i certificati client per l'autenticazione TLS reciproca. Specificare il nome di un segreto Kubernetes contenente il certificato client. Per altri dettagli, vedere Certificato X.509 .
Selezionare la scheda Configurazione avanzata e specificare le informazioni seguenti:
- Latenza di invio in batch (in secondi): tempo massimo di attesa prima dell'invio di un batch. Il valore predefinito è 5 secondi.
- Conteggio messaggi: numero massimo di messaggi in un batch. Il valore predefinito è 100000 messaggi.
- Modalità TLS: scegliere una delle modalità TLS seguenti:
  - Abilitato: abilita TLS per la comunicazione sicura con l'agente di raccolta OpenTelemetry. Specificare il nome di una ConfigMap Kubernetes contenente il certificato di certificazione attendibile.
  - Disabilitato: disabilita TLS.
- Nome della mappa di configurazione del certificato CA attendibile: il nome di un ConfigMap di Kubernetes che contiene il certificato CA attendibile.
Selezionare Applica per creare l'endpoint OpenTelemetry.

Creare un file Bicep .bicep con il contenuto seguente. Aggiornare le impostazioni in base alle esigenze e sostituire i valori segnaposto, come <AIO_INSTANCE_NAME>, con i propri valori.

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

Distribuire il file eseguendo il comando seguente dell'interfaccia della riga di comando di Azure:

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

Creare un file manifesto .yaml Kubernetes con il contenuto seguente:

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

Applicare il file manifesto al cluster Kubernetes:

kubectl apply -f <FILE>.yaml

Opzioni di configurazione

Questa sezione descrive le opzioni di configurazione per gli endpoint del flusso di dati OpenTelemetry.

Host

La host proprietà specifica l'URL dell'endpoint dell'agente di raccolta OpenTelemetry. Includere il protocollo (http:// o https://) e il numero di porta.

Esempi:

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

Autenticazione

Gli endpoint OpenTelemetry supportano diversi metodi di autenticazione per connettersi in modo sicuro agli agenti di raccolta.

Token account servizio (SAT)

L'autenticazione tramite token account servizio (SAT) usa token dell'account del servizio Kubernetes per l'autenticazione con il collettore OpenTelemetry.

Sostituire <OTEL_AUDIENCE> con il valore del gruppo di destinatari per la configurazione dell'agente di raccolta OpenTelemetry. Questo valore deve corrispondere al gruppo di destinatari previsto nell'agente di raccolta.

Nel riquadro Crea nuovo endpoint del flusso di dati: Open Telemetry, nella scheda di configurazione Basics, selezionare Token dell'account del servizio Kubernetes come metodo di autenticazione.
Specificare il valore del gruppo di destinatari del servizio per la configurazione dell'agente di raccolta OpenTelemetry.

Importante

È possibile scegliere il metodo di autenticazione solo quando si crea un nuovo endpoint del flusso di dati OpenTelemetry. Non è possibile modificare il metodo di autenticazione dopo la creazione dell'endpoint del flusso di dati OpenTelemetry. Se si vuole modificare il metodo di autenticazione di un flusso di dati esistente, eliminare il flusso di dati originale e crearne uno nuovo con il nuovo metodo di autenticazione.

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

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

Certificato X.509

L'autenticazione del certificato X.509 usa certificati client per l'autenticazione TLS reciproca.

Nel riquadro Crea nuovo flusso di dati: Aprire telemetria nella scheda Configurazione di base selezionare Certificato X509 come metodo di autenticazione.
Fornire le informazioni seguenti da Azure Key Vault:
- Nome segreto sincronizzato: nome di un segreto Kubernetes contenente il certificato client.
- Certificato client X509: certificato client.
- Chiave client X509: chiave privata per il certificato client.
- Certificati intermedi X509: certificati intermedi per la catena di certificati client.

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

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

Prima di usare l'autenticazione del certificato X.509, creare un segreto Kubernetes con il certificato client:

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

Autenticazione anonima

L'autenticazione anonima viene usata quando l'agente di raccolta OpenTelemetry non richiede l'autenticazione.

Nel riquadro Crea nuovo flusso di dati: Aprire telemetria nella scheda Configurazione di base selezionare Anonimo come metodo di autenticazione. Non sono necessarie impostazioni aggiuntive.

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

authentication:
  method: Anonymous
  anonymousSettings: {}

Configurazione TLS

Configurare le impostazioni tls (Transport Layer Security) per la comunicazione sicura con l'agente di raccolta OpenTelemetry.

Abilitazione di TLS con CA attendibile

Nel riquadro Crea nuovo flusso di dati: Aprire telemetria nella scheda Configurazione avanzata selezionare Abilitato come modalità TLS.
In Trusted CA certificate config map name (Nome mappa di configurazione certificato CA attendibile) specificare il nome di un file ConfigMap di Kubernetes contenente il certificato ca attendibile.

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

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

TLS disabilitato

Nel riquadro Crea nuovo flusso di dati: Aprire il riquadro Telemetria , nella scheda Configurazione avanzata selezionare Disabilitato come modalità TLS.

tls: {
  mode: 'Disabled'
}

tls:
  mode: Disabled

Creazione di batch

Configurare le impostazioni di invio in batch per ottimizzare le prestazioni raggruppando più messaggi prima dell'invio all'agente di raccolta.

Nel riquadro Crea nuovo endpoint del flusso di dati: Open Telemetry, nella scheda di configurazione Avanzata, specificare le seguenti impostazioni di batching:

Latenza di invio in batch (in secondi): tempo massimo di attesa prima dell'invio di un batch. Il valore predefinito è 5 secondi.
Conteggio messaggi: numero massimo di messaggi in un batch. Il valore predefinito è 100000 messaggi.

batching: {
  latencySeconds: 5
  maxMessages: 100
}

Proprietà	Descrizione	Predefinito
`latencySeconds`	Tempo massimo di attesa prima dell'invio di un batch.	60 secondi
`maxMessages`	Numero massimo di messaggi in un batch.	100000 messaggi

batching:
  latencySeconds: 5
  maxMessages: 100

Proprietà	Descrizione	Predefinito
`latencySeconds`	Tempo massimo di attesa prima dell'invio di un batch.	60 secondi
`maxMessages`	Numero massimo di messaggi in un batch.	100000 messaggi

Gestione degli errori e risoluzione dei problemi

Convalida dei messaggi

Gli endpoint OpenTelemetry convalidano i messaggi in ingresso rispetto allo schema richiesto. I messaggi non validi vengono eliminati e riconosciuti per evitare la perdita di messaggi nella pipeline del flusso di dati.

Errori di convalida comuni:

Campi obbligatori mancanti (name, type, value per le metriche; value, level per i log)
Tipi di metriche o livelli di log non validi
Valori non numerici nei campi delle metriche value
Valori timestamp non validi

Garanzie di recapito

L'endpoint OpenTelemetry fornisce garanzie di recapito all'agente di raccolta, ma non ai servizi upstream a cui l'agente di raccolta può inoltrare i dati. Quando i dati raggiungono l'agente di raccolta, Le operazioni IoT di Azure non hanno visibilità sul fatto che raggiungano la destinazione finale.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-02