Konfigurera OpenTelemetry-dataflödesslutpunkter (förhandsversion)

OpenTelemetry-dataflödesslutpunkter används för att skicka mått och loggar till OpenTelemetry-insamlare, som sedan kan vidarebefordra data till observerbarhetsplattformar som Grafana-instrumentpaneler och Azure Monitor. Du kan konfigurera slutpunktsinställningar, autentisering, TLS (Transport Layer Security) och batchhanteringsalternativ.

Förutsättningar

• En instans av Azure IoT Operations
• En OpenTelemetry-insamlare som distribueras och är tillgänglig från ditt Azure IoT Operations-kluster

Översikt över OpenTelemetry-slutpunkt

Med OpenTelemetry-slutpunkter kan du exportera telemetridata från Azure IoT Operations-dataflöden till OpenTelemetry-insamlare med hjälp av OpenTelemetry Protocol (OTLP). På så sätt kan du integrera enhets- och systemtelemetri i din befintliga observerbarhetsinfrastruktur.

Vanliga scenarier

• Enhetsdiagnostik: Exportera temperatur, tryck och andra sensoravläsningar som mått för att övervaka enhetens hälsa
• Fabriksövervakning: Skicka telemetri för produktionslinjen till Grafana-instrumentpaneler för driftssynlighet
• Systemobservabilitet: Vidarebefordra programloggar och mått till Azure Monitor för centraliserad övervakning
• Anpassade mått: Lägg till kontextuella attribut som fabriks-ID eller plats till mått för bättre filtrering och analys

Krav för dataformat

OpenTelemetry-slutpunkter kräver att data överensstämmer med ett specifikt JSON-schema med antingen en metrics matris, en logs matris eller båda. Meddelanden som inte överensstämmer med det här schemat tas bort och bekräftas för att förhindra meddelandeförlust.

JSON-nyttolasten måste använda den här strukturen på den översta nivån:

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

Minst en av metrics eller logs måste finnas.

Alla inkommande meddelanden verifieras mot det obligatoriska schemat. Meddelanden som misslyckas med valideringen tas bort, bekräftas tillbaka till asynkron meddelandekö och loggas för felsökning. Vanliga valideringsfel är saknade obligatoriska fält, ogiltiga datatyper, måtttyper som inte stöds eller loggnivåer och felaktiga tidsstämplar. Om MQTT-meddelanden innehåller tidsstämplar för förfallotid filtreras utgångna meddelanden ut före bearbetning.

Måttformat

Varje måttobjekt i matrisen metrics måste innehålla följande fält:

Obligatoriska fält:

• name (sträng): Måttnamnet
• type (sträng): Måtttypen (se måtttyper som stöds)
• value (tal): Måttets numeriska värde

Valfria fält:

• description (sträng): Beskrivning av måttet som kan läsas av människa
• timestamp (tal): Unix epoktidsstämpel i nanosekunder när måttet registrerades
• attributes (matris): Nyckel/värde-par för måttetiketter och filtrering

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

Varje attribut i matrisen attributes måste ha:

• key (sträng): Attributnamnet
• value (sträng): Attributvärdet (måste vara en sträng)

Loggformat

Varje loggobjekt i matrisen logs måste innehålla följande fält:

Obligatoriska fält:

• value (sträng): Logga meddelandeinnehåll
• level (sträng): Loggnivå (se loggnivåer som stöds)

Valfria fält:

• timestamp (tal): Unix epoktidsstämpel i nanosekunder när loggen registrerades
• attributes (matris): Nyckel/värde-par för loggkontext och filtrering

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

Varje attribut i matrisen attributes måste ha:

• key (sträng): Attributnamnet
• value (sträng): Attributvärdet (måste vara en sträng)

Måtttyper som stöds

Följande OpenTelemetry-måtttyper stöds:

• Räknare: u64_counter, f64_counter – Monotont ökande värden
• Upp-/nedräknare: i64_up_down_counter, f64_up_down_counter – Värden som kan öka eller minska
• Mätare: u64_gauge, i64_gauge, f64_gauge – Punkt-i-tid-värden
• Histogram: f64_histogram, u64_histogram – Fördelning av värden

Loggnivåer som stöds

Följande loggnivåer stöds:

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

Skapa OpenTelemetry-slutpunkt

Du kan skapa en OpenTelemetry-dataflödesslutpunkt med hjälp av driftupplevelsen, Bicep eller Kubernetes.

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

Konfigurationsalternativ

I det här avsnittet beskrivs konfigurationsalternativ för OpenTelemetry-dataflödesslutpunkter.

värd

Egenskapen host anger url:en för OpenTelemetry-insamlarens slutpunkt. Inkludera protokollet (http:// eller https://) och portnumret.

Exempel:

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

Autentisering

OpenTelemetry-slutpunkter stöder flera autentiseringsmetoder för att ansluta säkert till insamlare.

Tjänstkontotoken (SAT)

Autentisering med tjänstkontotoken (SAT) använder Kubernetes-tjänstkontotoken för att autentisera med OpenTelemetry-insamlaren.

Ersätt <OTEL_AUDIENCE> med målgruppsvärdet för konfigurationen av OpenTelemetry-insamlaren. Det här värdet måste matcha den förväntade målgruppen på insamlaren.

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

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

X.509-certifikat

X.509-certifikatautentisering använder klientcertifikat för ömsesidig TLS-autentisering.

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

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

Innan du använder X.509-certifikatautentisering skapar du en Kubernetes-hemlighet med ditt klientcertifikat:

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

Anonym autentisering

Anonym autentisering används när OpenTelemetry-insamlaren inte kräver autentisering.

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

authentication:
  method: Anonymous
  anonymousSettings: {}

TLS-konfiguration

Konfigurera TLS-inställningar (Transport Layer Security) för säker kommunikation med OpenTelemetry-insamlaren.

Aktiverad TLS med betrodd ca

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

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

Inaktiverad TLS

tls: {
  mode: 'Disabled'
}

tls:
  mode: Disabled

Batchhantering

Konfigurera batchinställningar för att optimera prestanda genom att gruppera flera meddelanden innan du skickar till insamlaren.

batching: {
  latencySeconds: 5
  maxMessages: 100
}

batching:
  latencySeconds: 5
  maxMessages: 100

Felhantering och felsökning

Meddelandeverifiering

OpenTelemetry-slutpunkter validerar inkommande meddelanden mot det obligatoriska schemat. Ogiltiga meddelanden tas bort och bekräftas för att förhindra meddelandeförlust i dataflödespipelinen.

Vanliga valideringsfel:

• Obligatoriska fält saknas (name, , typevalueför mått; value, level för loggar)
• Ogiltiga måtttyper eller loggnivåer
• Icke-numeriska värden i måttfält value
• Felformade tidsstämpelvärden

Leveransgarantier

OpenTelemetry-slutpunkten ger leveransgarantier till själva insamlaren, men inte till överordnade tjänster som insamlaren kan vidarebefordra data till. När data når insamlaren har Azure IoT Operations inte insyn i om de når det slutliga målet.

Relaterat innehåll

• Skapa ett dataflöde
• Konfigurera dataflödesslutpunkter
• Konfigurera MQTT-slutpunkter för dataflöde