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

  • [アーティクル]

重要

このコネクタは、Microsoft Fabric の リアルタイム分析 で使用できます。 次の例外を含め、この記事の手順を使用します。

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

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

注意

この記事では、次の方法について説明します。

  • 環境を設定する
  • Azure Data Explorer エクスポーターを構成する
  • サンプル アプリケーションの実行
  • 受信データのクエリを実行する

前提条件

環境を設定する

このセクションでは、OTel エクスポーターを使用するように環境を準備します。

Microsoft Entra アプリの登録を作成する

Microsoft Entraアプリケーション認証は、ユーザーが存在せずに Azure Data Explorerにアクセスする必要があるアプリケーションに使用されます。 OTel エクスポーターを使用してデータを取り込むには、Microsoft Entra サービス プリンシパルを作成して登録し、このプリンシパルが Azure Data Explorer データベースにデータを取り込むよう承認する必要があります。

  1. Azure Data Explorer クラスターを使用して、「Azure Data Explorer でMicrosoft Entraアプリケーション登録を作成する」の手順 1 から 7 に従います。
  2. 後の手順で使用する次の値を保存します。
    • アプリケーション (クライアント) ID
    • ディレクトリ (テナント) ID
    • クライアント シークレット キーの値

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

  1. Web UI の [クエリ] タブで、クラスターに接続します。 接続方法の詳細については、「 クラスターの追加」を参照してください。

  2. データを取り込むデータベースを参照します。

  3. プレースホルダーを置き換えて、次の管理コマンドを実行します。 DatabaseName をターゲット データベースの名前に置き換え、ApplicationID を以前に保存した値に置き換えます。 このコマンドは、アプリに データベース 取り込みロール を付与します。 詳細については、「 データベース セキュリティ ロールの管理」を参照してください。

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

    注意

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

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

  1. Azure Data Explorer の Web UI に移動します。

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

注意

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

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

.alter table <Table-Name> policy streamingingestion enable

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

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

  1. 次のフィールドを使用して、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 Tenant <アプリケーション テナント>
    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]
    metrics サービス: 有効にするメトリック コンポーネント レシーバー: [otlp]
    プロセッサ: [バッチ]
    エクスポーター: [azuredataexplorer]
    logs サービス: 有効にするログ コンポーネント レシーバー: [otlp]
    プロセッサ: [バッチ]
    エクスポーター: [azuredataexplorer]

  2. "--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 コレクター エージェントでサンプル のスプリング ペット クリニック アプリケーションを使用します。

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

  2. サンプル アプリケーションのオープン テレメトリを有効にするには、次の環境変数を設定します。 open-telemetry-collector-host は、Azure Data Explorer エクスポーターが構成され、実行されているホストを参照します。

    $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 の 3 つのテーブルを作成しました。 このセクションでは、各テーブルに個別にクエリを実行して、使用可能なデータの小さな選択を取得します。

  1. Azure Data Explorer の Web UI に移動します。

  2. 左側のメニューで [クエリ] を選択します。

  3. 左側のペインにあるターゲット クラスターを展開します。

  4. oteldb データベースを選び、クエリに正しいコンテキストを指定します。

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

    • メトリック

      OTELMetrics
|take 2

      次の表とまったく同じではなく、類似した結果を得る必要があります。

      Timestamp 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

      次の表とまったく同じではなく、類似した結果を得る必要があります。

      Timestamp 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"} [] []

その他のデータ処理

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

  1. 次の例では、バケットと集計を含むヒスト固有のテーブルにヒストグラム メトリックをエクスポートします。 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}]'

  2. 次のコマンドで、ヒストグラム メトリック タイプのカウント値と合計値のみを含むテーブルを作成し、更新ポリシーをアタッチします。 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

関連コンテンツ