OpenTelemetry から Azure Data Explorer にデータを取り込む
重要
このコネクタは、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 エクスポーターが構成され、実行されているホストを参照します。
次のコマンド ライン引数を使用して、サンプルの 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