Compartilhar via

Ingerir dados do OpenTelemetry no Azure Data Explorer

  • Artigo

Importante

Este conector pode ser usado em Real-Time Intelligence no Microsoft Fabric. Use as instruções incluídas neste artigo com as seguintes exceções:

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

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

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.

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

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

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

  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 dar o contexto correto às consultas.

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

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

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

  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.

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

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

  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