Ingerir dados do OpenTelemetry para o Azure Data Explorer

Artigo
10/13/2023

Importante

Este conector pode ser utilizado na Análise em Tempo Real no Microsoft Fabric. Utilize as instruções neste artigo com as seguintes exceções:

Se necessário, crie bases de dados com as instruções em Criar uma base de dados KQL.
Se necessário, crie tabelas com as instruções em Criar uma tabela vazia.
Obtenha URIs de consulta ou ingestão com as instruções em Copiar URI.
Execute consultas num conjunto de consultas KQL.

OpenTelemetry (OTel) é uma arquitetura aberta para a observabilidade da aplicação. A instrumentação é alojada pela Cloud Native Computing Foundation (CNCF), que fornece interfaces padrão para dados de observabilidade, incluindo métricas, registos e rastreios. O Recoletor OTel é composto pelos três componentes seguintes: os recetores lidam com a forma de obter dados para o Recoletor, os processadores determinam o que fazer com os dados recebidos e os exportadores são responsáveis por onde enviar os dados recebidos.

O exportador de Data Explorer do Azure suporta a ingestão de dados de muitos recetores para o Azure Data Explorer.

Nota

As definições de configuração são resumidas na documentação do readme.
Para obter o código fonte do exportador, veja Exportador de Data Explorer do Azure.

Neste artigo, vai aprender a:

Configurar o ambiente
Configurar o exportador de Data Explorer do Azure
Executar o exemplo de aplicação
Consultar dados recebidos

Pré-requisitos

Uma subscrição do Azure. Criar uma conta gratuita do Azure
Um cluster e uma base de dados: Início Rápido: Criar um cluster e uma base de dados do Azure Data Explorer

Configurar o ambiente

Nesta secção, vai preparar o seu ambiente para utilizar o exportador OTel.

Criar um registo de aplicações Microsoft Entra

Microsoft Entra autenticação de aplicações é utilizada para aplicações que precisam de aceder ao Azure Data Explorer sem um utilizador presente. Para ingerir dados com o exportador OTel, tem de criar e registar um principal de serviço Microsoft Entra e, em seguida, autorizar este principal a ingerir dados numa base de dados do Azure Data Explorer.

Com o cluster do Azure Data Explorer, siga os passos 1 a 7 em Criar um registo de aplicações Microsoft Entra no Azure Data Explorer.
Guarde os seguintes valores para serem utilizados em passos posteriores:
- ID da Aplicação (cliente)
- ID do Diretório (inquilino)
- Valor da chave de segredo do cliente

Conceder as permissões da aplicação Microsoft Entra

No separador consulta da IU da Web, ligue-se ao cluster. Para obter mais informações sobre como ligar, veja Adicionar clusters.
Navegue para a base de dados na qual pretende ingerir dados.
Execute o seguinte comando de gestão, substituindo os marcadores de posição. Substitua DatabaseName pelo nome da base de dados de destino e ApplicationID pelo valor guardado anteriormente. Este comando concede à aplicação a função de ingestor de bases de dados . Para obter mais informações, veja Gerir funções de segurança de bases de dados.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'
```
Nota

O último parâmetro é uma cadeia que aparece como notas quando consulta as funções associadas a uma base de dados. Para obter mais informações, veja Ver funções de segurança existentes.

Criar tabelas de destino

Navegue para a IU da Web do Azure Data Explorer.
Selecione Consulta no menu esquerdo.
Expanda o cluster de destino no painel esquerdo.
Selecione a base de dados de destino para dar às suas consultas o contexto correto.

Execute os seguintes comandos para criar tabelas e mapeamento de esquemas para os dados recebidos:

.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 a ingestão de transmissão em fluxo

O Azure Data Explorer tem dois tipos principais de ingestão: batching e transmissão em fluxo. Para obter mais informações, veja batching vs ingestão de transmissão em fluxo. O método de transmissão em fluxo é denominado gerido na configuração do exportador do Azure Data Explorer. A ingestão de transmissão em fluxo pode ser uma boa opção para si se precisar que os registos e os rastreios estejam disponíveis em tempo quase real. No entanto, a ingestão de transmissão em fluxo utiliza mais recursos do que a ingestão em lotes. A própria arquitetura OTel cria lotes de dados, que devem ser considerados ao escolher o método a utilizar para ingestão.

Nota

A ingestão de transmissão em fluxo tem de estar ativada no cluster Data Explorer do Azure para ativar a opçãomanaged. Pode verificar se a transmissão em fluxo está ativada com o comando de política de ingestão de transmissão em fluxo da base de dados .show .

Execute o seguinte comando para cada uma das três tabelas para ativar a ingestão de transmissão em fluxo:

.alter table <Table-Name> policy streamingingestion enable

Configurar o exportador de Data Explorer do Azure

Para ingerir os dados do OpenTelemetry no Azure Data Explorer, precisa de implementar e executar a distribuição OpenTelemetry com a seguinte configuração do exportador do Azure Data Explorer.

Configure o exportador de Data Explorer do Azure com os seguintes campos:

Campo	Descrição	Definição sugerida
Exportadores	Tipo de exportador	Azure Data Explorer
cluster_uri	URI do cluster de Data Explorer do Azure que contém a base de dados e as tabelas	<https:// cluster.kusto.windows.net>
application_id	ID de Cliente	<ID da aplicação>
application_key	Segredo do cliente	<chave da aplicação>
tenant_id	Inquilino	<inquilino da aplicação>
db_name	Base de dados que recebe os registos	oteldb ou outra base de dados que já criou
metrics_table_name	A tabela de destino na base de dados db_name que armazena dados de métricas exportados.	OTELMetrics
logs_table_name	A tabela de destino na base de dados db_name que armazena dados de registos exportados.	OTELLogs
traces_table_name	A tabela de destino na base de dados db_name que armazena dados de rastreios exportados.	OTELTraces
ingestion_type	Tipo de ingestão: gerida (transmissão em fluxo) ou em lote	gerido
metrics_table_json_mapping	Parâmetro opcional. O mapeamento de tabelas predefinido é definido durante a criação da tabela com base em atributos de métricas OTeL. O mapeamento predefinido pode ser alterado com este parâmetro.	<mapeamento de metrics_table_name json>
logs_table_json_mapping	Parâmetro opcional. O mapeamento de tabelas predefinido é definido durante a criação da tabela com base nos atributos de registos OTeL. O mapeamento predefinido pode ser alterado com este parâmetro.	<mapeamento de logs_table_name json>
traces_table_json_mapping	Parâmetro opcional. O mapeamento de tabelas predefinido é definido durante a criação da tabela com base nos atributos de rastreio OTeL. O mapeamento predefinido pode ser alterado com este parâmetro.	<mapeamento de traces_table_name json>
rastreios	Serviços: rastreios de componentes a ativar	recetores: [otlp] processadores: [batch] exportadores: [azuredataexplorer]
metrics	Serviços: componentes de métricas a ativar	recetores: [otlp] processadores: [batch] exportadores: [azuredataexplorer]
registos	Serviços: regista componentes a ativar	recetores: [otlp] processadores: [batch] exportadores: [ azuredataexplorer]

Utilize o sinalizador "--config" para executar o exportador do Azure Data Explorer.

Segue-se um exemplo de configuração para o exportador de Data Explorer do Azure:

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

Recolher dados com uma aplicação de exemplo

Agora que o recoletor está configurado, tem de enviar dados para serem ingeridos. Neste exemplo. utiliza a aplicação de clínica de animais de estimação spring de exemplo com o agente recoletor OTeL java.

Transfira o agente recoletor aqui: abra o agente do recoletor de telemetria.

Para ativar a telemetria aberta para a aplicação de exemplo, defina as seguintes variáveis de ambiente. O open-telemetry-collector-host referencia o anfitrião onde o exportador de Data Explorer do Azure está configurado e em execução.

Linha 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

Execute a aplicação spring-boot de exemplo com os seguintes argumentos da linha de comandos:

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

Consultar dados recebidos

Após a execução da aplicação de exemplo, os seus dados são ingeridos nas tabelas definidas no Azure Data Explorer. Estas tabelas foram criadas numa base de dados que foi definida na configuração do recoletor OTel, como oteldb. As tabelas que criou foram definidas na configuração do recoletor OTel. Neste exemplo, criou três tabelas: OTELMetrics, OTELLogs e OTELTraces. Nesta secção, vai consultar cada tabela separadamente para obter uma pequena seleção dos dados disponíveis.

Navegue para Azure Data Explorer IU da Web.
Selecione Consulta no menu esquerdo.
Expanda o cluster de destino no painel esquerdo.
Selecione a base de dados oteldb para dar às suas consultas o contexto correto.

Copie/cole as seguintes consultas sequencialmente para ver um número arbitrário de linhas de cada tabela:

Métricas

OTELMetrics
|take 2

Deverá obter resultados semelhantes, mas não exatamente iguais, à seguinte tabela:

CarimboDeDataEHora	MetricName	MetricType	MetricUnit	MetricDescription	MetricValue	Anfitrião	MetricAttributes	ResourceAttributes
07-2022-01T12:55:33Z	http.server.active_requests	Soma	pedidos	O número de pedidos HTTP simultâneos que estão atualmente em viagem	0	SFS7RUQ DE AMBIENTE DE TRABALHO	{"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"}
07-2022-01T12:55:33Z	http.server.duration_sum	Histograma	ms	A duração do pedido HTTP de entrada (soma total de exemplos)	114.9881	SFS7RUQ DE AMBIENTE DE TRABALHO	{"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"}

Registos

OTELLogs
|take 2

Deverá obter resultados semelhantes, mas não exatamente iguais, à seguinte tabela:

CarimboDeDataEHora	TraceId	SpanId	Texto de Gravidade	Número de Gravidade	Corpo	ResourceAttributes	LogsAttributes
07-2022-01T13:00:39Z			INFORMAÇÕES	9	Iniciar PetClinicApplication v2.7.0-SNAPSHOT com Java 18.0.1.1 no DESKTOP-SFS7RUQ com PID 37280 (C:\Users\adxuser\Documents\Repos\spring-petclinic\target\spring-petclinic-2.7.0-SNAPSHOT.jar iniciado pelo adxuser em 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"}
07-2022-01T13:00:39Z			INFORMAÇÕES	9	Sem conjunto de perfis ativos, recuando para 1 perfil predefinido: "predefinição"	{"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"}

Rastreios

OTELTraces
|take 2

Deverá obter resultados semelhantes, mas não exatamente iguais, à seguinte tabela:

TraceId	SpanId	ParentId	SpanName	SpanStatus	SpanKind	StartTime	EndTime	ResourceAttributes	TraceAttributes	Evento	Ligações
573c0e4e002a9f7281f6d63eafe4ef87	dab70d0ba8902c5e		87d003d6-02c1-4f3d-8972-683243c35642	STATUS_CODE_UNSET	SPAN_KIND_CLIENT	07-2022-01T13:17:59Z	07-2022-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", "thread.name":"main", "db.system":"h2", "thread.name 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	07-2022-01T13:17:59Z	07-2022-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"}	[]	[]

Processamento de dados adicional

Com as políticas de atualização, os dados recolhidos podem ser processados de acordo com as necessidades da aplicação. Para obter mais informações, veja Descrição geral da política de atualização.

O exemplo seguinte exporta as métricas do histograma para uma tabela com histo específico com registos e agregações. Execute o seguinte comando no painel de consulta da IU web do 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}]'

Os seguintes comandos criam uma tabela que contém apenas valores de contagem e soma do tipo de métrica Histograma e anexa uma política de atualização. Execute o seguinte comando no painel de consulta da IU web do 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

Partilhar via

Ingerir dados do OpenTelemetry para o Azure Data Explorer

Pré-requisitos

Configurar o ambiente

Criar um registo de aplicações Microsoft Entra

Conceder as permissões da aplicação Microsoft Entra

Criar tabelas de destino

Configurar a ingestão de transmissão em fluxo

Configurar o exportador de Data Explorer do Azure

Recolher dados com uma aplicação de exemplo

Consultar dados recebidos

Processamento de dados adicional

Comentários

Recursos adicionais

Partilhar via

Ingerir dados do OpenTelemetry para o Azure Data Explorer

Pré-requisitos

Configurar o ambiente

Criar um registo de aplicações Microsoft Entra

Conceder as permissões da aplicação Microsoft Entra

Criar tabelas de destino

Configurar a ingestão de transmissão em fluxo

Configurar o exportador de Data Explorer do Azure

Recolher dados com uma aplicação de exemplo

Consultar dados recebidos

Processamento de dados adicional

Conteúdo relacionado

Comentários

Recursos adicionais