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

Статья
06/25/2024

Внимание

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

При необходимости создайте базы данных с помощью инструкций в статье "Создание базы данных KQL".
При необходимости создайте таблицы с помощью инструкций в статье "Создание пустой таблицы".
Получение URI запроса или приема с помощью инструкций в URI копирования.
Выполнение запросов в наборе запросов KQL.

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

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

Примечание.

Параметры конфигурации приведены в документации по readme.
Исходный код экспортера см. в статье "Экспортер данных Azure Data Explorer".

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

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

Необходимые компоненты

Подписка Azure. Создайте бесплатную учетную запись Azure.
Кластер и база данных. Краткое руководство. Создание кластера и базы данных Azure Data Explorer

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

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

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

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

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

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

На вкладке запроса веб-интерфейса подключитесь к кластеру. Дополнительные сведения о подключении см. в разделе "Добавление кластеров".
Перейдите к базе данных, в которой требуется принять данные.
Выполните следующую команду управления, заменив заполнители. Замените DatabaseName именем целевой базы данных и ApplicationID ранее сохраненным значением. Эта команда предоставляет приложению роль ingestor базы данных. Дополнительные сведения см. в разделе "Управление ролями безопасности базы данных".
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'
```
Примечание.

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

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

Перейдите к веб-интерфейсу Azure Data Explorer.
Выберите "Запрос" в меню слева.
Разверните целевой кластер на левой панели.
Выберите целевую базу данных, чтобы предоставить запросы правильному контексту.

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

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

Примечание.

Для включения этого managed параметра необходимо включить прием потоковой передачи в кластере Azure Data Explorer. Можно проверить, включена ли потоковая передача с помощью команды политики приема потоковой передачи базы данных .show.

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

.alter table <Table-Name> policy streamingingestion enable

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

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

Настройте экспортер Azure Data Explorer с помощью следующих полей:

Поле	Description	Предлагаемый параметр
Экспортеры	Тип экспортера	Azure Data Explorer
cluster_uri	Универсальный код ресурса (URI) кластера Azure Data Explorer, в котором хранится база данных и таблицы	<https:// cluster.kusto.windows.net>
application_id	Client 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	Тип приема: управляемый (потоковая передача) или пакетный прием	managed
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	Службы: компоненты трассировки для включения	приемники: [otlp] процессоры: [пакет] экспортеры: [azuredataexplorer]
Метрики	Службы: компоненты метрик для включения	приемники: [otlp] процессоры: [пакет] экспортеры: [azuredataexplorer]
журналы	Службы: журналы компонентов для включения	приемники: [otlp] процессоры: [пакет] экспортеры: [ azuredataexplorer]

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

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

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

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

Скачайте агент сборщика: откройте агент сборщика телеметрии.

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

Командная строка
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

Запустите пример приложения spring-boot со следующими аргументами командной строки:
```
java -javaagent:./opentelemetry-javaagent.jar -jar spring-petclinic-<version>-SNAPSHOT.jar    
```

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

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

Перейдите к веб-интерфейсу Azure Data Explorer.
Выберите "Запрос" в меню слева.
Разверните целевой кластер на левой панели.
Выберите базу данных oteldb, чтобы предоставить запросы правильному контексту.

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

Метрики

OTELMetrics
|take 2

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

Метка времени	MetricName	MetricType	MetricUnit	MetricDescription	MetricValue	Хост	MetricAttributes	ResourceAttributes
2022-07-01T12:55:33Z	http.server.active_requests	Sum	requests	Количество одновременных HTTP-запросов, которые в настоящее время выполняются в тестовом режиме	0	Классический 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"}	{"host.name":"DESKTOP-SFS7RUQ", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1; бункер; 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; бункер; java.exe", "process.pid":5980, "service.name":"my-service", "telemetry.sdk.version":"1.14.0"}
2022-07-01T12:55:33Z	http.server.duration_sum	Гистограмма	мс	Длительность входящего HTTP-запроса (сумма примеров)	114.9881	Классический 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; бункер; 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; бункер; java.exe", "process.pid":5980, "service.name":"my-service", "telemetry.sdk.version":"1.14.0"}

Журналы

OTELLogs
|take 2

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

Метка времени	TraceId	SpanId	Уровень серьезности	Номер серьезности	Текст	ResourceAttributes	LogsAttributes
2022-07-01T13:00:39Z			INFO	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.исполняемый.path":"C:\Program Files\Java\jdk-18.0.1.1; бункер; 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; бункер; 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	Нет активного набора профилей, возвращаясь к 1 профилю по умолчанию: "по умолчанию"	{"host.name":"DESKTOP-SFS7RUQ", "process.исполняемый.path":"C:\Program Files\Java\jdk-18.0.1.1; бункер; 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; бункер; 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"}

Трассировки

OTELTraces
|take 2

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

TraceId	SpanId	ParentId	SpanName	SpanStatus	SpanKind	Время начала	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.исполняемый.path":"C:\Program Files\Java\jdk-18.0.1.1; бункер; 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; бункер; java.exe -javaagent:./opentelemetry-javaagent.jar", "telemetry.sdk.version":"1.14.0"}	{"db.user":"sa", "thread.id":1, "db.name":"87d003d03d6-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.исполняемый.path":"C:\Program Files\Java\jdk-18.0.1.1; бункер; 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; бункер; java.exe -javaagent:./opentelemetry-javaagent.jar", "telemetry.sdk.version":"1.14.0"}	{"db.user":"sa", "thread.id":1, "db.name":"87d003d03d6-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"}	[]	[]

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

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

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

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

Поделиться через

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

Необходимые компоненты

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

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

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

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

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

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

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

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

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

Обратная связь

Дополнительные ресурсы

Поделиться через

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

Необходимые компоненты

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

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

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

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

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

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

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

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

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

Связанный контент

Обратная связь

Дополнительные ресурсы