Ingerir dados do OpenTelemetry no Azure Data Explorer

O OpenTelemetry (OTel) é uma estrutura aberta para a observabilidade do aplicativo. A instrumentação é hospedada pelo CNCF (Cloud Native Computing Foundation). Ele fornece interfaces padrão para dados de observabilidade, incluindo métricas, logs e rastreamentos. O Coletor OTel inclui três componentes: receptores, que obtêm dados no Coletor; processadores, que determinam o que fazer com os dados recebidos; e exportadores, que enviam os dados recebidos para um destino.

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

Neste artigo, você aprenderá como:

Pré-requisitos

• Uma assinatura do Azure. Criar uma conta gratuita do Azure.
• Um cluster e um banco de dados. Saiba como 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 de aplicativo do Microsoft Entra permite que os aplicativos acessem o Azure Data Explorer sem que um usuário esteja presente. Para ingerir dados usando o exportador OTel, crie e registre uma entidade de serviço do Microsoft Entra e autorize essa entidade a ingerir dados em um banco de dados do Azure Data Explorer.

1. No cluster do Azure Data Explorer, siga as etapas 1 a 7 em Criar um registro de aplicativo do Microsoft Entra no Azure Data Explorer.
2. Salve os seguintes valores para etapas posteriores:

Conceder permissões ao aplicativo do Microsoft Entra

1. Na guia de consulta da interface do usuário da Web, conecte-se ao cluster. Para saber como se conectar, consulte Adicionar clusters.

2. Navegue até o banco de dados no qual você deseja ingerir dados.

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

   .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

1. Navegue até a interface do usuário da Web do Azure Data Explorer.

2. Selecione Consultar no menu à esquerda.

3. Expanda o cluster de destino no painel à esquerda.

4. Selecione o banco de dados de destino para fornecer às suas consultas o contexto correto.

5. 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 de streaming pode ser uma boa opção se você precisar de logs e rastros disponíveis praticamente em tempo real. No entanto, a ingestão por fluxo usa mais recursos do que a ingestão em lote. A estrutura OTel agrupa dados, que você deve considerar ao escolher um método de ingestão.

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.

1. 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ê criou.
   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	gerenciado
   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.	<mapeamento de metrics_table_name json>
   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.	<mapeamento de logs_table_name json>
   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.	<mapeamento de traces_table_name json>
   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]

2. Para executar o exportador do Azure Data Explorer, use o sinalizador "--config".

Esta é 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 de exemplo spring pet clinic com o agente coletor OTeL Java.

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

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

3. 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 são criadas em um banco de dados que foi definido na configuração do coletor OTel, como oteldb. As tabelas criadas são definidas na configuração do coletor 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.

1. Navegue até a interface do usuário da Web do Azure Data Explorer.

2. Selecione Consultar no menu à esquerda.

3. Expanda o cluster de destino no painel à esquerda.

4. Selecione o banco de dados oteldb para dar às consultas o contexto correto.

5. 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.0 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	Iniciando o PetClinicApplication v2.7.0-SNAPSHOT usando o Java 18.0.1.1 no DESKTOP-SFS7RUQ com o 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"}
     2022-07-01T13:00:39Z			INFO	9	Nenhum perfil ativo está definido, revertendo para 1 perfil padrão: "padrã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"}

   • 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

Use políticas de atualização para processar ainda mais os dados coletados, de acordo com a necessidade do aplicativo. Para saber mais, confira Visão geral de política de atualização.

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

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

Conteúdo relacionado

• Referência rápida de KQL
• Visão geral do KQL (Linguagem de Consulta Kusto)