Ingesta de datos de OpenTelemetry en Azure Data Explorer

Artículo
06/25/2024

Importante

Este conector se puede usar en Inteligencia en tiempo real en Microsoft Fabric. Use las instrucciones de este artículo con las siguientes excepciones:

Si es necesario, cree una bases de datos con las instrucciones de Crear una base de datos KQL.
Si es necesario, cree tablas con las instrucciones de Crear una tabla vacía.
Obtenga los URI de consulta o ingesta mediante las instrucciones de Copiar URI.
Ejecute consultas en un Conjunto de consultas KQL.

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. El colector OTel está formado por los tres componentes siguientes: los receptores se ocupan de cómo introducir los datos en el colector, 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:

Los valores de configuración se resumen en la documentación de Léame.
Para el código fuente del exportador, consulte Exportador de Azure Data Explorer.

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

Suscripción a Azure. Creación de una cuenta de Azure gratuita
Un clúster y una base de datos: Inicio rápido: Creación de un clúster y de la 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 se usa para las aplicaciones que necesitan acceder a Azure Data Explorer sin que haya 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.

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.
Guarde los siguientes valores para usarlos en pasos posteriores:
- Id. de la aplicación (cliente)
- Id. de directorio (inquilino)
- Valor de clave del secreto de cliente

Conceder permisos a la aplicación Microsoft Entra

En la pestaña consulta de la interfaz de usuario web, conéctese al clúster. Para obtener más información sobre cómo conectarse, consulte Agregar clústeres.
Vaya a la base de datos en la que desea ingerir datos.
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 agente de ingesta de bases de datos. Para más información, consulte Administrar 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 obtener más información, consulte Visualización de roles de seguridad existentes.

Creación de tablas de destino

Vaya a la interfaz de usuario web de Azure Data Explorer.
Seleccione Consulta en el menú de la izquierda.
Expanda el clúster de destino en el panel izquierdo.
Seleccione la base de datos de destino para proporcionar a las consultas el contexto correcto.

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 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 de OTeL realiza un procesamiento por lotes de los datos, lo que se deben tener en cuenta al elegir el método que se va a 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.

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 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	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.	<json metrics_table_name mapping>
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.	<json logs_table_name mapping>
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.	<json traces_table_name mapping>
traces	Servicios: componentes de seguimiento que se habilitan	receptores: [otlp] procesadores: [batch] exportadores: [azuredataexplorer]
Métricas	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]

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

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

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"

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

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, consulta cada tabla por separado para obtener una pequeña selección de los datos disponibles.

Vaya a la interfaz de usuario web de Azure Data Explorer.
Seleccione Consulta en el menú de la izquierda.
Expanda el clúster de destino en el panel izquierdo.
Seleccione la base de datos oteldb para proporcionar a las consultas el contexto correcto.

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

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

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

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

Compartir a través de

Ingesta de datos de OpenTelemetry en Azure Data Explorer

Requisitos previos

Configurar el entorno

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

Conceder permisos a la aplicación Microsoft Entra

Creación de tablas de destino

Configurar ingesta de streaming

Configuración del exportador de Azure Data Explorer

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

Consulta de datos entrantes

Procesamiento de datos adicional

Comentarios

Recursos adicionales

Compartir a través de

Ingesta de datos de OpenTelemetry en Azure Data Explorer

Requisitos previos

Configurar el entorno

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

Conceder permisos a la aplicación Microsoft Entra

Creación de tablas de destino

Configurar ingesta de streaming

Configuración del exportador de Azure Data Explorer

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

Consulta de datos entrantes

Procesamiento de datos adicional

Contenido relacionado

Comentarios

Recursos adicionales