Ingesta de datos de OpenTelemetry en Azure Data Explorer

  • Artículo

Importante

Este conector se puede usar en Análisis en tiempo real en Microsoft Fabric. Siga las instrucciones de este artículo con las siguientes excepciones:

OpenTelemetry (OTel) es un marco abierto que se utiliza para observar aplicaciones. La instrumentación la hospeda Cloud Native Computing Foundation (CNCF), que proporciona interfaces estándar para los datos de observabilidad, entre los que se incluyen métricas, registros y seguimientos. OTel Collector se compone de los tres componentes siguientes: los receptores tratan sobre cómo obtener datos en el recopilador, los procesadores determinan qué hacer con los datos recibidos y los exportadores son responsables de dónde enviar los datos recibidos.

El exportador de Azure Data Explorer admite la ingesta de datos de muchos receptores en Azure Data Explorer.

Nota

En este artículo aprenderá a:

  • Configurar el entorno
  • Configuración del exportador de Azure Data Explorer
  • Ejecutar la aplicación de ejemplo
  • Consulta de datos entrantes

Requisitos previos

Configurar el entorno

En esta sección, preparará el entorno para usar el exportador de OTel.

Creación de un registro de aplicación de Microsoft Entra

Microsoft Entra autenticación de aplicaciones se usa para las aplicaciones que necesitan acceder a Azure Data Explorer sin un usuario presente. Para ingerir datos mediante el exportador de OTel, debe crear y registrar una entidad de servicio de Microsoft Entra y, a continuación, autorizar a esta entidad a ingerir datos en una base de datos de Azure Data Explorer.

  1. Con el clúster de Azure Data Explorer, siga los pasos del 1 al 7 en Creación de un registro de aplicación de Microsoft Entra en Azure Data Explorer.
  2. Guarde los siguientes valores para usarlos en pasos posteriores:
    • Id. de aplicación (cliente)
    • Id. de directorio (inquilino)
    • Valor de clave secreta de cliente

Concesión de los permisos de la aplicación Microsoft Entra

  1. En la pestaña de consulta de la interfaz de usuario web, conéctese al clúster. Para más información sobre cómo conectarse, consulte Incorporación de clústeres.

  2. Vaya a la base de datos en la que desea ingerir datos.

  3. Ejecute el siguiente comando de administración y reemplace los marcadores de posición. Reemplace DatabaseName por el nombre de la base de datos de destino y ApplicationID por el valor guardado anteriormente. Este comando concede a la aplicación el rol de ingeror de base de datos . Para más información, consulte Administración de roles de seguridad de base de datos.

    .add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'

    Nota

    El último parámetro es una cadena que se muestra como una nota al consultar los roles asociados a una base de datos. Para más información, consulte Visualización de roles de seguridad existentes.

Creación de tablas de destino

  1. Vaya a la interfaz de usuario web de Azure Data Explorer.

  2. Seleccione Consulta en el menú de la izquierda.

  3. Expanda el clúster de destino en el panel izquierdo.

  4. Seleccione la base de datos de destino para proporcionar a las consultas el contexto correcto.

  5. Ejecute los comandos siguientes para crear tablas y asignación de esquemas para los datos entrantes:

    .create-merge table <Logs-Table-Name> (Timestamp:datetime, ObservedTimestamp:datetime, TraceID:string, SpanID:string, SeverityText:string, SeverityNumber:int, Body:string, ResourceAttributes:dynamic, LogsAttributes:dynamic) 

.create-merge table <Metrics-Table-Name> (Timestamp:datetime, MetricName:string, MetricType:string, MetricUnit:string, MetricDescription:string, MetricValue:real, Host:string, ResourceAttributes:dynamic,MetricAttributes:dynamic) 

.create-merge table <Traces-Table-Name> (TraceID:string, SpanID:string, ParentID:string, SpanName:string, SpanStatus:string, SpanKind:string, StartTime:datetime, EndTime:datetime, ResourceAttributes:dynamic, TraceAttributes:dynamic, Events:dynamic, Links:dynamic)

Configuración de la ingesta de streaming

Azure Data Explorer tiene dos tipos principales de ingesta: procesamiento por lotes y streaming. Para más información, consulte el apartado en el que se comparan la ingesta mediante procesamiento por lotes y la ingesta mediante streaming. El método de streaming se denomina administrado en la configuración del exportador de Azure Data Explorer. La ingesta mediante streaming puede ser una buena opción si necesita que los registros y seguimientos estén disponibles casi en tiempo real. Sin embargo, la ingesta mediante streaming usa más recursos que la ingesta por lotes. El propio marco OTel realiza lotes de datos, que se deben tener en cuenta al elegir qué método usar para la ingesta.

Nota

La ingesta mediante streaming debe estar habilitada en el clúster de Azure Data Explorer para poder habilitar la opción managed. Para comprobar si el streaming está habilitado, utilice el comando .show database streaming ingestion policy.

Para habilitar la ingesta mediante streaming en las tres tablas, ejecute el siguiente comando:

.alter table <Table-Name> policy streamingingestion enable

Configuración del exportador de Azure Data Explorer

Para ingerir los datos de OpenTelemetry en Azure Data Explorer, es preciso implementar y ejecutar la distribución de OpenTelemetry con la siguiente configuración del exportador de Azure Data Explorer.

  1. Configure el exportador de Azure Data Explorer mediante los siguientes campos:

    Campo Descripción Configuración sugerida
    Exportadores Tipo de exportador Explorador de datos de Azure
    cluster_uri URI del clúster de Azure Data Explorer que contiene la base de datos y las tablas https:// <cluster>.kusto.windows.net
    application_id Id. de cliente <id. de aplicación>
    application_key Secreto del cliente <clave de aplicación>
    tenant_id Inquilino <inquilino de aplicación>
    db_name Base de datos que recibe los registros oteldb, o cualquier otra base de datos que ya ha creado
    metrics_table_name La tabla de destino de la base de datos db_name que almacena los datos de métricas exportados. OTELMetrics
    logs_table_name La tabla de destino de la base de datos db_name que almacena los datos de registros exportados. OTELLogs
    traces_table_name La tabla de destino de la base de datos db_name que almacena los datos de seguimientos exportados. OTELTraces
    ingestion_type Tipo de ingesta: administrada (streaming) o por lotes administrado
    metrics_table_json_mapping Parámetro opcional. La asignación de tabla predeterminada se define durante la creación de tablas en función de los atributos de métricas de OTeL. La asignación predeterminada se puede cambiar mediante este parámetro. <json metrics_table_name mapping>
    logs_table_json_mapping Parámetro opcional. La asignación de tabla predeterminada se define durante la creación de tablas en función de los atributos de registros de OTeL. La asignación predeterminada se puede cambiar mediante este parámetro. <json logs_table_name mapping>
    traces_table_json_mapping Parámetro opcional. La asignación de tabla predeterminada se define durante la creación de tablas en función de los atributos de seguimiento de OTeL. La asignación predeterminada se puede cambiar mediante este parámetro. <json traces_table_name mapping>
    traces Servicios: componentes de seguimiento que se habilitan receptores: [otlp]
    procesadores: [batch]
    exportadores: [azuredataexplorer]
    metrics Servicios: componentes de métricas que se habilitan receptores: [otlp]
    procesadores: [batch]
    exportadores: [azuredataexplorer]
    logs Servicios: componentes de registros que se habilitan receptores: [otlp]
    procesadores: [batch]
    exportadores: [azuredataexplorer]

  2. Use la marca "--config" para ejecutar el exportador de Azure Data Explorer.

A continuación se muestra una configuración de ejemplo para el exportador de Azure Data Explorer:

---
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
processors:
  batch:
exporters:
  azuredataexplorer:
    cluster_uri: "https://<cluster>.kusto.windows.net"
    application_id: "<application id>"
    application_key: "<application key>"
    tenant_id: "<application tenant>"
    db_name: "oteldb"
    metrics_table_name: "OTELMetrics"
    logs_table_name: "OTELLogs"
    traces_table_name: "OTELTraces"
    ingestion_type : "managed"
    metrics_table_json_mapping : "<json metrics_table_name mapping>"
    logs_table_json_mapping  : "<json logs_table_name mapping>"
    traces_table_json_mapping  : "<json traces_table_name mapping>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]

Recopilación de datos con una aplicación de ejemplo

Ahora que el recopilador está configurado, es preciso enviar los datos que se van a ingerir. En este ejemplo, se usa la aplicación de clínica de spring pet de ejemplo con el agente del recopilador de OTeL de Java.

  1. Descargue el agente del recopilador aquí: abrir el agente del recopilador de datos de telemetría.

  2. Para habilitar la telemetría abierta para la aplicación de ejemplo, establezca las siguientes variables de entorno. Open-telemetry-collector-host hace referencia al host donde está configurado y en ejecución el exportador de Azure Data Explorer.

    $env:OTEL_SERVICE_NAME="pet-clinic-service"
$env:OTEL_TRACES_EXPORTER="otlp"
$env:OTEL_LOGS_EXPORTER="otlp "                   
$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://<open-telemetry-collector-host>:4317"

  3. Ejecute la aplicación spring-boot de ejemplo con los siguientes argumentos de la línea de comandos:

    java -javaagent:./opentelemetry-javaagent.jar -jar spring-petclinic-<version>-SNAPSHOT.jar

Consulta de datos entrantes

Una vez ejecutada la aplicación de ejemplo, los datos se han ingerido en las tablas definidas en Azure Data Explorer. Estas tablas se crearon en una base de datos definida en la configuración del recopilador OTel, como oteldb. Las tablas que ha creado se definieron en la configuración del recopilador OTel. En este ejemplo, ha creado tres tablas: OTELMetrics, OTELLogs y OTELTraces. En esta sección, se consulta cada tabla por separado para obtener una pequeña selección de los datos disponibles.

  1. Vaya a la interfaz de usuario web de Azure Data Explorer.

  2. Seleccione Consulta en el menú de la izquierda.

  3. Expanda el clúster de destino en el panel izquierdo.

  4. Seleccione la base de datos oteldb para proporcionar a las consultas el contexto correcto.

  5. Copie o pegue las siguientes consultas secuencialmente para ver un número arbitrario de filas de cada tabla:

    • Métricas

      OTELMetrics
|take 2

      Debe obtener resultados similares, pero no exactamente iguales, que la tabla siguiente:

      Timestamp MetricName MetricType MetricUnit MetricDescription MetricValue Host MetricAttributes ResourceAttributes
      2022-07-01T12:55:33Z http.server.active_requests Sum Solicitudes Número de solicitudes HTTP simultáneas actualmente en proceso 0 DESKTOP-SFS7RUQ {"http.flavor":"1.1", "http.host":"localhost:8080", "scope.name":"io.opentelemetry.tomcat-7.0", "scope.version":"1.14.0-alpha", "http.method":"GET", "http.scheme":"http"} {"host.name":"DESKTOP-SFS7RUQ", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "host.arch":"amd64", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.auto.version":"1.14.0", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":5980, "service.name":"my-service", "telemetry.sdk.version":"1.14.0"}
      2022-07-01T12:55:33Z http.server.duration_sum Histograma ms Duración de la solicitud HTTP entrante (suma total de ejemplos) 114.9881 DESKTOP-SFS7RUQ {"http.flavor":"1.1", "http.host":"localhost:8080", "scope.name":"io.opentelemetry.tomcat-7.0", "scope.version":"1.14.0-alpha", "http.method":"GET", "http.scheme":"http", "http.route":"/owners/find", "http.status_code":200} {"host.name":"DESKTOP-SFS7RUQ", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "host.arch":"amd64", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.auto.version":"1.14.0", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":5980, "service.name":"my-service", "telemetry.sdk.version":"1.14.0"}

    • Registros

      OTELLogs
|take 2

      Debe obtener resultados similares, pero no exactamente iguales, que la tabla siguiente:

      Timestamp TraceId SpanId SeverityText SeverityNumber Body ResourceAttributes LogsAttributes
      2022-07-01T13:00:39Z INFO 9 Inicio de PetClinicApplication v2.7.0-SNAPSHOT mediante Java 18.0.1.1 en DESKTOP-SFS7RUQ con PID 37280 (C:\Users\adxuser\Documents\Repos\spring-petclinic\target\spring-petclinic-2.7.0-SNAPSHOT.jar started by adxuser in C:\Users\adxuser\Documents\Repos\spring-petclinic) {"host.name":"DESKTOP-SFS7RUQ", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":37280, "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "telemetry.sdk.version":"1.14.0", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "os.description":"Windows 11 10.0", "service.name":"my-service", "telemetry.auto.version":"1.14.0", "host.arch":"amd64"} {"scope.name":"org.springframework.samples.petclinic.PetClinicApplication"}
      2022-07-01T13:00:39Z INFO 9 No hay ningún perfil activo establecido, se vuelve a un perfil predeterminado: "default" {"host.name":"DESKTOP-SFS7RUQ", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":37280, "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "telemetry.sdk.version":"1.14.0", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "os.description":"Windows 11 10.0", "service.name":"my-service", "telemetry.auto.version":"1.14.0", "host.arch":"amd64"} {"scope.name":"org.springframework.samples.petclinic.PetClinicApplication"}

    • Traces

      OTELTraces
|take 2

      Debe obtener resultados similares, pero no exactamente iguales, que la tabla siguiente:

      TraceId SpanId ParentId SpanName SpanStatus SpanKind StartTime EndTime ResourceAttributes TraceAttributes Eventos Vínculos
      573c0e4e002a9f7281f6d63eafe4ef87 dab70d0ba8902c5e 87d003d6-02c1-4f3d-8972-683243c35642 STATUS_CODE_UNSET SPAN_KIND_CLIENT 2022-07-01T13:17:59Z 2022-07-01T13:17:59Z {"telemetry.auto.version":"1.14.0", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "service.name":"my-service", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.language":"java", "telemetry.sdk.name":"opentelemetry", "host.arch":"amd64", "host.name":"DESKTOP-SFS7RUQ", "process.pid":34316, "process.runtime.version":"18.0.1.1+2-6", "os.type":"windows", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "telemetry.sdk.version":"1.14.0"} {"db.user":"sa", "thread.id":1, "db.name":"87d003d6-02c1-4f3d-8972-683243c35642", "thread.name":"main", "db.system":"h2", "scope.name":"io.opentelemetry.jdbc", "scope.version":"1.14.0-alpha", "db.connection_string":"h2:mem:", "db.statement":"DROP TABLE vet_specialties IF EXISTS"} [] []
      84a9a8c4009d91476da02dfa40746c13 3cd4c0e91717969a 87d003d6-02c1-4f3d-8972-683243c35642 STATUS_CODE_UNSET SPAN_KIND_CLIENT 2022-07-01T13:17:59Z 2022-07-01T13:17:59Z {"telemetry.auto.version":"1.14.0", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "service.name":"my-service", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.language":"java", "telemetry.sdk.name":"opentelemetry", "host.arch":"amd64", "host.name":"DESKTOP-SFS7RUQ", "process.pid":34316, "process.runtime.version":"18.0.1.1+2-6", "os.type":"windows", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "telemetry.sdk.version":"1.14.0"} {"db.user":"sa", "thread.id":1, "db.name":"87d003d6-02c1-4f3d-8972-683243c35642", "thread.name":"main", "db.system":"h2", "scope.name":"io.opentelemetry.jdbc", "scope.version":"1.14.0-alpha", "db.connection_string":"h2:mem:", "db.statement":"DROP TABLE vets IF EXISTS"} [] []

Procesamiento de datos adicional

Los datos recopilados se pueden procesar más si la aplicación lo necesita. Para ello, se deben usar directivas de actualización. Para más información, consulte Introducción a las directivas de actualización.

  1. En el ejemplo siguiente las métricas de un histograma se exporta a una tabla específica de histogramas con cubos y agregados. Ejecute el siguiente comando en el panel de consulta de la interfaz de usuario web de Azure Data Explorer:

    .create table HistoBucketData (Timestamp: datetime, MetricName: string , MetricType: string , Value: double, LE: double, Host: string , ResourceAttributes: dynamic, MetricAttributes: dynamic )

.create function 
with ( docstring = "Histo bucket processing function", folder = "UpdatePolicyFunctions") ExtractHistoColumns()
{
    OTELMetrics
    | where MetricType == 'Histogram' and MetricName has "_bucket"
    | extend f=parse_json(MetricAttributes)
    | extend le=todouble(f.le)
    | extend M_name=replace_string(MetricName, '_bucket','')
    | project Timestamp, MetricName=M_name, MetricType, MetricValue, LE=le, Host, ResourceAttributes, MetricAttributes
}

.alter table HistoBucketData policy update 
@'[{ "IsEnabled": true, "Source": "OTELMetrics","Query": "ExtractHistoColumns()", "IsTransactional": false, "PropagateIngestionProperties": false}]'

  2. Los siguientes comandos crean una tabla que solo contiene los valores count y sum del tipo de métrica Histograma y adjunta una directiva de actualización. Ejecute el siguiente comando en el panel de consulta de la interfaz de usuario web de Azure Data Explorer:

     .create table HistoData (Timestamp: datetime, MetricName: string , MetricType: string , Count: double, Sum: double, Host: string , ResourceAttributes: dynamic, MetricAttributes: dynamic)

 .create function 
with ( docstring = "Histo sum count processing function", folder = "UpdatePolicyFunctions") ExtractHistoCountColumns()
{
   OTELMetrics
    | where MetricType =='Histogram'
    | where MetricName has "_count"
    | extend Count=MetricValue
    | extend M_name=replace_string(MetricName, '_bucket','')
    | join kind=inner (OTELMetrics
    | where MetricType =='Histogram'
    | where MetricName has "_sum"
    | project Sum = MetricValue , Timestamp)
 on Timestamp | project Timestamp, MetricName=M_name, MetricType, Count, Sum, Host, ResourceAttributes, MetricAttributes
}

.alter table HistoData policy update 
@'[{ "IsEnabled": true, "Source": "RawMetricsData","Query": "ExtractHistoCountColumns()", "IsTransactional": false, "PropagateInge

Contenido relacionado