Прием данных из OpenTelemetry в Azure Data Explorer

  • Статья

Важно!

Этот соединитель можно использовать в аналитике в режиме реального времени в Microsoft Fabric. Используйте инструкции в этой статье со следующими исключениями:

OpenTelemetry (OTel) — это открытая платформа для наблюдения за приложениями. Инструментирование размещается в Cloud Native Computing Foundation (CNCF), который предоставляет стандартные интерфейсы для данных наблюдаемости, включая метрики, журналы и трассировки. Сборщик OTel состоит из следующих трех компонентов: получатели получают данные в сборщик, обработчики определяют, что делать с полученными данными, а экспортеры отвечают за то, куда отправлять полученные данные.

Средство экспорта Data Explorer Azure поддерживает прием данных от многих получателей в Data Explorer Azure.

Примечание

Вы узнаете, как выполнять следующие задачи:

  • Настройка среды
  • Настройка средства экспорта Data Explorer Azure
  • Запуск примера приложения
  • Запрос входящих данных

Предварительные требования

Настройка среды

В этом разделе вы подготовите среду для использования средства экспорта OTel.

Создание регистрации приложения Microsoft Entra

Microsoft Entra проверка подлинности приложения используется для приложений, которым требуется доступ к Azure Data Explorer без пользователя. Чтобы принимать данные с помощью средства экспорта OTel, необходимо создать и зарегистрировать субъект-службу Microsoft Entra, а затем авторизовать этот субъект для приема данных в базе данных azure Data Explorer.

  1. Используя кластер Azure Data Explorer, выполните шаги 1–7 из раздела Создание регистрации приложения Microsoft Entra в Azure Data Explorer.
  2. Сохраните следующие значения, чтобы использовать их на последующих шагах:
    • Идентификатор приложения (клиента)
    • Идентификатор каталога (клиента)
    • Значение секретного ключа клиента

Предоставление разрешений приложения Microsoft Entra

  1. На вкладке запроса пользовательского веб-интерфейса подключитесь к кластеру. Дополнительные сведения о подключении см. в разделе Добавление кластеров.

  2. Перейдите к базе данных, в которой вы хотите принимать данные.

  3. Выполните следующую команду управления, заменив заполнители. Замените DatabaseName именем целевой базы данных, а ApplicationID — ранее сохраненным значением. Эта команда предоставляет приложению роль ingestor базы данных . Дополнительные сведения см. в разделе Управление ролями безопасности базы данных.

    .add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'

    Примечание

    Последний параметр — это строка, которая отображается в виде примечаний при запросе ролей, связанных с базой данных. Дополнительные сведения см. в разделе Просмотр существующих ролей безопасности.

Создание целевых таблиц

  1. Перейдите в пользовательский веб-интерфейс azure Data Explorer.

  2. Выберите Запрос в меню слева.

  3. Разверните целевой кластер в области слева.

  4. Выберите целевую базу данных, чтобы предоставить запросам правильный контекст.

  5. Выполните следующие команды, чтобы создать таблицы и сопоставление схем для входящих данных:

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

Настройка приема потоковой передачи

Azure Data Explorer имеет два main типа приема: пакетную и потоковую передачу. Дополнительные сведения см. в статье Пакетная обработка и прием потоковой передачи. Метод потоковой передачи называется управляемым в конфигурации средства экспорта Data Explorer Azure. Прием потоковой передачи может быть хорошим выбором, если вам нужно, чтобы журналы и трассировки были доступны почти в реальном времени. Однако прием потоковой передачи использует больше ресурсов, чем пакетный прием. Платформа OTel сама пакетирует данные, что следует учитывать при выборе метода для приема.

Примечание

Чтобы включить этот параметр, необходимо включить прием потоковой передачиmanaged в кластере Azure Data Explorer. Если потоковая передача включена, можно проверка с помощью команды .show database streaming ingestion policy.

Выполните следующую команду для каждой из трех таблиц, чтобы включить прием потоковой передачи:

.alter table <Table-Name> policy streamingingestion enable

Настройка средства экспорта Data Explorer Azure

Чтобы принимать данные OpenTelemetry в azure Data Explorer, необходимо развернуть и запустить дистрибутив OpenTelemetry со следующей конфигурацией экспорта azure Data Explorer.

  1. Настройте средство экспорта Data Explorer Azure, используя следующие поля:

    Поле Описание Предлагаемый параметр
    Средства экспорта Тип средства экспорта Azure Data Explorer
    cluster_uri URI кластера azure Data Explorer, в котором хранится база данных и таблицы <https:// cluster.kusto.windows.net>
    application_id Идентификатор клиента <идентификатор приложения>
    application_key Секрет клиента <ключ приложения>
    tenant_id Клиент <клиент приложения>
    db_name База данных, получающая журналы oteldb или другая база данных, которую вы уже создали
    metrics_table_name Целевая таблица в базе данных db_name, в котором хранятся экспортированные данные метрик. OTELMetrics
    logs_table_name Целевая таблица в базе данных db_name, в котором хранятся экспортированные данные журналов. OTELLogs
    traces_table_name Целевая таблица в базе данных db_name, в котором хранятся экспортированные данные трассировки. OTELTraces
    ingestion_type Тип приема: управляемый (потоковая передача) или пакетный Управляемые
    metrics_table_json_mapping Необязательный параметр. Сопоставление таблиц по умолчанию определяется во время создания таблицы на основе атрибутов метрик OTeL. Сопоставление по умолчанию можно изменить с помощью этого параметра. <Сопоставление metrics_table_name JSON>
    logs_table_json_mapping Необязательный параметр. Сопоставление таблиц по умолчанию определяется во время создания таблицы на основе атрибутов журналов OTeL. Сопоставление по умолчанию можно изменить с помощью этого параметра. <Сопоставление logs_table_name JSON>
    traces_table_json_mapping Необязательный параметр. Сопоставление таблиц по умолчанию определяется во время создания таблицы на основе атрибутов трассировки OTeL. Сопоставление по умолчанию можно изменить с помощью этого параметра. <Сопоставление traces_table_name JSON>
    traces Службы: компоненты трассировки для включения receivers: [otlp]
    процессоры: [пакет]
    exporters: [azuredataexplorer]
    Метрики Службы: компоненты метрик для включения receivers: [otlp]
    процессоры: [пакет]
    exporters: [azuredataexplorer]
    журналы Службы: регистрируются компоненты для включения. receivers: [otlp]
    процессоры: [пакет]
    exporters: [ azuredataexplorer]

  2. Используйте флаг "--config" для запуска средства экспорта Data Explorer Azure.

Ниже приведен пример конфигурации для средства экспорта Data Explorer 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]

Сбор данных с помощью примера приложения

Теперь, когда сборщик настроен, необходимо отправить данные для приема. В этом примере Вы используете пример приложения spring pet clinic с агентом сборщика OTeL java.

  1. Скачайте агент сборщика здесь: Откройте агент сборщика телеметрии.

  2. Чтобы включить открытую телеметрию для примера приложения, задайте следующие переменные среды. Open-telemetry-collector-host ссылается на узел, на котором настроен и работает средство экспорта Data Explorer Azure.

    $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. Запустите пример приложения spring-boot со следующими аргументами командной строки:

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

Запрос входящих данных

После запуска примера приложения данные будут приняты в определенные таблицы в Azure Data Explorer. Эти таблицы были созданы в базе данных, которая была определена в конфигурации сборщика OTel как oteldb. Созданные таблицы были определены в конфигурации сборщика OTel. В этом примере вы создали три таблицы: OTELMetrics, OTELLogs и OTELTraces. В этом разделе вы запросите каждую таблицу отдельно, чтобы получить небольшой выбор доступных данных.

  1. Перейдите в пользовательский веб-интерфейс azure Data Explorer.

  2. Выберите Запрос в меню слева.

  3. Разверните целевой кластер в области слева.

  4. Выберите базу данных oteldb , чтобы предоставить запросам правильный контекст.

  5. Скопируйте или вставьте следующие запросы последовательно, чтобы просмотреть произвольное количество строк из каждой таблицы:

    • Метрики

      OTELMetrics
|take 2

      Вы должны получить результаты, которые похожи, но не совсем совпадают, как показано в следующей таблице:

      Отметка времени MetricName MetricType MetricUnit MetricDescription MetricValue Host MetricAttributes ResourceAttributes
      2022-07-01T12:55:33Z http.server.active_requests SUM requests Количество одновременных HTTP-запросов, которые в настоящее время находятся в режиме выполнения 0 SFS7RUQ desktop-SFS7RUQ {"http.flavor":"1.1", "http.host":"localhost:8080", "область.name":"io.opentelemetry.tomcat-7.0", "область.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-разрядная виртуальная машина сервера 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 Гистограмма ms Длительность входящего HTTP-запроса (общее количество примеров) 114.9881 SFS7RUQ desktop-SFS7RUQ {"http.flavor":"1.1", "http.host":"localhost:8080", "область.name":"io.opentelemetry.tomcat-7.0", "область.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-разрядная виртуальная машина сервера 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"}

    • Журналы

      OTELLogs
|take 2

      Вы должны получить результаты, которые похожи, но не совсем совпадают, как показано в следующей таблице:

      Отметка времени TraceId SpanId SeverityText SeverityNumber Текст ResourceAttributes LogsAttributes
      2022-07-01T13:00:39Z ИНФОРМАЦИЯ 9 Запуск PetClinicApplication версии 2.7.0-SNAPSHOT с помощью Java 18.0.1.1 на DESKTOP-SFS7RUQ с PID 37280 (C:\Users\adxuser\Documents\Repos\spring-petclinic\target\spring-petclinic-2.7.0-SNAPSHOT.jar начато adxuser в 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-разрядная виртуальная машина сервера 18.0.1.1+2-6", "process.runtime.name":"Среда выполнения Java(TM) SE", "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"} {"область.name":"org.springframework.samples.petclinic.PetClinicApplication"}
      2022-07-01T13:00:39Z ИНФОРМАЦИЯ 9 Активный профиль не задан, вернитесь к 1 профилю по умолчанию: "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-разрядная виртуальная машина сервера 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"} {"область.name":"org.springframework.samples.petclinic.PetClinicApplication"}

    • Трассировки

      OTELTraces
|take 2

      Вы должны получить результаты, аналогичные, но не совсем одинаковые, как показано в следующей таблице:

      TraceId SpanId ParentId SpanName SpanStatus SpanKind StartTime EndTime ResourceAttributes TraceAttributes События Ссылки
      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-разрядная виртуальная машина сервера 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", "область.name":"io.opentelemetry.jdbc", "область.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-разрядная виртуальная машина сервера 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", "область.name":"io.opentelemetry.jdbc", "область.version":"1.14.0-alpha", "db.connection_string":"h2:mem:", "db.statement":"DROP TABLE vets IF EXISTS"} [] []

Дальнейшая обработка данных

С помощью политик обновления собранные данные можно дополнительно обрабатывать в случае необходимости приложения. Дополнительные сведения см. в статье Обзор политики обновления.

  1. В следующем примере метрики гистограммы экспортируются в таблицу с сегментами и агрегатами. Выполните следующую команду в области запросов пользовательского веб-интерфейса 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. Следующие команды создают таблицу, которая содержит только значения счетчика и суммы для типа метрик гистограммы, и присоединяет политику обновления. Выполните следующую команду в области запросов пользовательского веб-интерфейса 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

См. также