OpenTelemetry

最新のコンピューティングでは、マイクロサービスやサーバーレス・アプリケーションなど、より多くの分散システム・スケールとサービスが追加されています。この成長に伴い、システム全体のサービスの所有権は、様々な個人または組織に割り当てられます。統合された可観測性フレームワークがなくては、これらのサービスが相互にどのように依存し、他のサービスに影響を与えるかを観察することはますます困難です。これは、デプロイメント後または停止中に、問題を識別するのに速度と正確性が必要な場合に明確になります。

OpenTelemetryは、統合された可観測性フレームワークです。これは、テレメトリ・データをインスツルメント、生成、収集およびエクスポートするための一般的なオープン・ソースの可観測性フレームワークです。複数のサービスがトレース、メトリックおよびログの統合バージョンを提供できるように、共通の仕様とプロトコルを提供します。OpenTelemetryは、インスツルメントされる可観測性モデルに参加するコンポーネントに依存します。つまり、コードはトレース、メトリックおよびログを発行します。

OpenTelemetryの可観測性と標準をサポートするために、多数の管理対象ODP.NETおよびODP.NET Core APIがインスツルメントされています。開発者およびオペレータは、収集されたODP.NETメトリックをカスタマイズできます。

ODP.NET OpenTelemetryでは、NuGetギャラリから入手できるOracle.ManagedDataAccess.OpenTelemetryパッケージが必要です。

ODP.NET OpenTelemetryトレース

トレースでは、マルチサービス・アーキテクチャを介した伝播時にアプリケーションまたはエンド・ユーザーが実行したリクエスト・パスが記録されます。OpenTelemetryのトレースは、そのスパン別に暗黙的に定義されます。トレースは、スパン間のエッジが親子関係として定義されるスパンの有向非巡回グラフと考えることができます。

スパン(アクティビティ)は、トランザクション内の操作を表します。各スパンは次の状態をカプセル化します。

表示名
開始タイムスタンプと期間
属性 - キーと値のペアのリスト
イベント - タプル(タイムスタンプ、名前、属性)で、ゼロ以上から番号付けが可能です
親スパン識別子
SpanContextを介した因果関係があるスパンへのリンク(ゼロ以上からの番号付けが可能)

アプリケーションがODP.NETのインスツルメントされたAPIをコールする前に(親)スパンを作成した場合、ODP.NETのスパンは子スパンになります。

ODP.NET OpenTelemetryは、次のアクティビティ・タグまたは属性を公開します。

表3-39 ODP.NET OpenTelemetryのアクティビティ・タグ

属性名	説明
`db.system`	データベース名。`Oracle`は、Oracleデータベースの属性値です。
`db.name`	コマンドによってアクセスされているデータベース。属性値は、`OracleConnection` `DatabaseName`プロパティと同じです。
`db.connection_string`	データベース接続文字列
`db.user`	データベース・ユーザー
`db.statement`	実行されるデータベース文
`otel.status_description`	トレースのステータス説明
`otel.status_code`	トレースのステータス・コード
`exception.stacktrace`	例外スタック・トレース
`exception.type`	例外タイプ
`exception.message`	例外メッセージ
`Activity.DisplayName`	アクティビティの表示名、またはインスツルメントされる操作の名前。

ODP.NET OpenTelemetryトレース・サンプル・エクスポータの視覚化:


Activity.TraceId:          8e6cf249680bf5ff371fc40cadcf881a
Activity.SpanId:           905ff6cba6df8e40
Activity.TraceFlags:           Recorded
Activity.ParentSpanId:    8be3adde4e655141
Activity.ActivitySourceName: ODPNET
Activity.DisplayName: SendExecuteRequest
Activity.Kind:        Client
Activity.StartTime:   2023-06-02T11:39:01.1957498Z
Activity.Duration:    00:00:00.1150490
Activity.Tags:
    db.system: oracle
   StatusCode : OK
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 48bce79b-eff8-45ff-9695-f08680a4ad09

Activity.TraceId:          8e6cf249680bf5ff371fc40cadcf881a
Activity.SpanId:           8be3adde4e655141
Activity.TraceFlags:           Recorded
Activity.ParentSpanId:    d97ef0e4f76807b9
Activity.ActivitySourceName: ODPNET
Activity.DisplayName: ExecuteNonQueryAsync
Activity.Kind:        Client
Activity.StartTime:   2023-06-02T11:39:00.8283807Z
Activity.Duration:    00:00:00.5442408
Activity.Tags:
    db.system: oracle
   StatusCode : OK
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 48bce79b-eff8-45ff-9695-f08680a4ad09

Activity.TraceId:          8e6cf249680bf5ff371fc40cadcf881a
Activity.SpanId:           d97ef0e4f76807b9
Activity.TraceFlags:           Recorded
Activity.ActivitySourceName: Test
Activity.DisplayName: MoneyTransfer
Activity.Kind:        Internal
Activity.StartTime:   2023-06-02T11:38:58.1482674Z
Activity.Duration:    00:00:03.2805191
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 48bce79b-eff8-45ff-9695-f08680a4ad09

使用方法

ODP.NET OpenTelemetryでは、トレースを視覚化および分析するために、JaegerやZipkinなどのエクスポータが必要です。これらのエクスポータはNuGetパッケージとして使用でき、NuGet依存関係としてOpenTelemetry SDKも含まれます。

ODP.Net OpenTelemetryのNuGetパッケージがインストールされると、アプリケーションの起動時にTracerProviderBuilder AddOracleDataProviderInstrumentation拡張メソッドを呼び出して、ODP.NET OpenTelemetryが有効になります。OpenTelemetryインスツルメンテーションを構成するための様々なオプションを受け入れます。

コード・サンプル: デフォルトのオプションを使用したODP.NET OpenTelemetryインスツルメンテーションの有効化

using OpenTelemetry.Trace;

Sdk.CreateTracerProviderBuilder()
.AddOracleDataProviderInstrumentation()  // ODP.NET extension method 
.AddConsoleExporter()
.Build();

コード・サンプル: すべてのオプションを有効にしたODP.NET OpenTelemetryインスツルメンテーションの有効化

using OpenTelemetry.Trace;

Sdk.CreateTracerProviderBuilder()
.AddOracleDataProviderInstrumentation(o =>
        {
          o.EnableConnectionLevelAttributes = true;
          o.RecordException = true;
          o.InstrumentOracleDataReaderRead = true;
          o.SetDbStatementForText = true;
        })
.AddConsoleExporter()
.Build();

ODP.NET OpenTelemetryを有効にすると、プロバイダでインスツルメントされたAPIがコールされるたびに、OpenTelemetryトレースが生成され、構成されたエクスポータに送信されます。

デフォルトでは、SQL文など、機密性の高いデータのインスツルメンテーションは無効になっています。

OpenTelemetryをサポートするためにインスツルメントされる管理対象ODP.NETおよびODP.NET Core APIのリストは次のとおりです。これらのAPIの1つから発生したすべてのODP.NETデータベース・ラウンド・トリップもインスツルメントされます。

OracleCommand
- ExecuteNonQuery()
- ExecuteNonQueryAsync(CancellationToken cancellationToken)
- ExecuteNonQueryAsync()
- すべてのExecuteReaderオーバーロード
- すべてのExecuteReaderAsyncオーバーロード
- ExecuteScalar()
- ExecuteScalarAsync(CancellationToken cancellationToken)
- ExecuteStream()
- ExecuteToStream(Stream)
- ExecuteXmlReader()
- すべてのExecuteXmlReaderAsyncオーバーロード
OracleDataAdapter
- すべてのFillオーバーロード
OracleDataReader
- Read()
- ReadAsync()

OpenTelemetryには、次の追加要件が含まれます。

インスツルメンテーション視覚化に使用される、コンソールやZipkinなどのエクスポータのNuGetパッケージ。
OpenTelemetry SDK。エクスポータのNuGetパッケージを使用して自動的にインストールされます。