Ingerir dados do OpenTelemetry no Azure Data Explorer

Artigo
07/24/2024

Importante

Esse conector pode ser usado na Inteligência em Tempo Real no Microsoft Fabric. Use as instruções incluídas neste artigo com as seguintes exceções:

Se necessário, crie bancos de dados usando as instruções em Criar um banco de dados KQL.
Se necessário, crie tabelas usando as instruções em Criar uma tabela vazia.
Obtenha URIs de consulta ou ingestão usando as instruções em Copiar URI.
Execute consultas em um KQL queryset.

O OpenTelemetry (OTel) é uma estrutura aberta para a observabilidade do aplicativo. A instrumentação é hospedada pela CNCF (Cloud Native Computing Foundation), que oferece interfaces padronizadas para dados de observabilidade, incluindo métricas, logs e rastreamentos. O Coletor OTel é composto pelos três componentes a seguir: os receptores lidam com a forma de obtenção de dados no Coletor, os processadores determinam o que fazer com os dados recebidos e os exportadores são responsáveis por para onde enviar os dados recebidos.

O exportador do Azure Data Explorer dá suporte à ingestão de dados de vários destinatários no Azure Data Explorer.

Observação

As definições da configurações estão resumidas na documentação Leiame.
Para o código-fonte do exportador, confira o exportador do Azure Data Explorer.

Neste artigo, você aprenderá como:

Configure seu ambiente
Configurar o exportador do Azure Data Explorer
Executar o aplicativo de exemplo
Consultar dados de entrada

Pré-requisitos

Uma assinatura do Azure. Criar uma conta gratuita do Azure
Um cluster e um banco de dados: Início Rápido: Criar um cluster e um banco de dados do Azure Data Explorer

Configure seu ambiente

Nesta seção, você prepara seu ambiente para usar o exportador OTel.

Criar um registro de aplicativo do Microsoft Entra

A autenticação do aplicativo do Microsoft Entra é usada para aplicativos que precisam acessar o Azure Data Explorer sem um usuário presente. Para ingerir dados usando o exportador OTel, você precisa criar e registrar uma entidade de serviço do Microsoft Entra e autorizar essa entidade a ingerir dados em um banco de dados do Azure Data Explorer.

Usando o cluster do Azure Data Explorer, siga as etapas 1 a 7 em Criar um registro de aplicativo do Microsoft Entra no Azure Data Explorer.
Salve os seguintes valores a serem usados em etapas posteriores:
- ID do Aplicativo (cliente)
- ID do Diretório (locatário)
- Valor da chave secreta do cliente

Conceder permissões ao aplicativo do Microsoft Entra

Na guia de consulta da interface do usuário da Web, conecte-se ao cluster. Para obter mais informações sobre como se conectar, confira Adicionar clusters.
Navegue até o banco de dados no qual você deseja ingerir dados.
Execute o comando de gerenciamento a seguir, substituindo os espaços reservados. Substitua DatabaseName pelo nome do banco de dados de destino e ApplicationID pelo valor salvo anteriormente. Esse comando concede ao aplicativo a função de ingestor de banco de dados. Para obter mais informações, consulte Gerenciar unções de segurança de banco de dados.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'
```
Observação

O último parâmetro é uma cadeia de caracteres que aparece como observações quando você consulta as funções associadas a um banco de dados. Para obter mais informações, consulte Exibir funções de segurança existentes.

Criar tabelas de destino

Navegue até a interface do usuário da Web do Azure Data Explorer.
Selecione Consultar no menu à esquerda.
Expanda o cluster de destino no painel à esquerda.
Selecione o banco de dados de destino para dar o contexto correto às consultas.

Execute os seguintes comandos para criar tabelas e um mapeamento de esquema para os dados de entrada:

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

O Azure Data Explorer tem dois tipos principais de ingestão: em lote e por fluxo. Para obter mais informações, confira ingestão em lote versus ingestão por streaming. O método de streaming é chamado de gerenciado na configuração do exportador do Azure Data Explorer. A ingestão por fluxo pode ser uma boa opção se você precisar que os logs e rastreamentos estejam disponíveis quase em tempo real. No entanto, a ingestão por fluxo usa mais recursos do que a ingestão em lote. A própria estrutura do OTel agrupa os dados em lotes, e isso deve ser considerado ao escolher o método a ser usado para ingestão.

Observação

A ingestão por fluxo deve ser habilitada no cluster do Azure Data Explorer para habilitar a opçãomanaged. Para verificar se o fluxo está habilitado use o comando .show database streaming ingestion policy.

Execute o seguinte comando para cada uma das três tabelas para habilitar a ingestão por fluxo:

.alter table <Table-Name> policy streamingingestion enable

Configurar o exportador do Azure Data Explorer

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

Configure o exportador do Azure Data Explorer usando os seguintes campos:

Campo	Descrição	Configuração sugerida
Exportadores	Tipo de exportador	Azure Data Explorer
cluster_uri	URI do cluster do Azure Data Explorer que contém o banco de dados e as tabelas	https:// <cluster>.kusto.windows.net
application_id	ID do Cliente	<ID do aplicativo>
application_key	Segredo do cliente	<chave do aplicativo>
tenant_id	Locatário	<locatário do aplicativo>
db_name	Banco de dados que recebe os logs	oteldb ou outro banco de dados que você já tenha criado
metrics_table_name	A tabela de destino no banco de dados db_name que armazena os dados de métrica exportados.	OTELMetrics
logs_table_name	A tabela de destino no banco de dados db_name que armazena dados de logs exportados.	OTELLogs
traces_table_name	A tabela de destino no banco de dados db_name que armazena os dados de rastreamento exportados.	OTELTraces
ingestion_type	Tipo de ingestão: gerenciada (por fluxo) ou em lote	managed
metrics_table_json_mapping	Parâmetro opcional. O mapeamento de tabela padrão é definido durante a criação da tabela com base em atributos de métricas do OTeL. O mapeamento padrão pode ser alterado com esse parâmetro.	<json metrics_table_name mapping>
logs_table_json_mapping	Parâmetro opcional. O mapeamento de tabela padrão é definido durante a criação da tabela com base em atributos de logs do OTeL. O mapeamento padrão pode ser alterado com esse parâmetro.	<json logs_table_name mapping>
traces_table_json_mapping	Parâmetro opcional. O mapeamento de tabela padrão é definido durante a criação da tabela com base em atributos de rastreamento do OTeL. O mapeamento padrão pode ser alterado com esse parâmetro.	<json traces_table_name mapping>
traces	Serviços: componentes de rastreamento para habilitar	receptores: [otlp] processadores: [batch] exportadores: [azuredataexplorer]
Métricas	Serviços: componentes de métrica para habilitar	receptores: [otlp] processadores: [batch] exportadores: [azuredataexplorer]
logs	Serviços: componentes de log para habilitar	receptores: [otlp] processadores: [batch] exportadores: [ azuredataexplorer]

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

A seguir, há uma configuração de exemplo para o exportador do 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]

Coletar dados com um aplicativo de exemplo

Agora que o coletor está configurado, você precisa enviar dados para serem ingeridos. Neste exemplo. Você usa o aplicativo spring pet clinic de exemplo com o agente coletor java do OTeL.

Baixe o agente coletor aqui: Agente coletor de telemetria aberta.

Para habilitar a telemetria aberta para o aplicativo de exemplo, defina as seguintes variáveis de ambiente. O host coletor de telemetria aberta faz referência ao host em que o exportador do Azure Data Explorer está configurado e em execução.

Linha de comando
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 o aplicativo spring-boot de exemplo com os seguintes argumentos de linha de comando:

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

Consultar dados de entrada

Depois que o aplicativo de exemplo for executado, seus dados serão ingeridos nas tabelas definidas no Azure Data Explorer. Essas tabelas foram criadas em um banco de dados que foi definido na configuração do coletor do OTel, como oteldb. As tabelas que você criou foram definidas na configuração do coletor do OTel. Neste exemplo, você criou três tabelas: OTELMetrics, OTELLogs e OTELTraces. Nesta seção, você consulta cada tabela separadamente para obter uma pequena amostra dos dados disponíveis.

Navegue até a interface do usuário da Web do Azure Data Explorer.
Selecione Consultar no menu à esquerda.
Expanda o cluster de destino no painel à esquerda.
Selecione o banco de dados oteldb para dar às consultas o contexto correto.

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

Métricas

OTELMetrics
|take 2

Você deve obter resultados semelhantes aos da seguinte tabela, mas não exatamente os mesmos:

Timestamp	MetricName	MetricType	MetricUnit	MetricDescription	MetricValue	Host	MetricAttributes	ResourceAttributes
2022-07-01T12:55:33Z	http.server.active_requests	Somar	solicitações	O número de solicitações HTTP simultâneas que estão atualmente em andamento	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	A duração da solicitação HTTP de entrada (soma total de exemplos)	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"}

Logs

OTELLogs
|take 2

Você deve obter resultados semelhantes aos da seguinte tabela, mas não exatamente os mesmos:

Timestamp	TraceId	SpanID	SeverityText	SeverityNumber	Corpo	ResourceAttributes	LogsAttributes
2022-07-01T13:00:39Z			INFO	9	Starting PetClinicApplication v2.7.0-SNAPSHOT using Java 18.0.1.1 on DESKTOP-SFS7RUQ with 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 active profile set, falling back to 1 default profile: "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"}

Rastreamentos

OTELTraces
|take 2

Você deve obter resultados semelhantes aos da seguinte tabela, mas não exatamente os mesmos:

TraceId	SpanID	ParentId	SpanName	SpanStatus	SpanKind	StartTime	EndTime	ResourceAttributes	TraceAttributes	Eventos	Links
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"}	[]	[]

Processamento adicional dos dados

Usando políticas de atualização, os dados coletados podem ser processados de acordo com a necessidade do aplicativo. Para saber mais, confira Visão geral de política de atualização.

O exemplo a seguir exporta métricas de histograma para uma tabela específica de histograma com buckets e agregações. Execute o seguinte comando no painel de consulta da interface do usuário da 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 comandos a seguir criam uma tabela que contém apenas valores de contagem e soma do tipo de Métrica de histograma e anexam uma política de atualização. Execute o seguinte comando no painel de consulta da interface do usuário da 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

Compartilhar via

Ingerir dados do OpenTelemetry no Azure Data Explorer

Pré-requisitos

Configure seu ambiente

Criar um registro de aplicativo do Microsoft Entra

Conceder permissões ao aplicativo do Microsoft Entra

Criar tabelas de destino

Configurar a ingestão de streaming

Configurar o exportador do Azure Data Explorer

Coletar dados com um aplicativo de exemplo

Consultar dados de entrada

Processamento adicional dos dados

Comentários

Recursos adicionais

Compartilhar via

Ingerir dados do OpenTelemetry no Azure Data Explorer

Pré-requisitos

Configure seu ambiente

Criar um registro de aplicativo do Microsoft Entra

Conceder permissões ao aplicativo do Microsoft Entra

Criar tabelas de destino

Configurar a ingestão de streaming

Configurar o exportador do Azure Data Explorer

Coletar dados com um aplicativo de exemplo

Consultar dados de entrada

Processamento adicional dos dados

Conteúdo relacionado

Comentários

Recursos adicionais