Azure Cosmos DB SDK 가시성
적용 대상: 
NoSQL
Azure Cosmos DB .NET 및 Java SDK는 애플리케이션을 모니터링하는 데 도움이 되는 분산 추적을 지원합니다. 요청 흐름을 추적하면 디버깅, 대기 시간,업 성능 분석 및 진단 수집에 유용합니다. 공급업체 중립적이며 선택한 내보내기와 관계없이 표준화된 데이터 형식을 보장하거나 Application Insights SDK 또는 Azure Monitor OpenTelemetry Distro를 사용하는 의미 체계 규칙 세트가 있는 OpenTelemetry를 사용하여 애플리케이션에 대한 추적을 계측합니다.
시작하기
분산 추적은 다음 SDK에서 사용할 수 있습니다.
| SDK | 지원되는 버전 | 주의 |
|---|---|---|
| .NET v3 SDK | >= 3.36.0 |
이 기능은 미리 보기 버전과 비 미리 보기 버전 모두에서 사용할 수 있습니다. 미리 보기가 아닌 버전의 경우 기본적으로 꺼져 있습니다. 에서 설정 DisableDistributedTracing = false 하여 추적을 사용하도록 설정할 수 있습니다 CosmosClientOptions.CosmosClientTelemetryOptions. |
| .NET v3 SDK 미리 보기 | >= 3.33.0-preview |
이 기능은 미리 보기 버전과 비 미리 보기 버전 모두에서 사용할 수 있습니다. 미리 보기 버전의 경우 기본적으로 설정됩니다. CosmosClientOptions.CosmosClientTelemetryOptions에서 DisableDistributedTracing = true를 설정하여 추적을 사용하지 않도록 설정할 수 있습니다. |
| Java v4 SDK | >= 4.43.0 |
추적 특성
Azure Cosmos DB 추적은 OpenTelemetry 데이터베이스 사양을 따르며 몇 가지 사용자 지정 특성도 제공합니다. 요청 작업에 따라 다른 특성을 볼 수 있으며 이러한 특성은 모든 요청에 대한 핵심 특성입니다.
| 특성 | Type | 설명 |
|---|---|---|
net.peer.name |
string | Azure Cosmos DB 호스트 이름. |
db.name |
string | Azure Cosmos DB 데이터베이스 이름. |
db.system |
string | 데이터베이스 서비스의 식별자입니다. 모든 요청에 대해 cosmosdb입니다. |
db.operation |
string | 작업 이름(예: CreateItemAsync. |
db.cosmosdb.container |
string | Azure Cosmos DB 컨테이너 이름. |
db.cosmosdb.client_id |
string | 고유한 클라이언트 인스턴스를 나타내는 식별자입니다. |
db.cosmosdb.operation_type |
string | 작업 유형(예: Create. |
db.cosmosdb.connection_mode |
string | 클라이언트 연결 모드. direct 또는 gateway 중 하나입니다. |
db.cosmosdb.status_code |
int | 요청에 대한 상태 코드입니다. |
db.cosmosdb.sub_status_code |
int | 요청에 대한 하위 상태 코드입니다. |
db.cosmosdb.request_charge |
double | 작업에 사용된 RU입니다. |
db.cosmosdb.regions_contacted |
string | Azure Cosmos DB 계정에 연결된 지역 목록입니다. |
user_agent.original |
string | Azure Cosmos DB SDK에서 생성된 전체 사용자 에이전트 문자열입니다. |
진단 수집
추적 공급자에서 로그를 구성한 경우 실패했거나 대기 시간이 긴 Azure Cosmos DB 요청에 대한 진단을 자동으로 받을 수 있습니다. 이러한 로그는 사용자 지정 코드를 캡처할 필요 없이 실패한 요청과 느린 요청을 진단하는 데 도움이 될 수 있습니다.
실패한 요청에 대한 진단 로그를 가져오는 것 외에도 성공적인 요청에서 진단을 수집할 시기에 대해 다른 대기 시간 임계값을 구성할 수 있습니다. 기본값은 지점 작업의 경우 100ms, 지점이 아닌 작업의 경우 500ms입니다. 이러한 임계값은 클라이언트 옵션을 통해 조정할 수 있습니다.
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
수신하는 진단 로그를 제어하도록 로그 수준을 구성할 수 있습니다.
| 로그 수준 | 설명 |
|---|---|
| 오류 | 오류에 대해서만 기록합니다. |
| Warning | 구성된 임계값을 기반으로 오류 및 높은 대기 시간 요청에 대한 로그입니다. |
| 정보 | 특정 정보 수준 로그가 없습니다. 이 수준의 로그는 경고를 사용하는 것과 동일합니다. |
애플리케이션 환경에 따라 로그 수준을 구성하는 다양한 방법이 있습니다. 다음은 appSettings.json의 샘플 구성입니다.
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
OpenTelemetry 구성
Azure Cosmos DB SDK에서 OpenTelemetry를 사용하려면 추적 공급자에 Azure.Cosmos.Operation 원본을 추가합니다. OpenTelemetry는 데이터를 수집할 수 있는 많은 내보내기와 호환됩니다. 다음 샘플에서는 Azure Monitor OpenTelemetry Exporter를 사용하지만 원하는 내보내기를 구성하도록 선택할 수 있습니다. 선택한 내보내기자에 따라 최대 몇 분의 데이터 수집이 지연될 수 있습니다.
팁
Azure.Monitor.OpenTelemetry.Exporter 패키지를 사용하는 경우 버전 >= 1.0.0-beta.11을 사용하고 있는지 확인합니다.
ASP.NET Core 및 Azure Monitor를 사용하는 경우 대신 Azure Monitor OpenTelemetry Distro를 사용하는 것이 좋습니다.
이 샘플에서는 .NET 콘솔 앱에 대해 OpenTelemetry를 구성하는 방법을 보여줍니다. GitHub에서 전체 샘플을 참조하세요.
ResourceBuilder resource = ResourceBuilder.CreateDefault().AddService(
serviceName: serviceName,
serviceVersion: "1.0.0");
// Set up logging to forward logs to chosen exporter
using ILoggerFactory loggerFactory
= LoggerFactory.Create(builder => builder
.AddConfiguration(configuration.GetSection("Logging"))
.AddOpenTelemetry(options =>
{
options.IncludeFormattedMessage = true;
options.SetResourceBuilder(resource);
options.AddAzureMonitorLogExporter(o => o.ConnectionString = aiConnectionString); // Set up exporter of your choice
}));
/*.AddFilter(level => level == LogLevel.Error) // Filter is irrespective of event type or event name*/
AzureEventSourceLogForwarder logforwader = new AzureEventSourceLogForwarder(loggerFactory);
logforwader.Start();
// Configure OpenTelemetry trace provider
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
_traceProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("Azure.Cosmos.Operation", // Cosmos DB source for operation level telemetry
"Sample.Application")
.AddAzureMonitorTraceExporter(o => o.ConnectionString = aiConnectionString) // Set up exporter of your choice
.AddHttpClientInstrumentation() // Added to capture HTTP telemetry
.SetResourceBuilder(resource)
.Build();
Application Insights SDK 구성
애플리케이션이 작성된 언어와 컴퓨팅 환경에 따라 Application Insights를 구성하는 방법에는 여러 가지가 있습니다. 자세한 내용은 Application Insights 설명서를 참조하세요. Application Insights로 데이터를 수집하는 데 최대 몇 분이 걸릴 수 있습니다.
참고 항목
대상 .NET 환경에 Application Insights 패키지의 버전 >= 2.22.0-beta2를 사용합니다.
다음 샘플에서는 .NET 콘솔 앱에 대해 Application Insights를 구성하는 방법을 보여 줍니다. GitHub에서 전체 샘플을 참조하세요.
IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);
IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
추적 데이터가 Application Insights로 수집되면 Azure Portal에서 시각화하여 애플리케이션의 요청 흐름을 이해할 수 있습니다. 다음은 Azure Portal의 왼쪽 탐색에 있는 트랜잭션 검색에서 파티션 간 쿼리의 추적 데이터 예입니다.
