Configuración de puntos de conexión de flujo de datos de OpenTelemetry (versión preliminar)

Importante

En esta página se incluyen instrucciones para administrar componentes de Azure IoT Operations mediante manifiestos de implementación de Kubernetes, que se encuentra en versión preliminar. Esta característica se proporciona con varias limitaciones y no debe usarse para cargas de trabajo de producción.

Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

Los puntos de conexión de flujo de datos de OpenTelemetry se utilizan para enviar métricas y registros a los recopiladores de OpenTelemetry, que luego pueden reenviar los datos a plataformas de observabilidad como los paneles de Grafana y Azure Monitor. Puede configurar la configuración del punto de conexión, la autenticación, la seguridad de la capa de transporte (TLS) y las opciones de procesamiento por lotes.

Prerrequisitos

• Una instancia de Azure IoT Operations
• Un recopilador de OpenTelemetry implementado y accesible desde el clúster de operaciones de Azure IoT

Visión general del punto de conexión de OpenTelemetry

Los puntos de conexión de OpenTelemetry permiten exportar datos de telemetría desde flujos de datos de operaciones de Azure IoT a los recopiladores de OpenTelemetry mediante el Protocolo OpenTelemetry (OTLP). Esto le permite integrar la telemetría del dispositivo y del sistema en la infraestructura de observabilidad existente.

Escenarios frecuentes

• Diagnósticos de dispositivos: exporte las lecturas de temperatura, presión y otros sensores como métricas para supervisar el estado del dispositivo.
• Supervisión de fábrica: envío de telemetría de línea de producción a paneles de Grafana para obtener visibilidad operativa
• Observabilidad del sistema: reenvíe los registros de aplicaciones y las métricas a Azure Monitor para la supervisión centralizada
• Métricas personalizadas: agregue atributos contextuales como el identificador de fábrica o la ubicación a las métricas para mejorar el filtrado y el análisis.

Requisitos de formato de datos

Los puntos de conexión de OpenTelemetry requieren que los datos se ajusten a un esquema JSON específico con una metrics matriz, una logs matriz o ambas. Los mensajes que no se ajustan a este esquema se descartan y se les reconoce para evitar la pérdida de mensajes.

La carga JSON debe usar esta estructura de nivel superior:

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

Al menos uno de metrics o logs debe estar presente.

Todos los mensajes entrantes se validan con el esquema necesario. Los mensajes que fallan en la validación se descartan, se confirma la recepción al intermediario y se registran en el sistema para solucionar problemas. Entre los errores de validación comunes se incluyen campos obligatorios que faltan, tipos de datos no válidos, tipos de métricas o niveles de registro no admitidos y marcas de tiempo con formato incorrecto. Si los mensajes MQTT incluyen marcas de tiempo de expiración, los mensajes expirados se filtran antes del procesamiento.

Formato de métricas

Cada objeto de métrica de la metrics matriz debe contener los campos siguientes:

Campos obligatorios:

• name (string): el nombre de la métrica
• type (string): el tipo de métrica (consulte los tipos de métrica admitidos)
• value (número): valor numérico de la métrica

Campos opcionales:

• description (cadena): descripción legible para humanos de la métrica
• timestamp (número): marca de tiempo de época de Unix en nanosegundos cuando se registró la métrica
• attributes (array): pares clave-valor para el etiquetado y el filtrado de 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 de la attributes matriz debe tener:

• key (string): el nombre del atributo
• value (string): el valor del atributo (debe ser una cadena)

Formato de registros

Cada objeto de registro de la logs matriz debe contener los siguientes campos:

Campos obligatorios:

• value (cadena): contenido del mensaje de registro
• level (cadena): nivel de registro (consulte los niveles de registro admitidos)

Campos opcionales:

• timestamp (número): marca de tiempo de época de Unix en nanosegundos cuando se generó el registro
• attributes (matriz): pares clave-valor para el contexto de registro y el filtrado

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

Cada atributo de la attributes matriz debe tener:

• key (string): el nombre del atributo
• value (string): el valor del atributo (debe ser una cadena)

Tipos de métricas admitidos

Se admiten los siguientes tipos de métricas de OpenTelemetry:

• Contadores: u64_counter, f64_counter : valores que aumentan monotonicamente
• Contadores arriba y abajo: i64_up_down_counter, f64_up_down_counter : valores que pueden aumentar o disminuir
• Medidores: u64_gauge, i64_gauge, f64_gauge - valores de un momento dado
• Histogramas: f64_histogram, u64_histogram - Distribución de valores

Niveles de registro admitidos

Se admiten los siguientes niveles de registro:

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

Creación de un punto de conexión de OpenTelemetry

Puede crear un punto de conexión de flujo de datos de OpenTelemetry mediante la experiencia de operaciones, Bicep o Kubernetes.

Experiencia de operaciones

1. Para crear un flujo de datos de OpenTelemetry en la experiencia de operaciones, vaya a los puntos de conexión de flujo de datos.

2. En la página de puntos de conexión de flujo de datos, identifique Open Telemetry y seleccione + Nuevo.

   

3. En el panel Crear nuevo punto de conexión de flujo de datos: Abra Telemetría , seleccione la pestaña Configuración básica y proporcione la siguiente información:

   • Nombre: un nombre único para el punto de conexión.
   • Host: el punto de conexión del recopilador OpenTelemetry con el formato<host>:<port> , por ejemplo, otel-collector.monitoring.svc.cluster.local:4317.
   • Método de autenticación: elija uno de los métodos de autenticación siguientes:
     • Token de cuenta de servicio de Kubernetes: usa tokens de cuenta de servicio de Kubernetes para autenticarse con el recopilador de OpenTelemetry. Proporcione el valor de audiencia para la configuración del recopilador de OpenTelemetry. Consulte Token de cuenta de servicio (SAT) para obtener más información.
     • Anónimo: se usa cuando el recopilador de OpenTelemetry no requiere autenticación.
     • Certificado X509: usa certificados de cliente para la autenticación TLS mutua. Proporcione el nombre de un secreto de Kubernetes que contenga el certificado de cliente. Consulte Certificado X.509 para obtener más información.

   

4. Seleccione la pestaña Configuración avanzada y proporcione la siguiente información:

   • Latencia de procesamiento por lotes (en segundos): tiempo máximo de espera antes de enviar un lote. El valor predeterminado es de 5 segundos.
   • Recuento de mensajes: número máximo de mensajes en un lote. El valor predeterminado es 100000 mensajes.
   • Modo TLS: elija uno de los siguientes modos TLS:
     • Habilitado: habilita TLS para la comunicación segura con el recopilador OpenTelemetry. Proporcione el nombre de un objeto ConfigMap de Kubernetes que contenga el certificado de CA de confianza.
     • Deshabilitado: deshabilita TLS.
   • Nombre del mapa de configuración del certificado de autoridad de certificación de confianza: el nombre de un ConfigMap de Kubernetes que contiene el certificado de autoridad de certificación de confianza.

   

5. Seleccione Aplicar para crear el punto de conexión de OpenTelemetry.

Bíceps

Cree un archivo .bicep de Bicep con el siguiente contenido. Actualice la configuración según sea necesario y reemplace los valores de marcador de posición como <AIO_INSTANCE_NAME> por sus valores.

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

Implemente el archivo mediante la ejecución del siguiente comando de la CLI de Azure:

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

Kubernetes

Cree un archivo de manifiesto .yaml de Kubernetes con el siguiente contenido:

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

Aplique el archivo de manifiesto al clúster de Kubernetes:

kubectl apply -f <FILE>.yaml

Opciones de configuración

En esta sección se describen las opciones de configuración de los puntos de conexión de flujo de datos de OpenTelemetry.

Anfitrión

La host propiedad especifica la dirección URL del punto de conexión del recopilador de OpenTelemetry. Incluya el protocolo (http:// o https://) y el número de puerto.

Ejemplos:

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

Autenticación

Los puntos de conexión de OpenTelemetry admiten varios métodos de autenticación para conectarse de forma segura a los recopiladores.

Token de cuenta de servicio (SAT)

La autenticación mediante token de cuentas de servicio (SAT) utiliza tokens de cuentas de servicio de Kubernetes para autenticarse con el recopilador de OpenTelemetry.

Reemplace por <OTEL_AUDIENCE> el valor de audiencia de la configuración del recopilador de OpenTelemetry. Este valor debe coincidir con la audiencia esperada en el recopilador.

Experiencia de operaciones

1. En el panel Crear nuevo punto de conexión de flujo de datos: Abra telemetría , en la pestaña Configuración básica , seleccione Token de cuenta de servicio de Kubernetes como método de autenticación.

2. Proporcione el valor de audiencia del servicio para la configuración del recopilador de OpenTelemetry.

   

Importante

Solo puedes elegir el método de autenticación al crear un nuevo punto de conexión de flujo de datos de OpenTelemetry. No se puede cambiar el método de autenticación después de crear el punto de conexión de flujo de datos OpenTelemetry. Si desea cambiar el método de autenticación de un flujo de datos existente, elimine el flujo de datos original y cree uno nuevo con el nuevo método de autenticación.

Bíceps

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

Kubernetes

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

Certificado X.509

La autenticación de certificados X.509 usa certificados de cliente para la autenticación TLS mutua.

Experiencia de operaciones

1. En el panel Crear nuevo punto de conexión de flujo de datos: Abra Telemetría , en la pestaña Configuración básica , seleccione Certificado X509 como método de autenticación.

2. Proporcione la siguiente información de Azure Key Vault:

   • Nombre del secreto sincronizado: el nombre de un secreto de Kubernetes que contiene el certificado de cliente.
   • Certificado de cliente X509: el certificado de cliente.
   • Clave de cliente X509: clave privada para el certificado de cliente.
   • Certificados intermedios X509: los certificados intermedios para la cadena de certificados de cliente.

   

Bíceps

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

Kubernetes

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

Antes de usar la autenticación de certificados X.509, cree un secreto de Kubernetes con el certificado de cliente:

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

Autenticación anónima

La autenticación anónima se usa cuando el recopilador de OpenTelemetry no requiere autenticación.

Experiencia de operaciones

En el panel Crear nuevo punto de conexión de flujo de datos: abra Telemetría , en la pestaña Configuración básica , seleccione Anónimo como método de autenticación. No se requiere ninguna configuración adicional.

Bíceps

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

Kubernetes

authentication:
  method: Anonymous
  anonymousSettings: {}

Configuración de TLS

Configure los valores de Seguridad de la capa de transporte (TLS) para una comunicación segura con el recopilador OpenTelemetry.

TLS habilitado con CA de confianza

Experiencia de operaciones

1. En el panel Crear nuevo punto de conexión de flujo de datos: abra Telemetría , en la pestaña Configuración avanzada , seleccione Habilitado como modo TLS.
2. En el Nombre del mapa de configuración del certificado de autoridad de certificación de confianza, proporcione el nombre de un ConfigMap de Kubernetes que contenga el certificado de autoridad de certificación de confianza.

Bíceps

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

Kubernetes

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

TLS deshabilitado

Experiencia de operaciones

En el panel Crear nuevo punto de conexión de flujo de datos: Abra Telemetría , en la pestaña Configuración avanzada , seleccione Deshabilitado como modo TLS.

Bíceps

tls: {
  mode: 'Disabled'
}

Kubernetes

tls:
  mode: Disabled

Procesamiento por lotes

Configure las opciones de procesamiento por lotes para optimizar el rendimiento mediante la agrupación de varios mensajes antes de enviarlos al recopilador.

Experiencia de operaciones

En el panel Crear un nuevo punto de conexión de flujo de datos: Abra telemetría , en la pestaña Configuración avanzada , proporcione las siguientes opciones de procesamiento por lotes:

• Latencia de procesamiento por lotes (en segundos): tiempo máximo de espera antes de enviar un lote. El valor predeterminado es de 5 segundos.
• Recuento de mensajes: número máximo de mensajes en un lote. El valor predeterminado es 100000 mensajes.

Bíceps

batching: {
  latencySeconds: 5
  maxMessages: 100
}

Propiedad	Descripción	Predeterminado
latencySeconds	Tiempo máximo de espera antes de enviar un lote.	60 segundos
maxMessages	Número máximo de mensajes en un lote.	100000 mensajes

Kubernetes

batching:
  latencySeconds: 5
  maxMessages: 100

Propiedad	Descripción	Predeterminado
latencySeconds	Tiempo máximo de espera antes de enviar un lote.	60 segundos
maxMessages	Número máximo de mensajes en un lote.	100000 mensajes

Control de errores y solución de problemas

Validación de mensajes

Los puntos de conexión de OpenTelemetry validan los mensajes entrantes en el esquema necesario. Los mensajes no válidos se descartan y se confirman para evitar la pérdida de mensajes en la canalización de flujo de datos.

Errores comunes de validación:

• Faltan campos obligatorios (name, type, value para métricas; value, level para registros)
• Tipos de métricas o niveles de registro no válidos
• Valores no numéricos en campos de métricas value
• Valores de marca de tiempo con formato incorrecto

Garantías de entrega

El punto de conexión de OpenTelemetry proporciona garantías de entrega al propio recopilador, pero no a los servicios ascendentes a los que el recopilador puede reenviar los datos. Una vez que los datos llegan al recopilador, Azure IoT Operations no tiene visibilidad sobre si llega al destino final.

Contenido relacionado

• Creación de un flujo de datos
• Configuración de puntos de conexión de flujo de datos
• Configuración de puntos de conexión de flujo de datos MQTT