Ingerir dados do OpenTelemetry para o Azure Data Explorer

OpenTelemetry (OTel) é uma estrutura aberta para observabilidade de aplicativos. A instrumentação é hospedada pela Cloud Native Computing Foundation (CNCF). Ele fornece interfaces padrão para dados de observabilidade, incluindo métricas, logs e rastreamentos. O OTel Collector inclui três componentes: recetores, que recebem 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 muitos recetores no Azure Data Explorer.

Neste artigo, você aprenderá a:

Pré-requisitos

• Uma assinatura do Azure. Crie uma conta do Azure gratuita.
• Um cluster e um banco de dados. Saiba como criar um cluster e um banco de dados do Azure Data Explorer.

Configurar o ambiente

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

Criar um registo da aplicação Microsoft Entra

A autenticação de aplicativo Microsoft Entra permite que os aplicativos acessem o Azure Data Explorer sem a presença de um usuário. 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 Microsoft Entra no Azure Data Explorer.
2. Salve os seguintes valores para etapas posteriores:

Conceder permissões ao aplicativo 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 seguinte comando de gestão, substituindo os marcadores. 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 notas 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 Consulta no menu à esquerda.

3. Expanda o cluster de destino no painel esquerdo.

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

5. Execute os seguintes comandos para criar tabelas e 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 dados em fluxo

O Azure Data Explorer tem dois tipos principais de ingestão: envio em lote e streaming. Para obter mais informações, consulte Loteamento vs ingestão de streaming. O método de streaming é chamado gerenciado na configuração do exportador do Azure Data Explorer. A ingestão de streaming pode ser uma boa escolha se você precisar de logs e rastreamentos disponíveis quase em tempo real. No entanto, a ingestão por streaming usa mais recursos do que a ingestão em lote. A estrutura OTel armazena dados em lotes, que você deve considerar ao escolher um método de ingestão.

Execute o seguinte comando para cada uma das três tabelas para ativar a ingestão por streaming.

.alter table <Table-Name> policy streamingingestion enable

Configurar o exportador do Azure Data Explorer

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

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

   Campo	Description	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>
   identificador_da_aplicação	ID do Cliente	<ID do aplicativo>
   chave_da_aplicação	Segredo do cliente	<chave de aplicação>
   ID do inquilino	Tenant	<inquilino da aplicação>
   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 dados métricos 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 dados de rastreamentos exportados.	OTELTraces
   tipo_de_ingestão	Tipo de ingestão: gestão (streaming) ou em lote	managed
   mapeamento_json_da_tabela_de_métricas	Parâmetro opcional. O mapeamento de tabela padrão é definido durante a criação da tabela com base nos atributos de métricas OTeL. O mapeamento padrão pode ser alterado usando esse parâmetro.	<Mapeamento metrics_table_name JSON>
   mapeamento_logs_tabela_json	Parâmetro opcional. O mapeamento de tabela padrão é definido durante a criação da tabela com base nos atributos de logs OTeL. O mapeamento padrão pode ser alterado usando 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 nos atributos de rastreamento OTeL. O mapeamento padrão pode ser alterado usando esse parâmetro.	<Mapeamento de traces_table_name JSON>
   traces	Serviços: monitoriza componentes para ativar	Recetores: [OTLP] Processadores: [Batch] Exportadores: [AzureDataExplorer]
   métricas	Serviços: componentes de métricas para ativar	Recetores: [OTLP] Processadores: [Batch] Exportadores: [AzureDataExplorer]
   registos	Serviços: registra componentes para habilitar	Recetores: [OTLP] Processadores: [Batch] Exportadores: [ AzureDataExplorer]

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

Este é um exemplo de configuração 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ê utiliza a aplicação exemplo Spring Pet Clinic com o agente coletor Java OTeL.

1. Faça o download do agente coletor aqui: Abra o agente coletor de telemetria.

2. Para habilitar a telemetria aberta para o aplicativo de exemplo, defina as seguintes variáveis de ambiente. O open-telemetry-collector-host faz referência ao host onde o exportador do Azure Data Explorer 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"
   

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 seleção dos dados disponíveis.

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

2. Selecione Consulta no menu à esquerda.

3. Expanda o cluster de destino no painel esquerdo.

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

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

   • Metrics

     OTELMetrics
     |take 2
     

     Você deve obter resultados semelhantes, mas não exatamente iguais, conforme a tabela a seguir:

     Data e Hora	Nome da Métrica	Tipo Métrico	Unidade Métrica	Descrição da Métrica	Valor Métrico	Host	MetricAttributes	ResourceAttributes
     2022-07-01T12:55:33Z	http.server.active_requests	Soma	pedidos	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 amostras)	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"}

   • Registos

     OTELLogs
     |take 2
     

     Você deve obter resultados semelhantes, mas não exatamente iguais, conforme a tabela a seguir:

     Data e Hora	TraceId	SpanId	Nível de SeveridadeTexto	Número de gravidade	Body	ResourceAttributes	Atributos de Logs
     2022-07-01T13:00:39Z			INFORMAÇÃO	9	Iniciando PetClinicApplication v2.7.0-SNAPSHOT usando Java 18.0.1.1 em DESKTOP-SFS7RUQ com PID 37280 (C:\Users\adxuser\Documents\Repos\spring-petclinic\target\spring-petclinic-2.7.0-SNAPSHOT.jar iniciado por 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			INFORMAÇÃO	9	Nenhum perfil ativo definido, caindo de volta para 1 perfil padrão: "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"}

   • Rastreios

     OTELTraces
     |take 2
     

     Você deve obter resultados semelhantes, mas não exatamente iguais, conforme a tabela a seguir:

     TraceId	SpanId	ParentId	SpanName	SpanStatus	SpanKind	StartTime	EndTime	ResourceAttributes	TraceAttributes	Events	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 SE EXISTIR"}	[]	[]
     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"}	[]	[]

Tratamento posterior de dados

Use políticas de atualização para processar ainda mais os dados coletados, de acordo com a necessidade do aplicativo. Para obter mais informações, consulte Visão geral da política de atualização.

1. O exemplo a seguir exporta métricas de histograma para uma tabela histo-específica 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 Histograma e anexa 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 do KQL
• Visão geral do Kusto Query Language (KQL)