Azure Cosmos DB Java SDK에 대한 모범 사례

  • 아티클

적용 대상: NoSQL

이 문서에서는 Azure Cosmos DB Java SDK 사용을 위한 모범 사례를 살펴봅니다. 이러한 연습을 수행하면 대기 시간, 가용성 및 전반적인 성능을 향상시킬 수 있습니다.

검사 목록

선택 항목 세부 정보/링크
SDK 버전 항상 최신 버전의 Azure Cosmos DB SDK를 사용하여 최적의 성능을 제공합니다.
싱글톤 클라이언트 애플리케이션의 수명에 대한 CosmosClient의 단일 인스턴스를 사용하여 성능을 향상합니다.
지역 대기 시간을 줄이기 위해 가능한 경우, Azure Cosmos DB 계정과 동일한 Azure 지역에서 애플리케이션을 실행해야 합니다. 2~4개의 지역을 사용하도록 설정하고 최상의 가용성을 위해 여러 지역에서 계정을 복제합니다. 프로덕션 작업의 경우 서비스 관리형 장애 조치(failover)를 사용하도록 설정합니다. 이 구성이 없는 경우, 지역 연결이 부족하여 수동 장애 조치(failover)가 성공하지 않으므로 계정의 쓰기 지역 가동 중단 시간에 대한 쓰기 가용성이 손실됩니다. Java SDK를 사용하여 여러 지역을 추가하는 방법에 대한 자세한 내용은 여기를 방문하세요.
가용성 및 장애 조치(failover) v4 SDK에서 preferredRegions를 설정합니다. 장애 조치(failover) 중에는 쓰기 작업이 현재 쓰기 지역으로 전송되고 모든 읽기가 기본 지역 목록 내의 첫 번째 지역으로 전송됩니다. 지역 장애 조치(failover) 메커니즘에 대한 자세한 내용은 가용성 문제 해결 가이드를 참조하세요.
CPU 클라이언트 컴퓨터에 리소스가 부족하여 연결/가용성 문제가 발생할 수 있습니다. Azure Cosmos DB 클라이언트를 실행하는 노드에서 CPU 사용률을 모니터링하고 사용량이 매우 높은 경우 스케일 업/아웃합니다.
호스팅 프로덕션 워크로드의 가장 일반적인 경우 가능할 때마다 최소 4코어 및 8GB 메모리 VM을 사용하는 것이 좋습니다.
연결 모드 최상의 성능을 위해 직접 모드를 사용합니다. 이 작업을 수행하는 방법에 대한 지침은 V4 SDK 설명서를 참조하세요.
네트워킹 가상 머신을 사용하여 애플리케이션을 실행하는 경우 VM에서 가속화된 네트워킹을 사용하도록 설정하여 높은 트래픽으로 인한 병목 상태를 지원하고 대기 시간 또는 CPU 지터를 줄입니다. 최대 CPU 사용량이 70% 미만이 되도록 보다 고사양 가상 머신을 사용하는 것을 고려할 수도 있습니다.
임시 포트 고갈 스파스 또는 산발적인 연결의 경우 idleEndpointTimeout를 더 높은 값으로 설정하는 것이 좋습니다. DirectConnectionConfig의 idleEndpointTimeout 속성은 사용되지 않은 연결을 닫는 시간을 제어하는 데 도움이 됩니다. 이렇게 하면 사용되지 않은 연결 수가 줄어듭니다. 기본적으로 엔드포인트에 대한 유휴 연결은 1시간 동안 열려 있습니다. 유휴 엔드포인트 시간 제한 기간 동안 특정 엔드포인트에 대한 요청이 없는 경우 직접 클라이언트는 해당 엔드포인트에 대한 모든 연결을 닫아 리소스 및 I/O 비용을 절약합니다.
적절한 스케줄러 사용(이벤트 루프 IO Netty 스레드 도용 방지) 차단되는 호출 방지: .block(). 비동기 API 패턴과 적절한 스레딩 및 스케줄러 사용의 이점을 얻기 위해 전체 호출 스택이 비동기적입니다.
엔드투엔드 시간 제한 엔드투엔드 시간 제한을 만들려면 Java SDK에서 엔드투엔드 시간 제한 정책을 구현합니다. Azure Cosmos DB 시간 제한에 대한 자세한 내용은 여기를 방문하세요.
재시도 논리 일시적인 오류는 근본 원인을 바탕으로 자체적으로 해결되는 오류입니다. 데이터베이스에 연결하는 애플리케이션은 이러한 일시적인 오류를 예상하도록 빌드되어야 합니다. 이를 처리하기 위해 사용자에게 애플리케이션 오류로 표시되는 대신 해당 코드에서 다시 시도 논리를 구현합니다. SDK에는 읽기 또는 쿼리 작업과 같이 다시 시도할 수 있는 요청에서 이러한 일시적인 오류를 처리하는 기본 제공 논리가 있습니다. 쓰기가 idempotent가 아니므로 SDK는 일시적인 오류에 대해 쓰기를 다시 시도하지 않습니다. SDK를 사용하면 사용자가 제한에 대해 다시 시도 논리를 구성할 수 있습니다. 다시 시도할 오류에 대한 자세한 내용은 여기를 방문하세요.
데이터베이스/컬렉션 이름 캐싱 구성에서 데이터베이스 및 컨테이너의 이름을 검색하거나 시작할 때 이름을 캐시합니다. CosmosAsyncDatabase#read() 또는 CosmosAsyncContainer#read()와 같은 호출은 시스템 예약된 RU 제한을 사용하는 서비스에 대한 메타데이터 호출을 발생시킵니다. createDatabaseIfNotExists()는 데이터베이스를 설정하는 데 한 번만 사용해야 합니다. 전체적으로 이 작업은 자주 수행되지 않습니다.
병렬 쿼리 Azure Cosmos DB SDK는 쿼리의 대기 시간 및 처리량 향상을 위해 쿼리를 병렬로 실행할 수 있도록 지원합니다. CosmosQueryRequestsOptions 내에서 maxDegreeOfParallelism 속성은 보유하고 있는 파티션 수로 설정하는 것이 좋습니다. 파티션 수를 인식하지 못하는 경우 값을 -1로 값을 설정하면 대기 시간이 가장 짧아질 수 있습니다. 또한 maxBufferedItemCount를 예상되는 반환 결과 수로 설정하여 미리 가져온 결과 수를 제한합니다.
성능 테스트 백오프 애플리케이션에 대한 테스트를 수행하는 경우, RetryAfter 간격에 따라 백오프를 구현해야 합니다. 백오프를 사용하면 재시도 사이 대기 기간을 최소화할 수 있습니다.
인덱싱 Azure Cosmos DB 인덱싱 정책을 통해 인덱싱 경로(IndexingPolicy#getIncludedPaths() 및 IndexingPolicy#getExcludedPaths())를 사용하여 인덱싱에 포함하거나 제외할 문서 경로를 지정할 수도 있습니다. 쓰기 속도를 높이기 위해 인덱싱에서 사용하지 않는 경로를 제외합니다. SDK를 사용하여 인덱스를 만드는 방법에 대한 샘플은 여기를 방문하세요.
문서 크기 지정된 작업의 요청 요금은 문서의 크기와 직접 관련됩니다. 큰 문서에 대한 작업은 더 작은 문서에 대한 작업보다 비용이 많이 들기 때문에 문서 크기를 더 줄이는 것이 좋습니다.
이미지 크기 기본적으로 쿼리 결과는 100개 항목 또는 4MB의 청크로 반환됩니다. 이 중 먼저 도달하는 제한이 적용됩니다. 쿼리가 100개 이상의 항목을 반환하는 경우 페이지 크기를 늘려 필요한 왕복 횟수를 줄입니다. 페이지 크기가 증가하면 메모리 사용량도 증가합니다.
쿼리 메트릭 사용 백 엔드 쿼리 실행에 대한 추가 로깅은 Java SDK를 사용하여 SQL 쿼리 메트릭을 캡처하는 방법에 대한 지침을 따르세요.
SDK 로깅 SDK 로깅을 사용하여 추가 진단 정보를 캡처하고 대기 시간 문제를 해결할 수 있습니다. 서비스에 대한 현재 요청과 관련된 자세한 Azure Cosmos DB 진단 정보를 보려면 Java SDK에서 CosmosDiagnostics를 로그합니다. 사용 사례를 예로 들면, 모든 예외에 대한 진단을 캡처하고, CosmosDiagnostics#getDuration()이 지정된 임계값보다 큰 경우 완료된 작업에 대한 진단을 캡처합니다(즉, SLA가 10초이면 getDuration()> 10초일 때 진단 캡처). 성능 테스트 중에만 이러한 진단을 사용하는 것이 좋습니다. 자세한 내용은 Java SDK에 대한 캡처 진단을 따르세요.
식별자에 특수 문자를 사용하지 마세요. 일부 문자는 제한되며 일부 식별자 '/', '\', '?', '#'에서 사용할 수 없습니다. 일반적인 권장 사항은 예기치 않은 동작을 방지하기 위해 데이터베이스 이름, 컬렉션 이름, 항목 ID 또는 파티션 키와 같은 식별자에 특수 문자를 사용하지 않는 것입니다.

게이트웨이 모드를 사용하는 경우의 모범 사례

Azure Cosmos DB 요청은 게이트웨이 모드를 사용할 때 HTTPS/REST를 통해 수행됩니다. 호스트 이름이나 IP 주소당 기본 연결 한도가 적용됩니다. 클라이언트 라이브러리가 Azure Cosmos DB에 대한 다중 동시 연결을 사용할 수 있도록 maxConnectionPoolSize를 다른 값(100~1,000)으로 조정해야 할 수도 있습니다. Java v4 SDK에서 GatewayConnectionConfig#maxConnectionPoolSize의 기본값은 1000입니다. 값을 변경하려면 GatewayConnectionConfig#maxConnectionPoolSize를 다른 값으로 설정하면 됩니다.

쓰기 집약적인 워크로드의 모범 사례

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

다음 단계

Java SDK의 성능 팁에 대한 자세한 내용은 Azure Cosmos DB Java SDK v4에 대한 성능 팁을 참조하세요.

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

Azure Cosmos DB로 마이그레이션하기 위한 용량 계획을 수행하려고 하시나요? 용량 계획을 위해 기존 데이터베이스 클러스터에 대한 정보를 사용할 수 있습니다.