OpenTelemetry-gegevensstroomeindpunten configureren (preview)

Belangrijk

Deze pagina bevat instructies voor het beheren van Azure IoT Operations-onderdelen met behulp van Kubernetes-implementatiemanifesten, die zich in PREVIEW bevinden. Deze functie is voorzien van verschillende beperkingen en mag niet worden gebruikt voor productieworkloads.

Zie de Aanvullende Gebruiksvoorwaarden voor Microsoft Azure Previews voor juridische voorwaarden die van toepassing zijn op Azure-functies die in bèta, preview, of anderszins nog niet algemeen beschikbaar zijn.

OpenTelemetry-gegevensstroomeindpunten worden gebruikt om metrische gegevens en logboeken te verzenden naar OpenTelemetry-collectors, waarmee de gegevens vervolgens kunnen worden doorgestuurd naar waarneembaarheidsplatforms zoals Grafana-dashboards en Azure Monitor. U kunt de eindpuntinstellingen, verificatie, TLS (Transport Layer Security) en batchverwerkingsopties configureren.

Vereiste voorwaarden

• Een exemplaar van Azure IoT-bewerkingen
• Een OpenTelemetry-collector geïmplementeerd en toegankelijk vanuit uw Azure IoT Operations-cluster

Overzicht van OpenTelemetry-eindpunten

Met OpenTelemetry-eindpunten kunt u telemetriegegevens uit Azure IoT Operations-gegevensstromen exporteren naar OpenTelemetry-collectors met behulp van het OtLP (OpenTelemetry Protocol). Hierdoor kunt u apparaat- en systeemtelemetrie integreren in uw bestaande waarneembaarheidsinfrastructuur.

Algemene scenario's

• Apparaatdiagnose: Temperatuur, druk en andere sensormetingen exporteren als metrische gegevens om de apparaatstatus te bewaken
• Factorybewaking: Telemetrie van productielijnen verzenden naar Grafana-dashboards voor operationele zichtbaarheid
• Waarneembaarheid van het systeem: Toepassingslogboeken en metrische gegevens doorsturen naar Azure Monitor voor gecentraliseerde bewaking
• Aangepaste metrische gegevens: contextuele kenmerken zoals factory-id of locatie toevoegen aan metrische gegevens voor betere filtering en analyse

Vereisten voor gegevensindeling

OpenTelemetry-eindpunten vereisen dat gegevens voldoen aan een specifiek JSON-schema met een metrics matrix, een logs matrix of beide. Berichten die niet aan dit schema voldoen, worden verwijderd en bevestigd om verlies van berichten te voorkomen.

De JSON-nettolading moet gebruikmaken van deze structuur op het hoogste niveau:

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

Ten minste één van metrics of logs moet aanwezig zijn.

Alle binnenkomende berichten worden gevalideerd op basis van het vereiste schema. Berichten die niet worden gevalideerd, worden verwijderd, bevestigd bij de broker en geregistreerd voor probleemoplossing. Veelvoorkomende validatiefouten zijn ontbrekende vereiste velden, ongeldige gegevenstypen, niet-ondersteunde metrische typen of logboekniveaus en ongeldige tijdstempels. Als MQTT-berichten verlooptijdenstempels bevatten, worden verlopen berichten gefilterd voordat ze worden verwerkt.

Indeling voor metrische gegevens

Elk metrische object in de metrics matrix moet de volgende velden bevatten:

Vereiste velden:

• name (tekenreeks): de naam van de metrische waarde
• type (tekenreeks): het metrische type (zie ondersteunde metrische typen)
• value (getal): De numerieke waarde van de metrische waarde

Optionele velden:

• description (tekenreeks): Door mensen leesbare beschrijving van de metrische waarde
• timestamp (getal): Unix-tijdstempel in nanoseconden toen de metrische waarde werd vastgelegd
• attributes (matrix): sleutel-waardeparen voor het labelen en filteren van metrische gegevens

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

Elk kenmerk in de attributes matrix moet het volgende hebben:

• key (tekenreeks): de kenmerknaam
• value (tekenreeks): De kenmerkwaarde (moet een tekenreeks zijn)

Logboekindeling

Elk logboekobject in de logs matrix moet de volgende velden bevatten:

Vereiste velden:

• value (tekenreeks): Inhoud van logboekbericht
• level (tekenreeks): logboekniveau (zie ondersteunde logboekniveaus)

Optionele velden:

• timestamp (getal): Unix epoch timestamp in nanoseconden toen het logboek werd vastgelegd
• attributes (matrix): sleutel-waardeparen voor logboekcontext en filteren

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

Elk kenmerk in de attributes matrix moet het volgende hebben:

• key (tekenreeks): de kenmerknaam
• value (tekenreeks): De kenmerkwaarde (moet een tekenreeks zijn)

Ondersteunde typen metrische gegevens

De volgende metrische typen OpenTelemetry worden ondersteund:

• Tellers: u64_counter, f64_counter - Monotonisch verhogende waarden
• Tellers omhoog/omlaag: i64_up_down_counter, f64_up_down_counter - Waarden die kunnen toenemen of verlagen
• Meters: u64_gauge, i64_gauge, f64_gauge - point-in-time-waarden
• Histogrammen: f64_histogram, u64_histogram - Verdeling van waarden

Ondersteunde logboekniveaus

De volgende logboekniveaus worden ondersteund:

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

OpenTelemetry-eindpunt maken

U kunt een OpenTelemetry-gegevensstroomeindpunt maken met behulp van de bewerkingservaring, Bicep of Kubernetes.

Bewerkingservaring

1. Als u een OpenTelemetry-gegevensstroom wilt maken in de bewerkingservaring, gaat u naar de eindpunten van de gegevensstroom.

2. Identificeer Open Telemetry op de eindpuntenpagina van de gegevensstroom en selecteer + Nieuw.

   

3. Selecteer in het deelvenster Nieuw gegevensstroomeindpunt maken: Open Telemetry het tabblad Basisconfiguratie en geef de volgende informatie op:

   • Naam: Een unieke naam voor het eindpunt.
   • Host: Het eindpunt van de OpenTelemetry-collector in de indeling<host>:<port>, bijvoorbeeld otel-collector.monitoring.svc.cluster.local:4317.
   • Verificatiemethode: kies een van de volgende verificatiemethoden:
     • Kubernetes-serviceaccounttoken: gebruikt Kubernetes-serviceaccounttokens om te verifiëren met de OpenTelemetry-collector. Geef de doelgroepwaarde op voor de configuratie van de OpenTelemetry-collector. Zie Service Account Token (SAT) voor meer informatie.
     • Anoniem: Gebruik deze functie wanneer de OpenTelemetry-collector geen verificatie vereist.
     • X509-certificaat: maakt gebruik van clientcertificaten voor wederzijdse TLS-verificatie. Geef de naam op van een Kubernetes-secret met je clientcertificaat. Zie het X.509-certificaat voor meer informatie.

   

4. Selecteer het tabblad Geavanceerde configuratie en geef de volgende informatie op:

   • Batchlatentie (in seconden): Maximale tijd die moet worden gewacht voordat een batch wordt verzonden. De standaardwaarde is 5 seconden.
   • Aantal berichten: Maximum aantal berichten in een batch. De standaardwaarde is 100000 berichten.
   • TLS-modus: kies een van de volgende TLS-modi:
     • Ingeschakeld: hiermee schakelt u TLS in voor beveiligde communicatie met de OpenTelemetry-collector. Geef de naam op van een Kubernetes ConfigMap die uw vertrouwde CA-certificaat bevat.
     • Uitgeschakeld: hiermee schakelt u TLS uit.
   • Naam van de ConfigMap van het vertrouwde CA-certificaat: de naam van een Kubernetes ConfigMap met uw vertrouwde CA-certificaat.

   

5. Selecteer Toepassen om het OpenTelemetry-eindpunt te maken.

Biceps

Maak een Bicep-bestand .bicep met de volgende inhoud. Werk de instellingen indien nodig bij en vervang de tijdelijke aanduidingen, zoals <AIO_INSTANCE_NAME> door uw waarden.

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

Implementeer het bestand door de volgende Azure CLI-opdracht uit te voeren:

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

Kubernetes (preview)

Maak een Kubernetes-manifestbestand .yaml met de volgende inhoud:

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

Pas het manifestbestand toe op het Kubernetes-cluster:

kubectl apply -f <FILE>.yaml

Configuratieopties

In deze sectie worden configuratieopties beschreven voor Eindpunten van openTelemetry-gegevensstromen.

Gastheer (or Gastvrouw)

De host eigenschap geeft de eindpunt-URL van de OpenTelemetry-collector op. Neem het protocol (http:// of https://) en het poortnummer op.

Voorbeelden:

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

Authenticatie

OpenTelemetry-eindpunten ondersteunen verschillende verificatiemethoden om veilig verbinding te maken met verzamelaars.

Token voor serviceaccount (SAT)

Verificatie van serviceaccounttoken (SAT) maakt gebruik van Kubernetes-serviceaccounttokens om te verifiëren met de OpenTelemetry-collector.

Vervang <OTEL_AUDIENCE> door de doelgroepwaarde voor de configuratie van uw OpenTelemetry-collector. Deze waarde moet overeenkomen met de verwachte doelgroep op de collector.

Bewerkingservaring

1. Selecteer in het paneel Nieuw gegevensstroom-eindpunt: Open Telemetrie, onder het tabblad Basisconfiguratie, Kubernetes-serviceaccounttoken als verificatiemethode.

2. Geef de waarde van de servicedoelgroep op voor de configuratie van de OpenTelemetry-collector.

   

Belangrijk

U kunt alleen de verificatiemethode kiezen bij het maken van een nieuw OpenTelemetry-gegevensstroomeindpunt. U kunt de verificatiemethode niet wijzigen nadat het eindpunt van de OpenTelemetry-gegevensstroom is gemaakt. Als u de verificatiemethode van een bestaande gegevensstroom wilt wijzigen, verwijdert u de oorspronkelijke gegevensstroom en maakt u een nieuwe met de nieuwe verificatiemethode.

Biceps

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

Kubernetes (preview)

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

X.509-certificaat

X.509-certificaatverificatie maakt gebruik van clientcertificaten voor wederzijdse TLS-verificatie.

Bewerkingservaring

1. Selecteer in het deelvenster Maak nieuw gegevensstroom-eindpunt: Open Telemetrie, onder het tabblad Basisconfiguratie, X509-certificaat als verificatiemethode.

2. Geef de volgende informatie op uit Azure Key Vault:

   • Gesynchroniseerde geheime naam: de naam van een Kubernetes-geheim met uw clientcertificaat.
   • X509-clientcertificaat: het clientcertificaat.
   • X509-clientsleutel: de persoonlijke sleutel voor het clientcertificaat.
   • X509 tussenliggende certificaten: de tussenliggende certificaten voor de client-certificaatketen.

   

Biceps

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

Kubernetes (preview)

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

Voordat u X.509-certificaatverificatie gebruikt, maakt u een Kubernetes-geheim met uw clientcertificaat:

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

Anonieme authenticatie

Anonieme verificatie wordt gebruikt wanneer de OpenTelemetry-collector geen verificatie vereist.

Bewerkingservaring

Selecteer Anoniem als verificatiemethode in het deelvenster Nieuwe gegevensstroom maken: Open het deelvenster Telemetrie, op het tabblad Basisconfiguratie. Er zijn geen extra instellingen vereist.

Biceps

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

Kubernetes (preview)

authentication:
  method: Anonymous
  anonymousSettings: {}

TLS-configuratie

Configureer TLS-instellingen (Transport Layer Security) voor beveiligde communicatie met de OpenTelemetry-collector.

TLS met vertrouwde CA ingeschakeld

Bewerkingservaring

1. Selecteer in het deelvenster Nieuw stroomgegevens-eindpunt maken: Open Telemetrie, onder het tabblad Geavanceerd voor configuratie, Ingeschakeld als de TLS-modus.
2. Geef in de configuratietoewijzingsnaam van het vertrouwde CA-certificaat de naam op van een Kubernetes ConfigMap die uw vertrouwde CA-certificaat bevat.

Biceps

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

Kubernetes (preview)

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

Uitgeschakelde TLS

Bewerkingservaring

Selecteer in het deelvenster Nieuwe gegevensstroom-eindpunt maken: Open Telemetry, onder het tabblad Geavanceerde configuratie, Uitgeschakeld als TLS-modus.

Biceps

tls: {
  mode: 'Disabled'
}

Kubernetes (preview)

tls:
  mode: Disabled

Batchverwerking

Configureer batchinstellingen om de prestaties te optimaliseren door meerdere berichten te groeperen voordat u naar de collector verzendt.

Bewerkingservaring

Geef in het deelvenster Nieuwe gegevensstroom-eindpunt maken: Open Telemetrie onder het tabblad Geavanceerde configuratie de volgende batchinstellingen:

• Batchlatentie (in seconden): Maximale tijd die moet worden gewacht voordat een batch wordt verzonden. De standaardwaarde is 5 seconden.
• Aantal berichten: Maximum aantal berichten in een batch. De standaardwaarde is 100000 berichten.

Biceps

batching: {
  latencySeconds: 5
  maxMessages: 100
}

Vastgoed	Beschrijving	Verstek
latencySeconds	Maximale tijd om te wachten voordat een batch wordt verzonden.	60 seconden
maxMessages	Maximum aantal berichten in een batch.	100000 berichten

Kubernetes (preview)

batching:
  latencySeconds: 5
  maxMessages: 100

Vastgoed	Beschrijving	Verstek
latencySeconds	Maximale tijd om te wachten voordat een batch wordt verzonden.	60 seconden
maxMessages	Maximum aantal berichten in een batch.	100000 berichten

Foutverwerking en het oplossen van problemen

Berichtvalidatie

OpenTelemetry-eindpunten valideren binnenkomende berichten op basis van het vereiste schema. Ongeldige berichten worden verwijderd en bevestigd om berichtverlies in de gegevensstroompijplijn te voorkomen.

Veelvoorkomende validatiefouten:

• Vereiste velden ontbreken (name, typevalue voor metrische gegevens; valuelevel voor logboeken)
• Ongeldige metrische typen of logboekniveaus
• Niet-numerieke waarden in metrische value velden
• Ongeldige tijdstempelwaarden

Leveringsgaranties

Het OpenTelemetry-eindpunt biedt leveringsgaranties aan de collector zelf, maar niet aan upstream-services waarnaar de collector gegevens kan doorsturen. Zodra de gegevens de collector bereiken, hebben Azure IoT-bewerkingen geen inzicht in of deze de uiteindelijke bestemming bereiken.

Verwante inhoud

• Een gegevensstroom maken
• Gegevensstroomeindpunten configureren
• MQTT-gegevensstroomeindpunten configureren