Configurar o pontos de extremidade de fluxo de dados do OpenTelemetry (versão prévia)

Os pontos de extremidade do fluxo de dados do OpenTelemetry (OTEL) enviam métricas e registros para coletores do OpenTelemetry, que podem então encaminhar os dados para plataformas de observabilidade, como painéis do Grafana e Azure Monitor. Você pode definir as configurações de ponto de extremidade, autenticação, TLS (Transport Layer Security) e opções de envio em lote.

Este artigo descreve como criar e configurar um endpoint de fluxo de dados OpenTelemetry para exportar dados de ativos de seu agente MQTT para um coletor OpenTelemetry. O artigo descreve o ponto de extremidade de fluxo de dados OTEL, que roteia dados de ativos do corretor MQTT para coletores OTEL externos. Você também pode enviar dados de ativos para endpoints de observabilidade usando o endpoint de fluxo de dados do OpenTelemetry se quiser rotear a telemetria para plataformas como Grafana ou Azure Monitor.

Esse recurso destina-se ao roteamento de dados de dispositivos e ativos, não para coletar métricas ou logs de integridade de componentes do Operações do Azure IoT. Para obter a observação do cluster (monitoramento da integridade do broker MQTT, componentes de fluxo de dados e assim por diante), ver Configurar a observabilidade e o monitoramento.

Pré-requisitos

• Uma instância do Operações do Azure IoT.
• Um coletor OpenTelemetry implantado e acessível do cluster de Operações IoT do Azure.
• Acesso administrativo ao cluster de Operações IoT do Azure.

Terminologia

Visão geral do endpoint OpenTelemetry

Usando endpoints do OpenTelemetry, você pode exportar dados de telemetria de dispositivos e ativos dos fluxos de dados das operações Azure IoT para coletores do OpenTelemetry usando o Protocolo OpenTelemetry (OTLP). Usando esse recurso, você pode integrar a telemetria do dispositivo e do sistema à sua infraestrutura de observabilidade existente.

Em Operações do Azure IoT, o OpenTelemetry permite:

• Exportar telemetria de ativos como métricas OTEL: enviar leituras de sensores, dados de produção ou status de equipamentos para plataformas de observabilidade.
• Rotear dados sem modificar dispositivos: transforme mensagens MQTT no formato OTEL na camada de fluxo de dados.
• Colete e exporte dados de telemetria para sua plataforma de observabilidade preferencial.
• Integrar com pipelines de observabilidade existentes: enviar dados para qualquer back-end compatível com OTLP (Grafana, Prometheus, Azure Monitor e Datadog).

Os endpoints de fluxo de dados OTEL são de primeira classe no Operações do Azure IoT. Eles aparecem na lista de pontos de extremidade de fluxo de dados disponíveis no portal de experiência de Operações e podem ser selecionados ao configurar gráficos de fluxo de dados modernos. Essa abordagem torna simples rotear a telemetria para back-ends compatíveis com OTEL, mantendo uma experiência de configuração consistente.

Cenários comuns

A seguir estão alguns cenários comuns para o uso de pontos de extremidade do OpenTelemetry em Operações do Azure IoT:

• Diagnóstico do dispositivo: exportar temperatura, pressão e outras leituras do sensor como métricas para monitorar a integridade do dispositivo.
• Monitoramento de fábrica: enviar telemetria de linha de produção para painéis do Grafana para visibilidade operacional.
• Observabilidade do sistema: encaminhe logs de aplicativos e métricas para o Azure Monitor para monitoramento centralizado.
• Métricas personalizadas: adicione atributos contextuais, como ID de fábrica ou localização, às métricas para melhor filtragem e análise.

Requisitos de formato de dados

Os pontos de extremidade do OpenTelemetry exigem que os dados estejam em conformidade com um esquema JSON específico com uma matriz metrics, uma matriz logs ou ambos. O sistema descarta e reconhece mensagens que não estão em conformidade com esse esquema para evitar a perda de mensagens.

O conteúdo JSON deve usar essa estrutura de nível superior:

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

Você deve incluir pelo menos um metrics ou logs valor.

O sistema valida todas as mensagens de entrada no esquema necessário. Ele descarta e reconhece as mensagens que falham na validação de volta ao agente e registra os erros para solução de problemas. Falhas comuns de validação incluem campos obrigatórios ausentes, tipos de dados inválidos, tipos de métrica ou níveis de log sem suporte, e carimbos de data/hora malformados. Se as mensagens MQTT incluirem carimbos de data/hora de expiração, o sistema filtrará mensagens expiradas antes do processamento.

Formato de métricas

Cada objeto de métrica na metrics matriz deve ter os seguintes campos:

Campos necessários:

• name (string): o nome da métrica.
• type (cadeia de caracteres): o tipo de métrica (consulte os tipos de métrica com suporte).
• value (número): o valor numérico da métrica.

Campos opcionais:

• description (cadeia de caracteres): descrição legível por humanos da métrica.
• timestamp (número): carimbo de data/hora Unix em nanossegundos quando a métrica foi registrada.
• attributes (matriz): pares chave-valor para rotular e filtrar métricas.

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

Cada atributo na attributes matriz deve ter:

• key (cadeia de caracteres): o nome do atributo.
• value (cadeia de caracteres): o valor do atributo (deve ser uma cadeia de caracteres).

Formato de logs

Cada objeto de log na logs matriz deve conter os seguintes campos:

Campos necessários:

• value (cadeia de caracteres): conteúdo da mensagem de log.
• level (cadeia de caracteres): Nível de log (consulte os níveis de log com suporte).

Campos opcionais:

• timestamp (número): carimbo de data/hora de época do Unix em nanossegundos quando o log foi registrado.
• attributes (array): pares de chave-valor para contexto de logs e filtragem.

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

Cada atributo na attributes matriz deve ter:

• key (cadeia de caracteres): o nome do atributo.
• value (cadeia de caracteres): o valor do atributo (deve ser uma cadeia de caracteres).

Tipos de métrica com suporte

Há suporte para os seguintes tipos de métrica OpenTelemetry:

• Contadores: u64_counter, f64_counter – Valores monotonamente crescentes.
• Contadores para cima/para baixo: i64_up_down_counter, f64_up_down_counter - Valores que podem aumentar ou diminuir.
• Medidores: u64_gauge, i64_gauge, f64_gauge - Valores de pontos no tempo.
• Histogramas: f64_histogram, u64_histogram - Distribuição de valores.

Níveis de log com suporte

Há suporte para os seguintes níveis de log:

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

Criar o ponto de extremidade do OpenTelemetry

Você pode criar um ponto de extremidade para fluxo de dados do OpenTelemetry usando a interface de Operações IoT, Bicep ou Kubernetes.

O endpoint de fluxo de dados pode ser visto na lista dos endpoints de fluxo de dados disponíveis na experiência do Operações do Azure IoT. Essa adição garante que você possa facilmente identificar e selecionar o endpoint OpenTelemetry ao configurar pipelines de monitoramento, assim promovendo uma melhor integração e visibilidade entre as ferramentas de monitoramento. Ao acessar o ponto de extremidade OTEL juntamente com outras opções de fluxo de dados, você pode rotear dados de telemetria e manter padrões de observabilidade consistentes entre ativos com mais eficiência.

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

Opções de configuração

Esta seção descreve as opções de configuração para os endpoints de fluxo de dados do OpenTelemetry.

Host

Especifique a URL do ponto de extremidade do coletor OpenTelemetry na propriedade host. Inclua o protocolo (http:// ou https://) e o número da porta.

Exemplos:

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

Autenticação

Os pontos de extremidade do OpenTelemetry suportam vários métodos de autenticação para se conectar com segurança aos coletores.

Token de Conta de Serviço (SAT)

A autenticação SAT (Token de conta de serviço) usa tokens de conta de serviço do Kubernetes para autenticar-se com o coletor do OpenTelemetry.

Substitua <OTEL_AUDIENCE> pelo valor de audiência para a configuração do coletor OpenTelemetry. Este valor deve coincidir com o público esperado pelo coletor.

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

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

certificado X.509

A autenticação de certificado X.509 usa certificados de cliente para autenticação TLS mútua.

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

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

Antes de usar a autenticação de certificado X.509, crie um segredo do Kubernetes com o certificado do cliente:

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

Autenticação anônima

Use a autenticação anônima quando o coletor OpenTelemetry não exigir autenticação.

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

authentication:
  method: Anonymous
  anonymousSettings: {}

Configuração TLS

Defina as configurações de TLS (Transport Layer Security) para comunicação segura com o coletor OpenTelemetry.

TLS habilitado com AC confiável

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

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

TLS desativado

tls: {
  mode: 'Disabled'
}

tls:
  mode: Disabled

Envio em lote

Defina as configurações de envio em lote para otimizar o desempenho agrupando várias mensagens antes de enviá-las ao coletor.

batching: {
  latencySeconds: 5
  maxMessages: 100
}

batching:
  latencySeconds: 5
  maxMessages: 100

Usar pontos de extremidade OpenTelemetry em grafos de fluxo de dados

Selecione pontos de extremidade de fluxo de dados OTEL como destinos em grafos de fluxo de dados modernos. Usando esse recurso, você pode rotear métricas e logs diretamente para back-ends compatíveis com OTEL. Os pontos de extremidade OTEL não estão disponíveis como destinos em fluxos de dados clássicos. Essa restrição garante a compatibilidade com back-ends que não dão suporte aos endpoints OTEL.

Passo a passo: configurar um ponto de extremidade de fluxo de dados OTEL

Esta seção fornece um passo a passo para criar e configurar um ponto de extremidade de fluxo de dados OTEL no Operações do Azure IoT.

Etapa 1: Criação de um novo endpoint de fluxo de dados OTEL

Ao criar um novo ponto de extremidade de fluxo de dados, selecione OpenTelemetry (OTEL) como o tipo de ponto de extremidade. Verifique se o host está prefixado com http://.

Siga as etapas em Implantar recursos de observabilidade e configure logs.

Etapa 2: Criar um grafo de fluxo de dados usando o ponto de extremidade OTEL

Crie um fluxo de dados com o ativo como fonte. Verifique se a métrica que você deseja enviar ao OTEL é um ponto de dados no ativo. O exemplo a seguir usa um valor de temperatura. Selecione o grafo de fluxo de dados OTEL:

Etapa 3: Configure o ponto de extremidade OTEL como destino

Selecione o nó de origem e insira os detalhes. Neste exemplo, você seleciona a métrica de temperatura como o ponto de dados a ser enviado para o endpoint OTEL.

Selecione OTEL como o destino e insira os detalhes necessários.

Tratamento de erros e solução de problemas

Esta seção descreve informações sobre tratamento de erros e solução de problemas para pontos de extremidade do OpenTelemetry.

Validação de mensagem

Os pontos de extremidade do OpenTelemetry validam as mensagens de entrada de acordo com o esquema necessário. O sistema descarta mensagens inválidas e as reconhece para evitar a perda de mensagens no pipeline de fluxo de dados.

Os erros comuns de validação incluem:

• Campos necessários ausentes (namee typevalue para métricas; value e level para logs)
• Tipos de métrica inválidos ou níveis de log
• Valores não numéricos em campos de métrica value
• Valores de carimbo de data/hora malformados

Garantias de entrega

O ponto de extremidade do OpenTelemetry fornece garantias de entrega para o próprio coletor, mas não para os serviços de upstream para os quais o coletor pode redirecionar dados. Depois que os dados atingem o coletor, as Operações de IoT do Azure não têm visibilidade se chegam ao destino final.

Conteúdo relacionado

• Criar um fluxo de dados
• Configurar pontos de extremidade de fluxo de dados
• Configurar pontos de extremidade de fluxo de dados MQTT