OpenTelemetry를 사용한 추적 작업

개요

이 가이드 에서는 .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 시맨틱 규칙을 따르는 범위 속성으로 예외 세부 정보를 기록하고 범위 상태를 Error로 설정합니다.

MongoDB 명령 실패의 경우, 운전자 작업 범위와 해당 명령 범위의 상태를 모두 Error로 설정합니다. 운전자 명령 범위의 db.response.status_code 속성에 오류 코드를 기록합니다.

중복 키 오류와 같이 서버 성공적인 명령 응답에서 반환하는 쓰기 오류는 db.response.status_code을 설정하다 하지 않습니다. 운전자 이러한 오류를 작업 범위의 예외 속성으로 기록합니다.

오류로 인해 드라이버 애플리케이션 에 예외를 발생시키는 것은 아닙니다.

성능 고려 사항

OpenTelemetry 추적을 사용할 때 다음과 같은 성능 영향을 고려하세요.

• db.query.text 속성을 캡처하면 오버헤드 추가됩니다. 필요한 경우에만 명령 텍스트를 캡처하거나 QueryTextMaxLength을 0로 설정하다 비활성화합니다.

• 드라이버의 ActivitySource을(를) 구독하는 리스너가 없는 경우, 운전자 모든 추적 작업을 건너뛰기 때문에 추적이 성능에 미치는 영향 미미합니다.

추가 정보

OpenTelemetry 추적에 대해 자세히 학습 OpenTelemetry .NET 설명서를 참조하세요.