Ingesta de datos de OpenTelemetry en Azure Data Explorer

OpenTelemetry (OTel) es un marco abierto que se utiliza para observar aplicaciones. La instrumentación se hospeda en Cloud Native Computing Foundation (CNCF). Proporciona interfaces estándar para los datos de observabilidad, incluidas las métricas, los registros y los seguimientos. El recopilador de OTel incluye tres componentes: receptores, que obtienen datos en el recopilador; procesadores, que determinan qué hacer con los datos recibidos; y exportadores, que envían los datos recibidos a un destino.

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

En este artículo aprenderá a:

Requisitos previos

• Suscripción a Azure. Cree una cuenta de Azure gratuita.
• Un clúster y una base de datos. Aprenda a crear un clúster y una base de datos de Azure Data Explorer.

Configurar el entorno

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

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

La autenticación de aplicaciones de Microsoft Entra permite a las aplicaciones acceder a Azure Data Explorer sin un usuario presente. Para ingerir datos mediante el exportador de OTel, cree y registre un principal de servicio de Microsoft Entra y autorice a este principal de servicio a ingerir datos en una base de datos de Azure Data Explorer.

1. En el clúster de Azure Data Explorer, siga los pasos del 1 al 7 en Creación de un registro de aplicaciones de Microsoft Entra en Azure Data Explorer.
2. Guarde los siguientes valores para los pasos posteriores:

Conceder permisos a la aplicación Microsoft Entra

1. En la pestaña consulta de la interfaz de usuario web, conéctese al clúster. Para obtener 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.

   .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 obtener 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 dar contexto correcto a las consultas.

5. Ejecute los siguientes comandos para crear tablas y la 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) 
   

Configurar 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 llama administrado en la configuración del exportador de Azure Data Explorer. La ingesta de streaming puede ser una buena opción si necesita registros y seguimientos disponibles casi en tiempo real. Sin embargo, la ingesta mediante streaming usa más recursos que la ingesta por lotes. El marco de OTel agrupa por lotes los datos, que debe tener en cuenta al elegir un método de ingesta.

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	Azure Data Explorer
   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 haya 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	managed
   metrics_table_json_mapping	Parámetro opcional. La asignación de tablas predeterminada se define al crear las tablas con OTeL atributos de métricas. La asignación predeterminada se puede cambiar mediante este parámetro.	<mapeo de json metrics_table_name>
   logs_table_json_mapping	Parámetro opcional. La asignación de tablas predeterminada se define al crear las tablas con OTeL atributos de registros. La asignación predeterminada se puede cambiar mediante este parámetro.	<mapeo de logs_table_name json>
   traces_table_json_mapping	Parámetro opcional. La asignación de tablas predeterminada se define al crear las tablas con OTeL atributos de seguimiento. La asignación predeterminada se puede cambiar mediante este parámetro.	<mapeo de json traces_table_name>
   traces	Servicios: componentes de seguimiento que se habilitan	receptores: [otlp] procesadores: [batch] exporters: [azuredataexplorer]
   Métricas	Servicios: componentes de métricas que se habilitan	receptores: [otlp] procesadores: [batch] exporters: [azuredataexplorer]
   logs	Servicios: componentes de registros que se habilitan	receptores: [otlp] procesadores: [batch] exporters: [ azuredataexplorer]

2. Para ejecutar el exportador de Azure Data Explorer, use la marca "--config".

Esta es 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, Use la aplicación de ejemplo spring pet clinic con el agente recopilador OTeL de Java.

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

2. Para habilitar la apertura de la telemetría en la aplicación de ejemplo, establezca las siguientes variables de entorno. open-telemetry-collector-host hace referencia al host en el que el exportador de Azure Data Explorer está configurado y se ejecuta.

   • Línea de comandos
   • Bash

   $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 crean en una base de datos definida en la configuración del recopilador de OTel, como oteldb. Las tablas que creó se definen en la configuración del recopilador de OTel. En este ejemplo, ha creado tres tablas: OTELMetrics, OTELLogs y OTELTraces. En esta sección, 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
     

     Debería obtener resultados similares, aunque no exactamente iguales, a los de la tabla siguiente:

     Marca de tiempo	MetricName	MetricType	MetricUnit	MetricDescription	MetricValue	Host	MetricAttributes	ResourceAttributes
     2022-07-01T12:55:33Z	http.server.active_requests	Sum	requests	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
     

     Debería obtener resultados similares, aunque no exactamente iguales, a los de la tabla siguiente:

     Marca de tiempo	TraceId	SpanId	SeverityText	SeverityNumber	Cuerpo	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.ejecutable.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
     

     Debería obtener resultados similares, aunque no exactamente iguales, a los de 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.ejecutable.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":"ELIMINAR TABLA vets SI EXISTE"}	[]	[]

Procesamiento de datos adicional

Use directivas de actualización para procesar aún más los datos recopilados según las necesidades de la aplicació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

• Referencia rápida de KQL
• Información general del Lenguaje de consulta de Kusto (KQL)