OpenTelemetry による操作の追跡

Overview

このガイドでは、 .NET/ C#ドライバーで OpenTelemetry トレースを使用する方法を学習できます。 OpenTelemetry は、テレメトリ データの測定、生成、収集、エクスポートを行う標準化された方法を提供するオープンソースの可視性フレームワークです。

.NET/ C#ドライバーは、 System.Diagnostics.ActivitySource APIを通じてトレース データを出力します。ドライバーのActivitySource にリスナーをサブスクライブすると、ドライバーはクエリやトランザクションなどのMongoDB操作を表す範囲を作成します。これらの範囲には、OpenTelemetry のセマンティック 規則 に従う属性が含まれます。

var connectionString = "<connection string>";
var client = new MongoClient(connectionString);
var collection = client.GetDatabase("sample_mflix").GetCollection<BsonDocument>("movies");

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.InMemory

OpenTelemetry トレースの有効化

ドライバーは、リスナーがドライバーの ActivitySource にサブスクライブし、クライアントでトレースが有効になっている場合に範囲を作成します。クライアントのトレースを無効にするには、TracingOptions.Disabledプロパティを true に設定します。

リスナーがサブスクライブされていない場合、ドライバーはすべてのトレース作業をスキップするため、パフォーマンスへの影響は無視できます。

ドライバーは、MongoDB.Driver という名前の ActivitySource に範囲を登録します。ドライバーのスパンを収集するには、OpenTelemetry を構成するときに MongoTelemetry.ActivitySourceName 定数を AddSource() メソッドに渡します。

dotnet add package OpenTelemetry.Extensions.Hosting

// Register the driver's ActivitySource with an OpenTelemetry
// TracerProvider in a generic host.
var exportedSpans = new List<Activity>();
var builder = Host.CreateApplicationBuilder();
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource(MongoTelemetry.ActivitySourceName)
        .AddInMemoryExporter(exportedSpans));
var host = builder.Build();

// Register the driver's ActivitySource with an OpenTelemetry
// TracerProvider.
var exportedSpans = new List<Activity>();
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(MongoTelemetry.ActivitySourceName)
    .AddInMemoryExporter(exportedSpans)
    .Build();

var filter = Builders<BsonDocument>.Filter.Eq("title", "Back to the Future");
var movie = collection.Find(filter).First();

{ "name" : "find sample_mflix.movies", "kind" : "operation" }
{ "name" : "find", "kind" : "command" }

// Subscribe to the driver's ActivitySource by using an ActivityListener.
// This approach avoids a dependency on the OpenTelemetry SDK.
var exportedSpans = new List<Activity>();
using var listener = new ActivityListener
{
    ShouldListenTo = source => source.Name == MongoTelemetry.ActivitySourceName,
    Sample = (ref ActivityCreationOptions<ActivityContext> _) =>
        ActivitySamplingResult.AllDataAndRecorded,
    ActivityStopped = exportedSpans.Add
};
ActivitySource.AddActivityListener(listener);

トレース オプションの構成

個々のクライアントのトレース機能を設定するには、MongoClientSettings.TracingOptionsプロパティを TracingOptionsインスタンスに設定します。 TracingOptionsクラスには次のプロパティがあります。

次の例では、QueryTextMaxLength を 1024 に設定します。これにより、コマンドテキストが最大 1024 文字でキャプチャされます。

var settings = MongoClientSettings.FromConnectionString(connectionString);
settings.TracingOptions = new TracingOptions
{
    Disabled = false,
    QueryTextMaxLength = 1024
};
var client = new MongoClient(settings);

操作トレース

.NET/ C#ドライバーは次のタイプの範囲を作成します。

例、find操作では、次の階層に示すように、ネストされたコマンドレベルの範囲を含む操作レベルの範囲が作成されます。

find sample_mflix.movies
  └── find

セキュリティと編集

ドライバーは機密情報を保護するために、次のセキュリティ対策を適用します。

• ドライバーは、認証コマンドなどの機密性の高いコマンドの範囲を作成しません。これらのコマンドには、authenticate、saslStart、saslContinue、getNonce、createUser、updateUser、copyDbSaslStart、copyDb が含まれます。ドライバーは、speculativeAuthenticateフィールドが含まれている場合は hello コマンドもスキップします。

• ドライバーはデフォルトで db.query.text 属性を無効にします。この属性は必要な場合にのみ有効にしてください。

• ドライバーがクエリテキストをキャプチャすると、コマンドから lsid、$db、$clusterTime、signature フィールドが削除されます。

Error Handling

操作が失敗すると、ドライバーは例外の詳細を OpenTelemetry セマンティック規則に準拠する span 属性として記録し、 span ステータスを Error に設定します。

MongoDBコマンドが失敗した場合、ドライバーは操作範囲とそのコマンド範囲の両方のステータスを Error に設定します。ドライバーは、コマンド span の db.response.status_code 属性にエラー コードを記録します。

重複キー エラーなど、サーバーが正常なコマンド応答で返す書き込みエラーは、db.response.status_code を設定しないでください。ドライバーはこれらのエラーを操作範囲の例外属性として記録します。

エラーは発生しても、ドライバーはアプリケーションに対して例外を発生させることはありません。

パフォーマンスに関する考慮事項

OpenTelemetry トレースを使用する場合は、次のパフォーマンスへの影響を考慮してください。

• db.query.text 属性をキャプチャするとオーバーヘッドが増加します。必要な場合にのみコマンド テキストをキャプチャするか、QueryTextMaxLength を 0 に設定して無効にします。

• ドライバーの ActivitySource にサブスクライブされていないリスナーが ない 場合、ドライバーはすべてのトレース作業をスキップするため、トレースによるパフォーマンスへの影響は無視されます。

詳細情報

OpenTelemetry トレースの詳細については、 OpenTelemetry .NETドキュメント を参照してください。