OpenTelemetry から Azure Data Explorer にデータを取り込む

[アーティクル]
07/25/2024

重要

このコネクタは、Microsoft Fabric のリアルタイムインテリジェンスで使用できます。次の例外を除き、この記事の手順を使用してください。

必要に応じて、「KQL データベースを作成する」の手順に従ってデータベースを作成する。
必要に応じて、「空のテーブルを作成する」の手順に従ってテーブルを作成する。
「URI をコピーする」の手順に従って、クエリまたはインジェスト URI を取得する。
KQL クエリセットでクエリを実行する。

OpenTelemetry (OTel) は、アプリケーションを監視するためのオープンフレームワークです。このインストルメンテーションは Cloud Native Computing Foundation (CNCF) によってホストされており、メトリック、ログ、トレースなど、監視データ用の標準インターフェイスが提供されます。 OTel コレクターは、次の 3 つのコンポーネントで構成されています。レシーバーはコレクターにデータを取得する方法を扱い、プロセッサは受信したデータの処理方法を決定し、エクスポーターは受信したデータを送信する場所を決定します。

Azure Data Explorer エクスポーターでは、多くのレシーバーから Azure Data Explorer へのデータの取り込みがサポートされています。

Note

構成設定は、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 クラスターを使用して、「Azure Data Explorer で Microsoft Entra アプリケーション登録を作成する」の手順 1 から 7 に従います。
後で使用するために、次の値を保存します。
- アプリケーション (クライアント) ID
- ディレクトリ (テナント) ID
- クライアントシークレットのキー値

Microsoft Entra アプリにアクセス許可を付与する

Web UI の [クエリ] タブで、クラスターに接続します。接続方法の詳細については、「クラスターを追加する」を参照してください。
データを取り込むデータベースを参照します。
プレースホルダーを置き換えて、次の管理コマンドを実行します。 DatabaseName をターゲットデータベースの名前に置き換え、ApplicationID を以前に保存した値に置き換えます。このコマンドは、データベースインジェスターロールをアプリに付与します。詳細については、「データベースセキュリティロールの管理」を参照してください。
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'
```
Note

最後のパラメーターは、データベースに関連付けられているロールに対してクエリを実行するときに、メモとして表示される文字列です。詳細については、「既存のセキュリティロールを表示する」を参照してください。

ターゲットテーブルを作成する

Azure Data Explorer の Web UI に移動します。
左側のメニューで [クエリ] を選択します。
左側のペインにあるターゲットクラスターを展開します。
ターゲットデータベースを選び、クエリに正しいコンテキストを指定します。

次のコマンドを実行して、受信データのテーブルとスキーママッピングを作成します。

.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 には、主にバッチ処理とストリーミングという 2 種類のインジェストがあります。詳細については、「バッチ処理とストリーミングインジェスト」を参照してください。 "streaming" メソッドは、Azure Data Explorer エクスポーター構成では "managed" と呼ばれます。ログとトレースをほぼリアルタイムで使用できるようにする必要がある場合は、ストリーミングインジェストが適している場合があります。ただし、ストリーミングインジェストでは、バッチ処理インジェストよりも多くのリソースが使用されます。 OTel フレームワーク自体でデータがバッチ処理されるので、インジェストに使用するメソッドを選択する際にはこの点を考慮する必要があります。

Note

managed オプションを有効にするには、Azure Data Explorer クラスターでストリーミングインジェストを有効にする必要があります。 .show データベースストリーミングインジェストポリシーコマンドを使用して、ストリーミングが有効になっているかどうかを確認できます。

ストリーミングインジェストを有効にするには、3 つのテーブルごとに次のコマンドを実行します。

.alter table <Table-Name> policy streamingingestion enable

Azure Data Explorer エクスポーターを構成する

OpenTelemetry データを Azure Data Explorer に取り込むには、次の Azure Data Explorer エクスポーター構成で OpenTelemetry ディストリビューションを展開して実行する必要があります。

次のフィールドを使用して、Azure Data Explorer エクスポーターを構成します。

フィールド	説明	推奨される設定
エクスポーター	エクスポーターの種類	Azure Data Explorer
cluster_uri	データベースとテーブルを保持する Azure Data Explorer クラスターの URI	https:// <cluster>.kusto.windows.net
application_id	クライアント ID	<アプリケーション 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 メトリック属性に基づいてテーブルの作成時に定義されます。このパラメーターを使用して、既定のマッピングを変更できます。	<json metrics_table_name mapping>
logs_table_json_mapping	省略可能な型のパラメーターです。既定のテーブルマッピングは、OTeL ログ属性に基づいてテーブルの作成時に定義されます。このパラメーターを使用して、既定のマッピングを変更できます。	<json logs_table_name mapping>
traces_table_json_mapping	省略可能な型のパラメーターです。既定のテーブルマッピングは、OTeL トレース属性に基づいてテーブルの作成時に定義されます。このパラメーターを使用して、既定のマッピングを変更できます。	<json traces_table_name mapping>
traces	サービス: 有効にするトレースコンポーネント	レシーバー: [otlp] プロセッサ: [バッチ] エクスポーター: [azuredataexplorer]
メトリック	サービス: 有効にするメトリックコンポーネント	レシーバー: [otlp] プロセッサ: [バッチ] エクスポーター: [azuredataexplorer]
logs	サービス: 有効にするログコンポーネント	レシーバー: [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]

サンプルアプリケーションを使用してデータを収集する

コレクターが構成されたので、取り込むデータを送信する必要があります。この例では、 java OTeL コレクターエージェントでサンプル spring pet clinic アプリケーションを使用します。

オープンテレメトリコレクターエージェントでコレクターエージェントをダウンロードします。

サンプルアプリケーションのオープンテレメトリを有効にするには、次の環境変数を設定します。 open-telemetry-collector-host は、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 の 3 つのテーブルを作成しました。このセクションでは、各テーブルに対して個別にクエリを実行して、利用可能なデータのごく一部を取得します。

Azure Data Explorer の Web UI に移動します。
左側のメニューで [クエリ] を選択します。
左側のペインにあるターゲットクラスターを展開します。
oteldb データベースを選び、クエリに正しいコンテキストを指定します。

次のクエリを順番にコピー/ペーストすると、各テーブルから任意の数の行が表示されます。

メトリック

OTELMetrics
|take 2

次の表に示すように、まったく同じではありませんが、類似した結果が得られます。

タイムスタンプ	MetricName	MetricType	MetricUnit	MetricDescription	MetricValue	Host	MetricAttributes	ResourceAttributes
2022-07-01T12:55:33Z	http.server.active_requests	SUM	requests	現在処理中の同時 HTTP 要求の数	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	ヒストグラム	ms	受信 HTTP 要求の期間 (サンプルの合計)	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"}

ログ

OTELLogs
|take 2

次の表に示すように、まったく同じではありませんが、類似した結果が得られます。

タイムスタンプ	TraceId	SpanId	SeverityText	SeverityNumber	本文	ResourceAttributes	LogsAttributes
2022-07-01T13:00:39Z			INFO	9	DESKTOP-SFS7RUQ で Java 18.0.1.1 を使用して PetClinicApplication v2.7.0-SNAPSHOT を 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	アクティブなプロファイルセットなし、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-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"}

トレース

OTELTraces
|take 2

次の表に示すように、まったく同じではありませんが、類似した結果が得られます。

TraceId	SpanId	ParentId	SpanName	SpanStatus	SpanKind	StartTime	EndTime	ResourceAttributes	TraceAttributes	Events	リンク
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"}	$	$

その他のデータ処理

更新ポリシーを使用すると、収集されたデータをアプリケーションのニーズに応じてさらに処理することができます。詳しくは、「更新ポリシーの概要」をご覧ください。

次の例では、バケットと集計を含むヒスト固有のテーブルにヒストグラムメトリックをエクスポートします。 Azure Data Explorer Web UI のクエリウィンドウで次のコマンドを実行します。

.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 Web UI のクエリウィンドウで次のコマンドを実行します。

 .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 エクスポーターを構成する

サンプル アプリケーションを使用してデータを収集する

受信データのクエリを実行する

その他のデータ処理

関連するコンテンツ

フィードバック

その他のリソース

ターゲットテーブルを作成する

ストリーミングインジェストを設定する

サンプルアプリケーションを使用してデータを収集する