使用 OpenTelemetry 跟踪操作

Overview

在本指南中，您可以学习；了解如何将 OpenTelemetry 跟踪与.NET/ C#驱动程序结合使用。 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 并且客户端已启用跟踪时，驾驶员会创建 span。要禁用客户端端跟踪，请将 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

安全和日志校订

驾驶员应用以下安全措施来保护敏感信息：

• 驾驶员不会为敏感命令（例如身份验证命令）创建 span。这些命令包括 authenticate、saslStart、saslContinue、getNonce、createUser、updateUser、copyDbSaslStart 和 copyDb。当 hello 命令包含 speculativeAuthenticate字段时，驾驶员也会跳过该命令。

• 驾驶员默认禁用 db.query.text 属性。仅在必要时启用此属性。

• 当驾驶员捕获查询文本时，它会从命令中删除 lsid、$db、$clusterTime 和 signature 字段。

Error Handling

当操作失败时，驾驶员会将异常详细信息记录为遵循 OpenTelemetry 语义约定的 span 属性，并将 span 状态设置为 Error。

对于MongoDB命令失败，驾驶员会将操作范围及其命令范围的状态设置为 Error。驾驶员会在命令范围的 db.response.status_code 属性中记录错误代码。

服务器在成功的命令响应中返回的写入错误（例如重复键错误）不会设立db.response.status_code。驾驶员会将这些错误记录为操作范围的异常属性。

错误不会阻止驱动程序向应用程序引发异常。

性能考虑因素

使用 OpenTelemetry 跟踪时，请考虑以下性能影响：

• 捕获 db.query.text 属性会增加开销。仅在必要时捕获命令文本，或将 QueryTextMaxLength设立为 0 以将其禁用。

• 当没有侦听器订阅驱动程序的 ActivitySource 时，跟踪对性能的影响可以忽略不计，因为驾驶员会跳过所有跟踪工作。

更多信息

要学习；了解有关 OpenTelemetry 跟踪的更多信息，请参阅 OpenTelemetry .NET文档。