Azure Cosmos DB 및 .NET에 대한 성능 팁

2025-06-16

적용 대상: NoSQL

Azure Cosmos DB는 보장된 대기 시간과 처리량 수준으로 매끄럽게 크기가 조정되는 빠르고 유연한 분산 데이터베이스입니다. Azure Cosmos DB를 사용하여 데이터베이스를 스케일링하기 위해 주요 아키텍처를 변경하거나 복잡한 코드를 작성할 필요는 없습니다. 규모를 확장 및 축소하는 방법이 API 호출을 하나 만드는 것만큼 쉽습니다. 자세한 내용은 컨테이너 처리량 프로비저닝 또는 데이터베이스 처리량 프로비저닝을 참조하세요.

네트워크 호출을 통해 Azure Cosmos DB에 액세스하기 때문에 SQL .NET SDK를 사용할 때 최대 성능을 얻기 위해 클라이언트 쪽에서 최적화 작업을 수행할 수 있습니다.

데이터베이스 성능을 개선하려는 경우 다음 섹션에 제공된 옵션을 고려합니다.

호스팅 권장 사항

서버 측 가비지 수집 활성화

경우에 따라 가비지 수집의 빈도를 줄이는 것이 도움이 될 수 있습니다. .NET에서 gcServer를 true로 설정합니다.

클라이언트 워크로드 스케일 아웃

높은 처리량 수준 또는 50,000RU/s(초당 요청 단위)보다 큰 속도로 테스트하는 경우 클라이언트 애플리케이션 때문에 워크로드 병목 상태가 발생할 수 있습니다. 머신이 CPU나 네트워크 사용률을 제한할 수 있기 때문입니다. 이 시점에 도달하면 여러 서버에 걸쳐 클라이언트 애플리케이션을 확장하여 Azure Cosmos DB 계정을 계속 추가할 수 있습니다.

참고

CPU 사용량이 많으면 대기 시간이 증가하고 요청 시간 제한 예외가 발생할 수 있습니다.

메타데이터 작업

실행 부하 과다 경로에서 및/또는 항목 작업을 수행하기 전에 Create...IfNotExistsAsync 및/또는 Read...Async를 호출하여 데이터베이스 및/또는 컨테이너가 존재하는지 확인하지 마세요. 유효성 검사는 삭제될 것으로 예상되는 경우(그렇지 않으면 필요하지 않음) 필요할 때만 애플리케이션 시작 시 수행해야 합니다. 이러한 메타데이터 작업은 추가 엔드투엔드 대기 시간을 생성하고 SLA가 없으며 데이터 작업처럼 확장되지 않는 별도의 제한이 있습니다.

로깅 및 추적

일부 환경에는 .NET DefaultTraceListener가 활성화되어 있습니다. DefaultTraceListener는 높은 CPU 및 I/O 병목 상태를 일으키는 프로덕션 환경에서 성능 문제를 야기합니다. 프로덕션 환경의 TraceListeners에서 제거하여 애플리케이션에 대해 DefaultTraceListener가 비활성화되어 있는지 확인합니다.

최신 SDK 버전(3.23.0 이상)은 이를 감지하면 자동으로 제거하고, 이전 버전에서는 다음 방법으로 제거할 수 있습니다.

.NET 6/ .NET Core
.NET Framework

if (!Debugger.IsAttached)
{
    Type defaultTrace = Type.GetType("Microsoft.Azure.Cosmos.Core.Trace.DefaultTrace,Microsoft.Azure.Cosmos.Direct");
    TraceSource traceSource = (TraceSource)defaultTrace.GetProperty("TraceSource").GetValue(null);
    traceSource.Listeners.Remove("Default");
    // Add your own trace listeners
}

app.config 또는 web.config 파일을 편집합니다.

<configuration>
  <system.diagnostics>
    <sources>
      <source name="DocDBTrace" switchName="SourceSwitch" switchType="System.Diagnostics.SourceSwitch" >
        <listeners>
          <remove name="Default" />
          <!--Add your own trace listeners-->
          <add name="myListener" ... />
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
<configuration>

고가용성

Azure Cosmos DB에서 고가용성을 구성하는 방법에 대한 일반적인 지침은 Azure Cosmos DB의 고가용성을 참조하세요.

데이터베이스 플랫폼의 좋은 기본 설정 외에도 가동 중단 시나리오에 도움이 될 수 있는 .NET SDK 자체에서 구현할 수 있는 특정 기술이 있습니다. 주목할 만한 두 가지 전략은 임계값 기반 가용성 전략과 파티션 수준 회로 차단기입니다.

임계값 기반 가용성 전략

임계값 기반 가용성 전략은 보조 지역에 병렬 읽기 요청을 보내고(정의된 ApplicationPreferredRegions대로) 가장 빠른 응답을 수락하여 비상 대기 시간 및 가용성을 향상시킬 수 있습니다. 이러한 방식을 사용하면 지역적 중단이나 장시간 대기 시간 조건이 애플리케이션 성능에 미치는 영향을 크게 줄일 수 있습니다.

예제 구성:

이 구성은 CosmosClientBuilder을 사용하여 수행할 수 있습니다.

CosmosClient client = new CosmosClientBuilder("connection string")
    .WithApplicationPreferredRegions(
        new List<string> { "East US", "East US 2", "West US" } )
    .WithAvailabilityStrategy(
        AvailabilityStrategy.CrossRegionHedgingStrategy(
        threshold: TimeSpan.FromMilliseconds(500),
        thresholdStep: TimeSpan.FromMilliseconds(100)
     ))
    .Build();

옵션을 구성하고 이를 CosmosClient에 추가합니다.

CosmosClientOptions options = new CosmosClientOptions()
{
    AvailabilityStrategy
     = AvailabilityStrategy.CrossRegionHedgingStrategy(
        threshold: TimeSpan.FromMilliseconds(500),
        thresholdStep: TimeSpan.FromMilliseconds(100)
     )
      ApplicationPreferredRegions = new List<string>() { "East US", "East US 2", "West US"},
};

CosmosClient client = new CosmosClient(
    accountEndpoint: "account endpoint",
    authKeyOrResourceToken: "auth key or resource token",
    clientOptions: options);

작동 방식:

초기 요청: 시간 T1에서 주 지역(예: 미국 동부)에 대한 읽기 요청이 수행됩니다. SDK는 최대 500밀리초(threshold 값) 동안 응답을 기다립니다.
두 번째 요청: 주 지역에서 500밀리초 내에 응답이 없으면 병렬 요청이 다음 주 지역(예: 미국 동부 2)으로 전송됩니다.
세 번째 요청: 기본 지역과 보조 지역 모두 600밀리초(500ms + 100ms, thresholdStep 값) 이내에 응답하지 않으면 SDK는 세 번째 기본 지역(예: 미국 서부)에 다른 병렬 요청을 보냅니다.
가장 빠른 응답 수락: 먼저 응답한 지역이 해당 응답을 수락하고 다른 병렬 요청은 무시됩니다.

참고

첫 번째 기본 지역에서 일시적이지 않은 오류 상태 코드(예: 문서를 찾을 수 없음, 권한 부여 오류, 충돌 등)가 반환되면 가용성 전략이 이 시나리오에서 아무런 이점이 없으므로 작업 자체가 빠르게 실패하게 됩니다.

파티션 수준 회로 차단기

PPCB(파티션 수준 회로 차단기)는 비정상 물리적 파티션을 추적하여 가용성 및 대기 시간을 향상시키는 .NET SDK의 기능입니다. 사용하도록 설정하면 요청을 더 건강한 지역으로 라우팅하여 지역 또는 파티션 관련 문제로 인한 연속 오류를 방지할 수 있습니다. 이 기능은 백 엔드 트리거 장애 조치(failover)와 독립적이며 환경 변수를 통해 제어됩니다.

이 기능은 기본적으로 사용하지 않도록 설정되지만 파티션 수준 장애 조치(failover)를 사용하도록 설정하면 자동으로 사용하도록 설정됩니다.

작동 방식

오류 검색: 또는 취소 토큰과 같은 503 Service Unavailable408 Request Timeout특정 오류가 관찰되면 SDK는 파티션에 대한 연속 오류를 계산합니다.
장애 조치(failover) 트리거: 설정된 연속 실패 횟수에 도달하면 SDK는 해당 파티션 키 범위에 대한 요청을 다음 GlobalPartitionEndpointManagerCore.TryMarkEndpointUnavailableForPartitionKeyRange 기본 설정 지역으로 리디렉션합니다.
백그라운드 복구: 네 개의 복제본 모두에 연결하여 실패한 파티션의 상태를 주기적으로 다시 평가하기 위해 장애 조치(failover) 중에 백그라운드 작업이 시작됩니다. 정상적이게 되면 SDK는 오버라이드를 제거하고 기본 지역으로 돌아갑니다.

계정 유형별 동작

단일 지역 쓰기(단일 마스터):읽기 요청만 PPCB 장애 조치(failover) 논리에 참여합니다.
다중 지역 쓰기(다중 마스터):읽기 및 쓰기 요청 모두 PPCB 장애 조치(failover) 논리를 사용합니다.

구성 옵션

다음 환경 변수를 사용하여 PPCB를 구성합니다.

환경 변수	설명	기본값
`AZURE_COSMOS_CIRCUIT_BREAKER_ENABLED`	PPCB 기능을 사용하거나 사용하지 않도록 설정합니다.	`false`
`AZURE_COSMOS_PPCB_CONSECUTIVE_FAILURE_COUNT_FOR_READS`	장애 조치(failover)를 트리거하는 연속 읽기 실패.	`10`
`AZURE_COSMOS_PPCB_CONSECUTIVE_FAILURE_COUNT_FOR_WRITES`	연속 쓰기 실패는 장애 조치를 트리거합니다.	`5`
`AZURE_COSMOS_PPCB_ALLOWED_PARTITION_UNAVAILABILITY_DURATION_IN_SECONDS`	파티션 상태를 다시 평가하기 전의 시간입니다.	`5` 초
`AZURE_COSMOS_PPCB_STALE_PARTITION_UNAVAILABILITY_REFRESH_INTERVAL_IN_SECONDS`	파티션 상태의 백그라운드 새로 고침 간격입니다.	`60` 초

참고

SDK에는 현재 읽기에 대한 신뢰할 수 있는 장애 복구 트리거가 없습니다. 대신 네 개의 복제본이 모두 응답할 때 백그라운드 상태 검사기가 원래 지역을 다시 사용하도록 점진적으로 시도합니다.

가용성 최적화 비교

임계값 기반 가용성 전략:
- 이점: 보조 지역에 병렬 읽기 요청을 전송하여 비상 대기 시간을 줄이고 네트워크 시간 초과가 발생하는 요청을 선점하여 가용성을 향상시킵니다.
- 단점: 추가적인 병렬 지역 간 요청으로 인해 회로 차단기에 비해 추가 RU(요청 단위) 비용이 발생합니다(임계값이 위반된 기간 동안에만 해당).
- 사용 사례: 대기 시간을 줄이는 것이 중요하고 추가 비용(RU 요금 및 클라이언트 CPU 압력 측면 모두)이 허용되는 읽기 중심 워크로드에 적합합니다. 멱등적(idempotent)이지 않은 쓰기 재시도 정책을 선택하고 계정에 여러 지역에 대한 쓰기가 있는 경우, 쓰기 작업도 이점을 얻을 수 있습니다.
파티션 수준 회로 차단기:
- 이점: 비정상 파티션을 방지하여 쓰기 가용성과 대기 시간을 개선하고 요청이 좀 더 양호한 지역으로 라우팅되도록 보장합니다.
- 장단점: 더 많은 RU 비용이 발생하지는 않지만 네트워크 시간 제한을 초래하는 요청에 대한 초기 가용성 손실을 허용할 수 있습니다.
- 사용 사례: 일관된 성능이 필수적인 쓰기 작업이나 혼합 워크로드에 적합하며, 특히 일시적으로 비정상 상태가 될 수 있는 파티션을 처리하는 경우에 적합합니다.

두 가지 전략 모두 읽기/쓰기 가용성을 향상하고 비상 대기 시간을 줄이는 데 사용할 수 있습니다. 파티션 수준 회로 차단기는 병렬 요청을 수행할 필요 없이, 복제본 성능 저하를 초래할 수 있는 상황을 포함하여 다양한 일시적인 오류 시나리오를 처리할 수 있습니다. 또한 임계값 기반 가용성 전략을 추가하면 추가 RU 비용이 허용되는 경우 비상 대기 시간이 최소화되고 가용성 손실이 제거됩니다.

이러한 전략을 구현하면 개발자는 지역적 중단이나 높은 대기 시간 조건에서도 애플리케이션의 복원력 및 고성능을 유지하며, 더 나은 사용자 환경을 제공할 수 있습니다.

네트워킹

연결 정책: 직접 연결 모드 사용

.NET V3 SDK 기본 연결 모드는 TCP 프로토콜과 직접 연결됩니다. CosmosClient에서 CosmosClientOptions 인스턴스를 만들 때 연결 모드를 구성합니다. 다양한 연결 옵션에 관한 자세한 정보는 연결 모드 문서를 참조하세요.

CosmosClient client = new CosmosClient(
  "<nosql-account-endpoint>",
  tokenCredential
  new CosmosClientOptions
  {
      ConnectionMode = ConnectionMode.Gateway // ConnectionMode.Direct is the default
  }
);

임시 포트 고갈

인스턴스에서 연결 볼륨이 높거나 포트 사용량이 많으면 먼저 클라이언트 인스턴스가 싱글톤인지 확인합니다. 즉, 클라이언트 인스턴스는 애플리케이션의 수명 동안 고유해야 합니다.

TCP 프로토콜에서 실행 중이면 클라이언트가 수명이 긴 연결을 사용하여 대기 시간을 최적화합니다. 2분 동안 활동이 없으면 연결을 종료하는 HTTPS 프로토콜과는 대조적입니다.

스파스 액세스 권한이 있고 게이트웨이 모드 액세스보다 연결 수가 더 많은 경우 다음을 수행할 수 있습니다.

CosmosClientOptions.PortReuseMode 속성을 PrivatePortPool로 구성합니다(프레임워크 버전 4.6.1 이상과 .NET Core 버전 2.0 이상에서 적용됨). 이 속성을 사용하면 SDK가 다양한 Azure Cosmos DB 대상 엔드포인트에 작은 임시 포트 풀을 사용할 수 있습니다.
CosmosClientOptions.IdleTcpConnectionTimeout 속성을 10분 이상으로 구성합니다. 권장값은 20분에서 24시간 사이입니다.

성능을 위해 같은 Azure 지역에 클라이언트 배치

가능한 경우 Azure Cosmos DB를 호출하는 모든 애플리케이션을 Azure Cosmos DB 데이터베이스와 같은 지역에 배치합니다. 대략 비교한다면, 같은 지역 내의 Azure Cosmos DB 호출은 1-2ms(밀리초) 내에 완료되지만, 미국 서부와 동부 해안 사이의 대기 시간은 50ms보다 큽니다. 클라이언트에서 Azure 데이터 센터 경계로 요청이 전달되는 경로에 따라 이러한 요청 간 대기 시간은 달라질 수 있습니다.

호출하는 애플리케이션이 프로비저닝된 Azure Cosmos DB 엔드포인트와 같은 Azure 지역 내에 있게 하면 대기 시간을 최대한 줄일 수 있습니다. 사용 가능한 영역 목록은 Azure 지역을 참조하세요.

같은 지역에 클라이언트 배치

스레드/작업 수 늘리기

Azure Cosmos DB 호출은 네트워크를 통해 수행되므로 클라이언트 애플리케이션이 요청 간에 대기하는 시간이 최소한이 되도록 요청의 동시 처리 수준을 다양하게 지정해야 할 수 있습니다. 예를 들어 .NET 작업 병렬 라이브러리를 사용하는 경우, Azure Cosmos DB에서 읽거나 쓰는 수백 개의 작업에 대한 순서를 생성합니다.

가속화된 네트워킹을 사용하도록 설정하여 대기 시간 및 CPU 지터 줄이기

성능을 최대화하려면 지침에 따라 Windows(지침을 보려면 클릭) 또는 Linux(지침을 보려면 클릭) Azure VM에서 가속화된 네트워킹을 사용하도록 설정하는 것이 좋습니다.

가속화된 네트워킹을 사용하지 않으면 Azure VM과 다른 Azure 리소스 간에 전송되는 IO가 VM과 해당 네트워크 카드 사이에 위치한 호스트 및 가상 스위치를 통해 불필요하게 라우팅될 수 있습니다. 데이터 경로에 호스트 및 가상 스위치를 인라인으로 두면 통신 채널의 대기 시간과 jitter가 증가할 뿐만 아니라 VM의 CPU 사이클도 도용합니다. 가속화된 네트워킹을 사용하면 VM에서 중간자 없이 NIC와 직접 상호 작용합니다. 호스트와 가상 스위치에서 처리되었던 네트워크 정책 세부 정보는 이제 NIC의 하드웨어에서 처리되며, 호스트와 가상 스위치가 무시됩니다. 일반적으로 가속화된 네트워킹을 사용하도록 설정하는 경우 대기 시간이 줄어들고 처리량이 향상될 뿐만 아니라 더 일관된 대기 시간이 유지되며 CPU 사용률이 줄어들 수도 있습니다.

제한 사항: 가속화된 네트워킹은 VM OS에서 지원되어야 하며, VM이 중지 및 할당 취소된 경우에만 사용하도록 설정할 수 있습니다. VM은 Azure Resource Manager를 사용하여 배포할 수 없습니다. App Service 가속화된 네트워크를 사용할 수 없습니다.

자세한 내용은 Windows 및 Linux 지침을 참조하세요.

SDK 사용

최신 SDK 설치

Azure Cosmos DB SDK는 최상의 성능을 제공하기 위해 지속적으로 향상됩니다. 최신 SDK를 확인하고 향상된 기능을 검토하려면 Azure Cosmos DB SDK를 참조하세요.

스트림 API 사용

.NET SDK V3에는 직렬화하지 않고 데이터를 수신하고 반환할 수 있는 스트림 API가 포함되어 있습니다.

SDK에서 직접 응답을 사용하지 않고 다른 애플리케이션 계층으로 릴레이하는 중간 계층 애플리케이션은 스트림 API의 이점을 누릴 수 있습니다. 스트림 처리의 예는 항목 관리 샘플을 참조하세요.

애플리케이션 수명 동안 싱글톤 Azure Cosmos DB 클라이언트 사용

각 CosmosClient 인스턴스는 스레드로부터 안전하고 직접 모드에서 작동하는 경우 효율적인 연결 관리와 주소 캐싱을 수행합니다. 효율적으로 연결을 관리하고 SDK 클라이언트 성능을 향상시키려면 애플리케이션이 상호 작용하는 각 계정에 대해 애플리케이션 수명 동안 AppDomain당 단일 인스턴스를 사용하는 것이 좋습니다.

여러 계정을 처리하는 다중 테넌트 애플리케이션에 대해서는 관련 모범 사례를 참조하세요.

Azure Functions에 대해 작업할 때 인스턴스는 기존 지침을 따르고 단일 인스턴스를 유지 관리해야 합니다.

차단되는 호출 방지

Azure Cosmos DB SDK는 많은 요청을 동시에 처리하도록 설계되어야 합니다. 비동기 API를 사용하면 차단 호출을 기다리지 않고 작은 스레드 풀에서 수천 개의 동시 요청을 처리할 수 있습니다. 스레드는 장기 실행 동기 작업이 완료되기를 기다리는 대신 다른 요청에서 작업할 수 있습니다.

Azure Cosmos DB SDK를 사용하는 앱의 일반적인 성능 문제는 비동기식일 수 있는 호출을 차단하는 것입니다. 많은 동기 차단 호출은 스레드 풀 결핍 및 응답 시간 저하로 이어집니다.

수행하지 않아야 할 작업:

Task.Wait 또는 Task.Result를 호출하여 비동기 실행을 차단합니다.
Task.Run을 사용하여 동기식 API를 비동기식으로 생성합니다.
공통 코드 경로에서 잠금을 획득합니다. Azure Cosmos DB .NET SDK는 코드를 병렬로 실행하도록 설계될 때 가장 성능이 좋습니다.
Task.Run을 호출하고 즉시 기다립니다. ASP.NET Core는 이미 일반 스레드 풀 스레드에서 앱 코드를 실행하므로 Task.Run을 호출하면 불필요한 스레드 풀 일정만 추가로 발생합니다. 예약된 코드가 스레드를 차단하더라도 Task.Run은 이를 방지하지 않습니다.
차단 호출을 사용하여 쿼리를 동기적으로 드레이닝하는 Container.GetItemLinqQueryable<T>()에서 ToList()를 사용하지 마세요. 쿼리를 비동기식으로 드레이닝하려면 ToFeedIterator()를 사용합니다.

실행:

Azure Cosmos DB .NET API를 비동기식으로 호출합니다.
전체 호출 스택은 비동기/대기 패턴을 활용하기 위해 비동기식입니다.

PerfView와 같은 프로파일러를 사용하여 스레드 풀에 자주 추가되는 스레드를 찾을 수 있습니다. Microsoft-Windows-DotNETRuntime/ThreadPoolWorkerThread/Start 이벤트는 스레드 풀에 추가된 스레드를 나타냅니다.

쓰기 작업에 대한 콘텐츠 응답을 사용하지 않게 설정

만들기 페이로드가 많은 워크로드의 경우 EnableContentResponseOnWrite요청 옵션을 false로 설정합니다. 서비스에서는 만들거나 업데이트된 리소스를 더는 SDK에 반환하지 않습니다. 일반적으로 애플리케이션에는 생성 중인 개체가 있으므로 서비스에서 반환하지 않아도 됩니다. 요청 요금처럼 헤더 값에 계속 액세스할 수 있습니다. 콘텐츠 응답을 사용하지 않게 설정하면 SDK에서 더는 메모리를 할당하거나 응답 본문을 직렬화할 필요가 없기 때문에 성능 향상에 도움이 될 수 있습니다. 또한 네트워크 대역폭 사용량을 줄여 성능을 개선할 수 있습니다.

ItemRequestOptions requestOptions = new ItemRequestOptions() { EnableContentResponseOnWrite = false };
ItemResponse<Book> itemResponse = await this.container.CreateItemAsync<Book>(book, new PartitionKey(book.pk), requestOptions);
// Resource will be null
itemResponse.Resource

대기 시간이 아니라 처리량을 최적화하기 위해 대량을 사용으로 설정

워크로드에 많은 양의 처리량이 필요하고 대기 시간이 그다지 중요하지 않으면 벌크를 활성화합니다. 대량 기능을 사용으로 설정하는 방법과 이 기능을 사용해야 하는 시나리오에 관한 자세한 내용은 대량 지원 소개를 참조하세요.

게이트웨이 모드를 사용할 때 호스트당 System.Net MaxConnections 늘리기

Azure Cosmos DB 요청은 게이트웨이 모드를 사용할 때 HTTPS/REST를 통해 수행됩니다. 호스트 이름이나 IP 주소당 기본 연결 한도가 적용됩니다. 클라이언트 라이브러리가 Azure Cosmos DB에 대한 다중 동시 연결을 활용할 수 있도록 MaxConnections를 더 높은 값(100-1,000)으로 설정해야 할 수도 있습니다. .NET SDK 1.8.0 이상에서 ServicePointManager.DefaultConnectionLimit의 기본값은 50입니다. 값을 변경하기 위해 Documents.Client.ConnectionPolicy.MaxConnectionLimit를 더 높은 값으로 설정할 수 있습니다.

스레드/작업 수 늘리기

이 문서의 네트워킹 섹션에서 스레드/작업 수 늘리기를 참조하세요.

쿼리 작업

쿼리 작업은 쿼리에 대한 성능 팁을 참조하세요.

인덱싱 정책

쓰기 속도를 높이기 위해 인덱싱에서 사용하지 않는 경로 제외

Azure Cosmos DB 인덱싱 정책을 통해 인덱싱 경로(IndexingPolicy.IncludedPaths 및 IndexingPolicy.ExcludedPaths)를 사용하여 인덱싱에 포함하거나 제외할 문서 경로를 지정할 수도 있습니다.

필요한 경로만 인덱싱하면 쓰기 성능이 향상되고, 쓰기 작업에 대한 RU 요금이 감소하며, 쿼리 패턴이 미리 알려진 시나리오의 인덱스 스토리지를 줄일 수 있습니다. 인덱싱 비용은 인덱싱된 고유 경로 수와 직접 상관되기 때문입니다. 예를 들어, 다음 코드는 “*” 와일드카드를 사용하여 인덱싱에서 문서의 전체 섹션(하위 트리라고도 함)을 제외하는 방법을 보여 줍니다.

var containerProperties = new ContainerProperties(id: "excludedPathCollection", partitionKeyPath: "/pk" );
containerProperties.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
containerProperties.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/nonIndexedContent/*");
Container container = await this.cosmosDatabase.CreateContainerAsync(containerProperties);

자세한 내용은 Azure Cosmos DB 인덱싱 정책을 참조하세요.

처리량

낮은 RU/s 사용량을 위한 측정 및 튜닝

Azure Cosmos DB에서는 다양한 데이터베이스 작업 세트를 제공합니다. 이러한 작업에는 UDF(사용자 정의 함수), 저장 프로시저 및 트리거가 있는 관계형 및 계층적 쿼리가 포함되며, 모두 데이터베이스 컬렉션 내의 문서에서 작동합니다.

각 작업과 관련된 비용은 작업을 완료하는 데 필요한 CPU, IO 및 메모리에 따라 달라집니다. 하드웨어 리소스를 고려하고 관리하는 대신 다양한 데이터베이스 작업을 수행하고 애플리케이션 요청을 처리하는 데 필요한 리소스의 단일 측정값으로 요청 단위를 고려할 수 있습니다.

처리량은 각 컨테이너에 설정된 요청 단위 수에 따라 프로비저닝됩니다. 요청 단위 소비는 초당 단위 비율로 평가됩니다. 해당 컨테이너에 프로비저닝된 요청 단위 비율을 초과하는 애플리케이션은 비율이 컨테이너에 프로비저닝된 수준 아래로 떨어질 때까지 제한됩니다. 애플리케이션에 더 높은 수준의 처리량이 필요한 경우 추가 요청 단위를 프로비저닝하여 처리량을 늘릴 수 있습니다.

쿼리의 복잡성은 작업에 사용되는 요청 단위의 양에 영향을 줍니다. 조건자의 수, 조건자의 특성, UDF 파일 수, 원본 데이터 세트의 크기는 모두 쿼리 작업의 비용에 영향을 줍니다.

모든 작업(만들기, 업데이트 또는 삭제)의 오버헤드를 측정하려면 x-ms-request-charge 헤더(또는 .NET SDK의 RequestCharge나 ResourceResponse<T>의 해당 FeedResponse<T> 속성)를 검사하여 작업에 사용된 요청 단위 수를 측정합니다.

// Measure the performance (Request Units) of writes
ItemResponse<Book> response = await container.CreateItemAsync<Book>(myBook, new PartitionKey(myBook.PkValue));
Console.WriteLine("Insert of item consumed {0} request units", response.RequestCharge);
// Measure the performance (Request Units) of queries
FeedIterator<Book> queryable = container.GetItemQueryIterator<ToDoActivity>(queryString);
while (queryable.HasMoreResults)
    {
        FeedResponse<Book> queryResponse = await queryable.ExecuteNextAsync<Book>();
        Console.WriteLine("Query batch consumed {0} request units", queryResponse.RequestCharge);
    }

이 헤더에서 반환된 요청 비용은 프로비저닝된 처리량(즉, 2,000RU/s)의 일부입니다. 예를 들어, 앞의 쿼리가 1,000개의 1KB 문서를 반환하는 경우 작업 비용은 1,000이 됩니다. 따라서 1초 이내에 서버는 이후 요청의 속도를 제한하기 전에 해당 두 요청만 인식합니다. 자세한 내용은 요청 단위와 요청 단위 계산기를 참조하세요.

너무 큰 속도 제한/요청 속도 처리

클라이언트가 계정에 대해 예약된 처리량을 초과하려 할 때도 서버의 성능이 저하되거나 예약된 수준 이상의 처리량이 사용되지 않습니다. 서버는 RequestRateTooLarge(HTTP 상태 코드 429)로 요청을 선제적으로 종료합니다. 요청을 다시 시도하기 전에 사용자가 기다려야 하는 시간(밀리초)을 나타내는 x-ms-retry-after-ms 헤더를 반환합니다.

    HTTP Status 429,
    Status Line: RequestRateTooLarge
    x-ms-retry-after-ms :100

SDK는 이 응답을 암시적으로 모두 catch하고, server-specified retry-after 헤더를 준수하고 요청을 다시 시도합니다. 동시에 여러 클라이언트가 계정에 액세스하지만 않으면 다음 재시도가 성공할 것입니다.

두 개 이상의 클라이언트가 요청 속도를 초과하여 누적해서 계속 작동할 경우 클라이언트가 내부적으로 현재 9로 설정한 기본 재시도 횟수가 충분하지 않을 수 있습니다. 이 경우 클라이언트는 애플리케이션에 상태 코드 429를 표시하며 CosmosException 예외 처리를 합니다.

RetryOptions 인스턴스에서 CosmosClientOptions를 설정하여 기본 재시도 횟수를 변경할 수 있습니다. 기본적으로 요청이 요청 속도를 초과하여 계속 작동하는 경우 상태 코드가 429인 CosmosException은 30초의 누적 대기 시간 후에 반환됩니다. 이 오류는 현재 값이 기본값인 9인지 아니면 사용자 정의 값인지에 상관없이 현재 재시도 횟수가 최대 재시도 횟수보다 적은 경우에도 반환됩니다.

재시도 동작을 자동화하면 대부분의 애플리케이션에 대한 복원력과 유용성을 개선할 수 있습니다. 그러나 성능 벤치마크를 수행할 때, 특히 대기 시간을 측정할 때 최상의 동작이 아닐 수 있습니다. 실험이 서버 제한에 도달하고 클라이언트 SDK를 자동으로 재시도하는 경우 클라이언트 관찰 대기 시간이 급증합니다. 성능 실험 중 대기 시간 급증을 방지하려면, 각 작업에 의해 반환된 비용을 측정하고 요청이 예약된 요청 속도 이하로 작동하고 있는지 확인합니다.

자세한 내용은 요청 단위를 참조하세요.

처리량을 높이기 위해 문서 크기를 줄이도록 설계

지정된 작업의 요청 요금(즉, 요청 처리 비용)은 문서의 크기와 직접 상관됩니다. 큰 문서에서 작업하는 경우 작은 문서 작업보다 비용이 많이 듭니다.

다음 단계

몇 개의 클라이언트 컴퓨터에서 고성능 시나리오에 대한 Azure Cosmos DB를 평가하는 데 사용된 애플리케이션 예제는 Azure Cosmos DB를 사용한 성능 및 스케일 테스트를 참조하세요.

확장성 및 고성능을 위한 애플리케이션 설계 방법에 대한 자세한 내용은 Azure Cosmos DB의 분할 및 크기 조정을 참조하세요.