OpenTelemetry とアクティビティ トレースを使用する

データ API ビルダー (DAB) では、分散トレースとメトリックの OpenTelemetry がサポートされており、REST、GraphQL、データベース操作、および内部ミドルウェア全体の動作を監視および診断できます。

[前提条件]

• 既存の DAB 構成ファイル。
• OpenTelemetry コレクターまたはバックエンド (Azure Monitor や Jaeger など) の実行。
• データ API ビルダー CLI。 CLI をインストールする

ツールを実行

dab add-telemetryを使用して、OpenTelemetry 設定を構成に追加します。

1. 構成ファイルがあることを確認します。 作成する必要がある場合は、次を実行します。

   dab init \
       --database-type mssql \
       --connection-string "<sql-connection-string>"
   

2. 構成ファイルに OpenTelemetry 設定を追加します。

   バッシュ

   dab add-telemetry \
       -c dab-config.json \
       --otel-enabled true \
       --otel-endpoint "http://localhost:4317" \
       --otel-protocol "grpc" \
       --otel-service-name "dab"
   

   コマンド プロンプト

   dab add-telemetry ^
       -c dab-config.json ^
       --otel-enabled true ^
       --otel-endpoint "http://localhost:4317" ^
       --otel-protocol "grpc" ^
       --otel-service-name "dab"
   

3. DAB を起動します。

   dab start
   

テレメトリ バックエンドでテストする

1. OpenTelemetry バックエンドまたはコレクター UI を開きます。

2. REST、GraphQL、またはデータベース呼び出しのトレースとメトリックが到着していることを確認します。

注

.NET アスパイア ダッシュボードは、開発者ループの理想的な部分です。 これには、OpenTelemetry トレースとメトリックの組み込みビューが含まれています。

データ API ビルダーのトレース

DAB は、次の目的で OpenTelemetry の "アクティビティ" を作成します。

• 受信 HTTP 要求 (REST エンドポイント)
• GraphQL の操作
• データベース クエリ (エンティティごと)
• 内部ミドルウェアの手順 (要求処理、エラー追跡など)

各アクティビティには、次のような詳細なタグ (メタデータ) が含まれています。

• http.method、 http.url、 http.querystring、 status.code
• action.type (CRUD、GraphQL 操作)
• user.role、user-agent
• data-source.type、data-source.name
• api.type (REST または GraphQL)

エラーと例外も詳細情報と共にトレースされます。

データ API ビルダーのメトリック

DAB は、次のような OpenTelemetry メトリックを出力します。

• 要求の合計数: HTTP メソッド、状態、エンドポイント、API の種類でラベル付けされたカウンター。
• エラー: エラーの種類、HTTP メソッド、状態、エンドポイント、API の種類でラベル付けされたカウンター。
• 要求期間: HTTP メソッド、状態、エンドポイント、API の種類でラベル付けされたヒストグラム (ミリ秒)。
• アクティブな要求: 同時要求のアップ/ダウン カウンター。

メトリックでは、.NET Meter API と OpenTelemetry SDK が使用されます。

Configuration

構成ファイルの open-telemetry の下に runtime.telemetry セクションを追加します。

{
    "runtime": {
        "telemetry": {
            "open-telemetry": {
                "enabled": true,
                "endpoint": "http://otel-collector:4317",
                "service-name": "dab",
                "exporter-protocol": "grpc"
            }
        }
    }
}

Command-line

dab add-telemetryを使用して OpenTelemetry を構成します。

• --otel-enabled
• --otel-endpoint
• --otel-protocol
• --otel-service-name
• --otel-headers

Example

バッシュ

dab add-telemetry \
    -c dab-config.json \
    --otel-enabled true \
    --otel-endpoint "http://localhost:4317" \
    --otel-protocol "grpc" \
    --otel-service-name "dab"

コマンド プロンプト

dab add-telemetry ^
    -c dab-config.json ^
    --otel-enabled true ^
    --otel-endpoint "http://localhost:4317" ^
    --otel-protocol "grpc" ^
    --otel-service-name "dab"

結果の構成

注

openTelemetry オプションは、 dab configureでは使用できません。

{
    "runtime": {
        "telemetry": {
            "open-telemetry": {
                "enabled": true,
                "endpoint": "http://localhost:4317",
                "service-name": "dab",
                "exporter-protocol": "grpc"
            }
        }
    }
}

エクスポートと視覚化

テレメトリは、.NET OpenTelemetry SDK を介して、Azure Monitor や Jaeger などの構成済みのバックエンドにエクスポートされます。 指定されたendpointでバックエンドが実行中であり、アクセス可能であることを確認してください。 視覚化には、OpenTelemetry 互換のバックエンドを使用できます。

OpenTelemetry SDK はエクスポートのタイミングを制御します。 アクティビティが完了するとトレースがエクスポートされます。 SDK によって構成された定期的な間隔でメトリックがエクスポートされます。 間隔を設定しない場合、SDK はその既定値を使用します。

注

短時間でシャットダウンするエフェメラル コンテナーは、エクスポートが完了する前に終了できます。 円滑なシャットダウンのための時間を許可し、積極的な終了を回避して保留中のテレメトリをフラッシュできるようにします。

実装に関するメモ

• トレースとメトリックは、REST、GraphQL、およびデータベースのすべての操作に対応しています
• ミドルウェアとエラー ハンドラーもテレメトリを出力する
• 要求を介してコンテキストが伝達される

関連コンテンツ

• ランタイム構成
• Azure Application Insights を使用する