Konfigurace koncových bodů toku dat OpenTelemetry (Preview)

Důležité

Tato stránka obsahuje pokyny ke správě komponent operací Azure IoT pomocí manifestů nasazení Kubernetes, které jsou ve verzi Preview. Tato funkce je poskytována s několika omezeními a neměla by se používat pro produkční úlohy.

Podívejte se na doplňkové podmínky užívání služby Microsoft Azure Preview pro právní podmínky, které se vztahují na funkce Azure, jež jsou ve verzi beta, Preview nebo jinak ještě nejsou obecně dostupné.

Koncové body toku dat OpenTelemetry se používají k odesílání metrik a protokolů do kolektorů OpenTelemetry, které pak můžou data předávat na platformy pozorovatelnosti, jako jsou řídicí panely Grafana a Azure Monitor. Můžete nakonfigurovat nastavení koncového bodu, ověřování, protokol TLS (Transport Layer Security) a možnosti dávkování.

Požadavky

• Instance Azure IoT Operations
• Kolekce OpenTelemetry nasazená a přístupná z vašeho clusteru Azure IoT Operations

Přehled koncového bodu OpenTelemetry

Koncové body OpenTelemetry umožňují exportovat telemetrická data z toků dat operací Azure IoT do kolektorů OpenTelemetry pomocí protokolu OTLP (OpenTelemetry Protocol). Díky tomu můžete integrovat telemetrii zařízení a systému do stávající infrastruktury pozorovatelnosti.

Obvyklé scénáře

• Diagnostika zařízení: Export teploty, tlaku a dalších snímačů jako metriky pro monitorování stavu zařízení
• Monitorování továrny: Odeslání telemetrie výrobní linky do řídicích panelů Grafana za účelem zajištění provozní viditelnosti
• Pozorovatelnost systému: Předávání protokolů a metrik aplikací do služby Azure Monitor pro centralizované monitorování
• Vlastní metriky: Přidání kontextových atributů, jako je ID továrny nebo umístění, do metrik pro lepší filtrování a analýzu

Požadavky na formát dat

Koncové body OpenTelemetry vyžadují, aby data odpovídala určitému schématu JSON s polem typu metrics, polem typu logs nebo obojím. Zprávy, které nevyhovují tomuto schématu, se zahodí a potvrdí, aby se zabránilo ztrátě zpráv.

Datová část JSON musí používat tuto strukturu nejvyšší úrovně:

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

Alespoň jeden z metrics nebo logs musí být přítomen.

Všechny příchozí zprávy se ověřují podle požadovaného schématu. Zprávy, které neprojdou ověřením, jsou zahozeny, potvrzeny zpět brokerovi a zaznamenány pro účely řešení potíží. Mezi běžná selhání ověřování patří chybějící požadovaná pole, neplatné datové typy, nepodporované typy metrik nebo úrovně protokolu a chybné časové razítka. Pokud zprávy MQTT obsahují časová razítka vypršení platnosti, odfiltrují se před zpracováním zprávy s vypršenou platností.

Formát metrik

Každý objekt metriky v metrics poli musí obsahovat následující pole:

Povinná pole:

• name (řetězec): Název metriky
• type (řetězec): Typ metriky (viz podporované typy metrik)
• value (číslo): Číselná hodnota metriky

Volitelná pole:

• description (řetězec): Popis metriky čitelný pro člověka
• timestamp (číslo): Časové razítko unixové epochy v nanosekundách při zaznamenání metriky
• attributes (pole): Páry klíč-hodnota pro označování a filtrování metrik

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

Každý atribut v attributes poli musí mít:

• key (řetězec): Název atributu
• value (řetězec): Hodnota atributu (musí být řetězec)

Formát protokolů

Každý objekt protokolu v logs poli musí obsahovat následující pole:

Povinná pole:

• value (řetězec): Obsah zprávy protokolu
• level (řetězec): Úroveň protokolu (viz podporované úrovně protokolů)

Volitelná pole:

• timestamp (číslo): Časové razítko unixové éry v nanosekundách při zaznamenání protokolu
• attributes (pole): Páry klíč-hodnota pro kontext protokolu a filtrování

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

Každý atribut v attributes poli musí mít:

• key (řetězec): Název atributu
• value (řetězec): Hodnota atributu (musí být řetězec)

Podporované typy metrik

Podporují se následující typy metrik OpenTelemetry:

• Čítače: u64_counter, f64_counter – Neustále se zvyšující hodnoty
• Čítače nahoru/dolů: i64_up_down_counter, f64_up_down_counter – hodnoty, které můžou zvýšit nebo snížit
• Měřidla: u64_gauge, i64_gauge, f64_gauge - Hodnoty v daném okamžiku
• Histogramy: f64_histogram, u64_histogram – Rozdělení hodnot

Podporované úrovně protokolů

Podporují se následující úrovně protokolů:

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

Vytvoření koncového bodu OpenTelemetry

Koncový bod toku dat OpenTelemetry můžete vytvořit pomocí provozního prostředí, Bicep nebo Kubernetes.

Zkušenosti z provozu

1. Pokud chcete v provozním prostředí vytvořit tok dat OpenTelemetry, přejděte do koncových bodů toku dat.

2. Na stránce koncových bodů toku dat identifikujte otevřenou telemetrii a vyberte + Nový.

   

3. V podokně Vytvořit nový koncový bod toku dat: Otevřená telemetrie, vyberte kartu Základní konfigurace a zadejte následující informace:

   • Název: Jedinečný název koncového bodu.
   • Hostitel: Koncový bod kolektoru OpenTelemetry ve formátu<host>:<port>, například otel-collector.monitoring.svc.cluster.local:4317.
   • Metoda ověřování: Zvolte jednu z následujících metod ověřování:
     • Token účtu služby Kubernetes: Používá tokeny účtu služby Kubernetes k ověření pomocí kolektoru OpenTelemetry. Zadejte hodnotu cílové skupiny pro konfiguraci kolektoru OpenTelemetry. Další podrobnosti najdete v tématu Token účtu služby (SAT ).
     • Anonymní: Používá se, když kolektor OpenTelemetry nevyžaduje ověřování.
     • Certifikát X509: Používá klientské certifikáty pro vzájemné ověřování TLS. Zadejte název tajného klíče Kubernetes obsahujícího váš klientský certifikát. Další podrobnosti najdete v certifikátu X.509 .

   

4. Vyberte kartu Upřesnit konfigurace a zadejte následující informace:

   • Latence dávkování (v sekundách):Maximální doba čekání před odesláním dávky. Výchozí hodnota je 5 sekund.
   • Počet zpráv: Maximální počet zpráv v dávce Výchozí hodnota je 1 00000 zpráv.
   • Režim TLS: Zvolte jeden z následujících režimů PROTOKOLU TLS:
     • Povoleno: Povolí protokol TLS pro zabezpečenou komunikaci s kolektorem OpenTelemetry. Zadejte název objektu ConfigMap Kubernetes obsahujícího certifikát důvěryhodné certifikační autority.
     • Zakázáno: Zakáže protokol TLS.
   • Název mapy konfigurace certifikátu důvěryhodné certifikační autority: Název objektu ConfigMap Kubernetes obsahujícího certifikát důvěryhodné certifikační autority.

   

5. Výběrem možnosti Použít vytvořte koncový bod OpenTelemetry.

Biceps

Vytvořte soubor Bicep .bicep s následujícím obsahem. Podle potřeby aktualizujte nastavení a nahraďte zástupné hodnoty, jako jsou <AIO_INSTANCE_NAME> vaše hodnoty.

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

Nasaďte soubor spuštěním následujícího příkazu Azure CLI:

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

Vytvořte soubor manifestu .yaml Kubernetes s následujícím obsahem:

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

Použijte soubor manifestu na cluster Kubernetes:

kubectl apply -f <FILE>.yaml

Možnosti konfigurace

Tato část popisuje možnosti konfigurace koncových bodů toku dat OpenTelemetry.

Host

Vlastnost host určuje adresu URL koncového bodu kolektoru OpenTelemetry. Uveďte protokol (http:// nebo https://) a číslo portu.

Examples:

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

Autentizace

Koncové body OpenTelemetry podporují několik metod ověřování pro zabezpečené připojení ke kolektorům.

Token účtu služby (SAT)

Ověřování pomocí tokenu účtu služby (SAT) používá tokeny účtu služby Kubernetes k autentizaci pomocí kolektoru OpenTelemetry.

Nahraďte <OTEL_AUDIENCE> hodnotou cílové skupiny pro konfiguraci kolektoru OpenTelemetry. Tato hodnota se musí shodovat s očekávanou cílovou skupinou v kolekci.

Zkušenosti z provozu

1. Ve podokně Vytvořit nový koncový bod toku dat: Open Telemetry, na záložce Základní konfigurace vyberte jako metodu ověření token účtu služby Kubernetes.

2. Zadejte hodnotu cílové skupiny služby pro konfiguraci kolektoru OpenTelemetry.

   

Důležité

Metodu ověřování můžete zvolit pouze při vytváření nového koncového bodu toku dat OpenTelemetry. Po vytvoření koncového bodu toku dat OpenTelemetry nemůžete změnit metodu ověřování. Pokud chcete změnit metodu ověřování existujícího toku dat, odstraňte původní tok dat a vytvořte nový s novou metodou ověřování.

Biceps

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

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

certifikát X.509

Ověřování certifikátu X.509 používá klientské certifikáty pro vzájemné ověřování TLS.

Zkušenosti z provozu

1. V podokně Vytvořit nový koncový bod toku dat: Otevřená telemetrie na záložce Základní konfigurace, vyberte jako metodu ověřování certifikát X509.

2. Zadejte následující informace ze služby Azure Key Vault:

   • Název synchronizovaného tajného kódu: Název tajného kódu Kubernetes obsahujícího váš klientský certifikát.
   • Klientský certifikát X509: Klientský certifikát.
   • Klientský klíč X509: Privátní klíč pro klientský certifikát.
   • Mezilehlé certifikáty X509: Mezilehlé certifikáty pro řetězec klientských certifikátů.

   

Biceps

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

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

Před použitím ověřování certifikátu X.509 vytvořte tajný klíč Kubernetes s klientským certifikátem:

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

Anonymní ověřování

Anonymní ověřování se používá, když kolektor OpenTelemetry nevyžaduje ověřování.

Zkušenosti z provozu

V podokně Vytvořit nový tok dat: Open Telemetry na kartě konfigurace Základní vyberte jako metodu ověřování Anonymní. Nevyžaduje se žádné další nastavení.

Biceps

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

authentication:
  method: Anonymous
  anonymousSettings: {}

Konfigurace protokolu TLS

Nakonfigurujte nastavení protokolu TLS (Transport Layer Security) pro zabezpečenou komunikaci s kolektorem OpenTelemetry.

Povolení protokolu TLS s důvěryhodnou certifikační autoritou

Zkušenosti z provozu

1. V podokně Vytvořit nový koncový bod toku dat: Telemetrie na záložce Upřesněná konfigurace vyberte jako režim TLS Povoleno.
2. V názvu mapy konfigurace certifikátu důvěryhodné certifikační autority zadejte název objektu ConfigMap Kubernetes obsahujícího certifikát důvěryhodné certifikační autority.

Biceps

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

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

Zakázání protokolu TLS

Zkušenosti z provozu

V podokně Vytvořit nový koncový bod toku dat: Open Telemetry, na kartě Pokročilá konfigurace, vyberte jako režim TLS Zakázáno.

Biceps

tls: {
  mode: 'Disabled'
}

tls:
  mode: Disabled

Batching

Nakonfigurujte nastavení dávkování pro optimalizaci výkonu seskupením více zpráv před odesláním do kolektoru.

Zkušenosti z provozu

V koncovém bodu Vytvořit nový tok dat: Otevřete podokno Telemetrie na kartě Pokročilá konfigurace a zadejte následující nastavení dávkování:

• Latence dávkování (v sekundách):Maximální doba čekání před odesláním dávky. Výchozí hodnota je 5 sekund.
• Počet zpráv: Maximální počet zpráv v dávce Výchozí hodnota je 1 00000 zpráv.

Biceps

batching: {
  latencySeconds: 5
  maxMessages: 100
}

Vlastnictví	Description	Výchozí
latencySeconds	Maximální doba čekání před odesláním dávky	60 sekund
maxMessages	Maximální počet zpráv v dávce	100000 zpráv

batching:
  latencySeconds: 5
  maxMessages: 100

Vlastnictví	Description	Výchozí
latencySeconds	Maximální doba čekání před odesláním dávky	60 sekund
maxMessages	Maximální počet zpráv v dávce	100000 zpráv

Zpracování chyb a řešení potíží

Ověření zprávy

Koncové body OpenTelemetry ověřují příchozí zprávy podle požadovaného schématu. Neplatné zprávy jsou odstraněny a potvrzeny, aby se zabránilo ztrátě zpráv v datovém toku.

Běžné chyby ověřování:

• Chybí požadovaná pole (name, typevalue pro metriky; value, level pro protokoly)
• Neplatné typy metrik nebo úrovně protokolů
• Nečíselné hodnoty v polích metrik value
• Chybné hodnoty časového razítka

Záruky doručení

Koncový bod OpenTelemetry poskytuje záruky doručení do samotného kolektoru, ale nikoli upstreamové služby, do které může kolektor předávat data. Jakmile data dorazí do kolektoru, operace Azure IoT nemají přehled o tom, jestli dosáhnou konečného cíle.

Související obsah

• Vytvoření toku dat
• Konfigurace koncových bodů toku dat
• Konfigurace koncových bodů toku dat MQTT