OpenTelemetry

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

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

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

ODP.NET OpenTelemetryトレース

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

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

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

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

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

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

属性名	説明
`Activity.DisplayName`	アクティビティの表示名、またはインスツルメントされる操作の名前。
`db.name`	コマンドによってアクセスされているデータベース。属性値は、`OracleConnection` `DatabaseName`プロパティと同じです。
`db.odp.connection.id`	診断目的で、各接続に一意の識別子を指定します。`OracleConnection`または`OracleCommand`で`ConnectionIdPrefix`プロパティを設定することで、この識別子にカスタム・アプリケーション生成文字列を接頭辞として指定できます。
`db.odp.rows_affected`	`ExecuteNonQuery`、`ExecuteReader`または`ExecuteScalar*`メソッドを使用する場合、SQL DML (`INSERT`、`UPDATE`および`DELETE`のみ)の影響を受ける行数。ストアド・プロシージャおよび無名PL/SQLの場合は値を返しません。
`db.odp.sql_id`	OracleデータベースのSQL文の識別子の値(`SQL_ID`と同等)
`db.odp.user.statement`	ストアド・プロシージャやXMLコマンドの場合など、実行されているデータベース文とは異なる、ユーザー指定のODP.NETコマンド・テキストがリダクションされました。
`db.statement`	実行されるデータベース文がリダクションされました
`db.system`	データベース名。`Oracle`は、Oracleデータベースの属性値です。
`db.user`	データベース・ユーザー
`exception.message`	例外メッセージ
`exception.stacktrace`	例外スタック・トレース
`exception.type`	例外タイプ
`otel.status_code`	トレースのステータス・コード
`otel.status_description`	トレースのステータス説明
`server.address`	データベース・ホストの名前
`server.port`	サーバーのポート番号

ODP.NET OpenTelemetryトレース・サンプル・エクスポータのビジュアライゼーション:


Activity.TraceId:            29399ee7598dea88defd7c5421bc41d4
Activity.SpanId:             e1878b5fc4435f23
Activity.TraceFlags:         Recorded
Activity.ParentSpanId:       8487a50b9ace7808
Activity.ActivitySourceName: Oracle.ManagedDataAccess.Core
Activity.ActivitySourceVersion: 23.6.0
Activity.DisplayName:        Connect MYHOSTNAME:1521:dbview
Activity.Kind:               Client
Activity.StartTime:          2024-09-19T07:26:16.4615973Z
Activity.Duration:           00:00:00.4114888
Activity.Tags:
    db.system: oracle
    db.user: scott
    db.name: dbview
    server.address: MYHOSTNAME
    server.port: 1521
StatusCode: Ok
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 312ec47d-c0a1-4df3-b59f-f38aa225c39d
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.9.0

Activity.TraceId:            29399ee7598dea88defd7c5421bc41d4
Activity.SpanId:             8487a50b9ace7808
Activity.TraceFlags:         Recorded
Activity.ParentSpanId:       95b69d7844ae0dd3
Activity.ActivitySourceName: Oracle.ManagedDataAccess.Core
Activity.ActivitySourceVersion: 23.6.0
Activity.DisplayName:        Open MYHOSTNAME:1521:dbview
Activity.Kind:               Client
Activity.StartTime:          2024-09-19T07:26:16.3584252Z
Activity.Duration:           00:00:00.5781012
Activity.Tags:
    db.system: oracle
    db.user: scott
    db.name: dbview
    server.address: MYHOSTNAME
    server.port: 1521
StatusCode: Ok
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 312ec47d-c0a1-4df3-b59f-f38aa225c39d
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.9.0

Activity.TraceId:            29399ee7598dea88defd7c5421bc41d4
Activity.SpanId:             89b3cd0b7b2d2f35
Activity.TraceFlags:         Recorded
Activity.ParentSpanId:       e0cf4916dc1e4328
Activity.ActivitySourceName: Oracle.ManagedDataAccess.Core
Activity.ActivitySourceVersion: 23.6.0
Activity.DisplayName:        SendExecuteRequest MYHOSTNAME:1521:dbview
Activity.Kind:               Client
Activity.StartTime:          2024-09-19T07:26:17.0031962Z
Activity.Duration:           00:00:00.0492725
Activity.Tags:
    db.system: oracle
    server.address: MYHOSTNAME
    server.port: 1521
    db.name: dbview
    db.user: scott
    db.statement: update Blogs set Blog_Name=? where Blog_Id=?
    db.odp.sql_id: 71jyh89d1cz9r
StatusCode: Ok
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 312ec47d-c0a1-4df3-b59f-f38aa225c39d
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.9.0

Activity.TraceId:            29399ee7598dea88defd7c5421bc41d4
Activity.SpanId:             e0cf4916dc1e4328
Activity.TraceFlags:         Recorded
Activity.ParentSpanId:       95b69d7844ae0dd3
Activity.ActivitySourceName: Oracle.ManagedDataAccess.Core
Activity.ActivitySourceVersion: 23.6.0
Activity.DisplayName:        ExecuteNonQuery MYHOSTNAME:1521:dbview
Activity.Kind:               Client
Activity.StartTime:          2024-09-19T07:26:16.9671882Z
Activity.Duration:           00:00:00.1279960
Activity.Tags:
    db.system: oracle
    server.address: MYHOSTNAME
    server.port: 1521
    db.name: dbview
    db.user: scott
    db.statement: update Blogs set Blog_Name=? where Blog_Id=?
    db.odp.rows_affected: 1
    db.odp.sql_id: 71jyh89d1cz9r
StatusCode: Ok
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 312ec47d-c0a1-4df3-b59f-f38aa225c39d
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.9.0

Activity.TraceId:            29399ee7598dea88defd7c5421bc41d4
Activity.SpanId:             8d2ebac56ee5c04f
Activity.TraceFlags:         Recorded
Activity.ParentSpanId:       95b69d7844ae0dd3
Activity.ActivitySourceName: Oracle.ManagedDataAccess.Core
Activity.ActivitySourceVersion: 23.6.0
Activity.DisplayName:        Close MYHOSTNAME:1521:dbview
Activity.Kind:               Client
Activity.StartTime:          2024-09-19T07:26:17.1450407Z
Activity.Duration:           00:00:00.0144354
Activity.Tags:
    db.system: oracle
    server.address: MYHOSTNAME
    server.port: 1521
    db.name: dbview
    db.user: scott
StatusCode: Ok
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 312ec47d-c0a1-4df3-b59f-f38aa225c39d
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.9.0

Activity.TraceId:            29399ee7598dea88defd7c5421bc41d4
Activity.SpanId:             95b69d7844ae0dd3
Activity.TraceFlags:         Recorded
Activity.ActivitySourceName: Test
Activity.DisplayName:        SampleTestActivity
Activity.Kind:               Internal
Activity.StartTime:          2024-09-19T07:26:16.2164456Z
Activity.Duration:           00:00:00.9785065
Resource associated with Activity:
    service.name: DemoApp
    service.version: 1.0.0
    service.instance.id: 312ec47d-c0a1-4df3-b59f-f38aa225c39d
    telemetry.sdk.name: opentelemetry
    telemetry.sdk.language: dotnet
    telemetry.sdk.version: 1.9.0

ODP.NET OpenTelemetryは、動的インスツルメンテーションと手動インスツルメンテーションの両方をサポートします。次の項では、各インスツルメンテーション・メソッドの設定方法について説明します。

動的および手動の計測

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

ODP.NET OpenTelemetryの手動インスツルメンテーションには、次の要件があります:

NuGetギャラリから入手できるOracle.ManagedDataAccess.OpenTelemetryパッケージ。
インスツルメンテーション・ビジュアライゼーションに使用される、コンソールやZipkinなどのエクスポータのNuGetパッケージ。
OpenTelemetry SDK。エクスポータのNuGetパッケージを使用して自動的にインストールされます。

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文など、機密性の高いデータのインスツルメンテーションは無効になっています。

2つ目の手動インスツルメンテーション・メソッドでは、ODP.NET OpenTelemetry NuGetパッケージを追加せずに、AddOracleDataProviderInstrumentation()拡張メソッドをコールせずに、ODP.NET OpenTelemetryを有効にできます。これには、ODP.NET CoreにTracerProviderBuilderコールAddSource("Oracle.ManagedDataAccess.Core")、管理対象ODP.NETにAddSource("Oracle.ManagedDataAccess")を追加する必要があります。

ODP.NET OpenTelemetryインスツルメンテーションは、デフォルト・オプションを使用して有効化されます。オプション値を変更する方法がないため、デフォルトを使用する必要があります。これらの値を変更するには、ODP.NET OpenTelemetry NuGetパッケージを直接使用する必要があります。

OpenTelemetry.Api NuGetパッケージは、アプリケーションがOpenTelemetry.Exporter.ConsoleやOpenTelemetry.Exporter.ZipkinなどのOpenTelemetryエクスポータのNuGetパッケージを追加すると自動的にインストールされます。AddSource()メソッドをコールするには、OpenTelemetry.Apiが必要です。

コード・サンプル: AddSourceによるODP.NET OpenTelemetry手動インストゥルメンテーションの有効化


Sdk.CreateTracerProviderBuilder()
         .AddSource("Oracle.ManagedDataAccess.Core")
         .AddConsoleExporter()
         .Build();

このインスツルメンテーション・メソッドを使用すると、実行時にODP.NET OpenTelemetryトレースをプログラムで動的に有効化および無効化できます。有効にするには、OracleConfiguration OpenTelemetryTracingをtrue (デフォルト)に設定します。無効にするには、falseに設定します。

OpenTelemetryTracingは、管理対象のODP.NET .NET構成ファイル設定としても使用できます。.NET構成設定として、アプリケーションの起動時にのみ読み取られます。起動後のこの設定値に対する変更は無視されます。

自動計測

OpenTelemetry自動計測では、コードを変更せずにODP.NETトレースを有効にします。既存の.NETアプリケーションは、再コンパイルすることなくトレースを有効にできます。

これを使用するには、OpenTelemetry.AutoInstrumentation 1.7.0 NuGetパッケージ以降をプロジェクトに追加します。以前のバージョンのパッケージでは、ODP.NETトレースを有効にするために環境変数を設定する必要があります。たとえば、次の環境変数設定は、コンソール・エクスポータを使用したODP.NET Coreトレースを有効にします。


OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES=Oracle.ManagedDataAccess.Core
OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED=true

新しいOpenTelemetry.AutoInstrumentation NuGetパッケージを使用する場合、ODP.NET自動インスツルメンテーションがデフォルトでオンになります。

インスツルメントされたODP.NET API

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オーバーロード
OracleConnection
- Close()
- Open()
- OpenAsync()
OracleDataAdapter
- すべてのFillオーバーロード
OracleDataReader
- Read()
- ReadAsync()