중요합니다
이 문서의 성능 팁은 Azure Cosmos DB Java SDK v4 전용입니다. 자세한 내용은 Azure Cosmos DB Java SDK v4 릴리스 정보, Maven 리포지토리 및 Azure Cosmos DB Java SDK v4 문제 해결 가이드를 참조하세요. 현재 v4보다 이전 버전을 사용하는 경우 v4로 업그레이드하는 방법에 대한 도움말은 Azure Cosmos DB Java SDK v4로 마이그레이션 가이드를 참조하세요.
Azure Cosmos DB는 보장된 대기 시간 및 처리량으로 매끄럽게 크기가 조정되는 빠르고 유연한 분산 데이터베이스입니다. Azure Cosmos DB를 사용하여 데이터베이스를 스케일링하기 위해 주요 아키텍처를 변경하거나 복잡한 코드를 작성할 필요는 없습니다. 규모를 확장 및 축소하는 것은 단일 API 호출 또는 SDK 메서드 호출을 수행하는 것만큼 쉽습니다. 그러나 네트워크 호출을 통해 Azure Cosmos DB에 액세스하기 때문에 Azure Cosmos DB Java SDK v4를 사용할 때 최고 성능을 달성하기 위해 조정할 수 있는 연결 구성이 있습니다.
연결 구성
비고
Azure Cosmos DB Java SDK v4에서 직접 모드 는 대부분의 워크로드에서 데이터베이스 성능을 향상시키는 가장 좋은 선택입니다.
다양한 연결 옵션에 관한 자세한 정보는 연결 모드 문서를 참조하세요.
직접 연결 모드
Java SDK 기본 연결 모드는 직접입니다. 직접 모드 Azure Cosmos DB 요청은 Azure Cosmos DB Java SDK v4를 사용하는 경우 TCP를 통해 이루어집니다. 내부적으로 직접 모드는 특수 아키텍처를 사용하여 네트워크 리소스를 동적으로 관리하고 최상의 성능을 얻습니다. 직접 모드에서 사용하는 클라이언트 쪽 아키텍처를 사용하면 Azure Cosmos DB 복제본에 대한 예측 가능한 네트워크 사용률 및 다중 액세스가 가능합니다. 아키텍처에 대한 자세한 내용은 직접 모드 연결 아키텍처를 참조하세요.
여기에 표시된 것처럼 directMode() 메서드를 사용하여 클라이언트 작성기에서 연결 모드를 구성할 수 있습니다. 기본 설정으로 직접 모드를 구성하려면 인수 없이 메서드를 호출 directMode() 합니다. 직접 모드 연결 설정을 사용자 지정하려면 DirectConnectionConfig 를 API에 directMode() 전달합니다.
Java SDK V4(Maven com.azure::azure-cosmos) Async API
/* Direct mode, default settings */
CosmosAsyncClient clientDirectDefault = new CosmosClientBuilder()
.endpoint(HOSTNAME)
.key(MASTERKEY)
.consistencyLevel(CONSISTENCY)
.directMode()
.buildAsyncClient();
/* Direct mode, custom settings */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);
CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
.endpoint(HOSTNAME)
.key(MASTERKEY)
.consistencyLevel(CONSISTENCY)
.directMode(directConnectionConfig)
.buildAsyncClient();
/* Gateway mode, default settings */
CosmosAsyncClient clientGatewayDefault = new CosmosClientBuilder()
.endpoint(HOSTNAME)
.key(MASTERKEY)
.consistencyLevel(CONSISTENCY)
.gatewayMode()
.buildAsyncClient();
/* Gateway mode, custom settings */
GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();
// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);
CosmosAsyncClient clientGatewayCustom = new CosmosClientBuilder()
.endpoint(HOSTNAME)
.key(MASTERKEY)
.consistencyLevel(CONSISTENCY)
.gatewayMode(gatewayConnectionConfig)
.buildAsyncClient();
/* No connection mode, defaults to Direct mode with default settings */
CosmosAsyncClient clientDefault = new CosmosClientBuilder()
.endpoint(HOSTNAME)
.key(MASTERKEY)
.consistencyLevel(CONSISTENCY)
.buildAsyncClient();
직접 연결 모드 사용자 지정
기본이 아닌 직접 모드 동작이 필요한 경우 DirectConnectionConfig 인스턴스를 만들고 해당 속성을 사용자 지정한 다음, 사용자 지정된 속성 인스턴스를 Azure Cosmos DB 클라이언트 빌더의 directMode() 메서드에 전달합니다.
이러한 구성 설정은 앞에서 설명한 기본 직접 모드 아키텍처의 동작을 제어합니다.
첫 번째 단계로 여기에 권장되는 다음 구성 설정을 사용합니다. 이러한 DirectConnectionConfig 옵션은 예기치 않은 방법으로 SDK 성능에 영향을 줄 수 있는 고급 구성 설정입니다. 절충을 이해하는 데 익숙하고 필요한 경우가 아니면 사용자가 수정하지 않는 것이 좋습니다. 이 특정 주제에 문제가 발생하는 경우 Azure Cosmos DB 팀에 문의하세요.
| 구성 옵션 | Default | Recommended | 세부 정보 |
|---|---|---|---|
| idleConnectionTimeout | "PT0"(제로) | "PT0"(제로) | 이는 엔드포인트/백 엔드 노드(복제본을 나타낸)에 대한 단일 연결 에 대한 유휴 연결 제한 시간을 나타냅니다. 기본적으로 SDK는 백 엔드 노드에 대한 유휴 연결을 자동으로 닫지 않습니다. |
| idleEndpointTimeout | "PT1H" | "PT1H" | 이는 엔드포인트/백 엔드 노드(복제본을 나타낸)에 대한 연결 풀 의 유휴 연결 제한 시간을 나타냅니다. 기본적으로 특정 엔드포인트/백 엔드 노드에 들어오는 요청이 없는 경우 SDK는 네트워크 리소스 및 I/O 비용을 절약하기 위해 1시간 후 해당 엔드포인트/백 엔드 노드에 대한 연결 풀의 모든 연결을 닫습니다. 스파스 또는 산발적인 트래픽 패턴의 경우 SDK가 연결을 자주 열 필요가 없도록 이 값을 6시간, 12시간 또는 24시간과 같은 더 높은 숫자로 설정하는 것이 좋습니다. 그러나 네트워크 리소스를 활용하며 지정된 시간에 더 많은 수의 연결이 열린 상태로 유지됩니다. 이 설정을 ZERO로 설정하면 유휴 엔드포인트 검사를 사용할 수 없습니다. |
| maxConnectionsPerEndpoint | "130" | "130" | 이는 엔드포인트/백 엔드 노드(복제본을 나타낸)에 대한 연결 풀 의 상한 크기를 나타냅니다. SDK는 들어오는 동시 요청에 따라 요청 시 엔드포인트/백 엔드 노드에 대한 연결을 만듭니다. 기본적으로 필요한 경우 SDK는 엔드포인트/백 엔드 노드에 최대 130개의 연결을 만듭니다. (참고: SDK는 이러한 130개의 연결을 미리 만들지 않습니다.) |
| maxRequestsPerConnection | 30 | 30 | 이는 특정 엔드포인트/백 엔드 노드(복제본을 나타낸)에 대해 단일 연결 에서 큐에 대기할 수 있는 최대 요청 수의 상한 크기를 나타냅니다. SDK는 요청 시 엔드포인트/백 엔드 노드에 대한 단일 연결 및 들어오는 동시 요청에 따라 요청을 큐에 대기합니다. 기본적으로 필요한 경우 SDK는 특정 엔드포인트/백 엔드 노드에 대한 단일 연결에 최대 30개의 요청을 큐에 대기합니다. (참고: SDK는 이러한 30개의 요청을 단일 연결에 사전 큐로 대기하지 않습니다.) |
| 연결 시간 초과 | "PT5S" | "~PT1S" | 엔드포인트/백 엔드 노드를 사용하여 단일 연결을 설정할 수 있는 연결 설정 제한 시간을 나타냅니다. 기본적으로 SDK는 연결이 설정되기까지 최대 5초 동안 대기한 후 오류를 발생시킵니다. TCP 연결 설정은 연결 설정 시간의 대기 시간을 증가시키는 다단계 핸드셰이크를 사용하므로 고객은 네트워크 대역폭 및 환경 설정에 따라 이 값을 설정하는 것이 좋습니다. 참고: ~PT1S의 권장 사항은 Cosmos DB 계정의 공동 배치된 지역에 배포된 애플리케이션에만 적용됩니다. |
| 네트워크 요청 시간 초과 | "PT5S" | "PT5S" | 단일 요청에 대한 네트워크 시간 제한 기간을 나타냅니다. SDK는 요청이 네트워크 연결에 기록된 후 이 기간 동안 서비스 응답을 처리하기 위해 최대한 기다립니다. SDK는 1초(분)에서 10초(최대) 사이의 값만 허용합니다. 값을 너무 높게 설정하면 재시도 횟수가 줄어들고 재시도를 통해 성공 가능성을 줄일 수 있습니다. |
게이트웨이 연결 모드
데이터베이스 및 컨테이너 CRUD와 같은 컨트롤 플레인 작업은 항상 게이트웨이 모드를 활용합니다. 사용자가 데이터 평면 작업에 대한 직접 모드를 구성한 경우에도 컨트롤 플레인 및 메타 데이터 작업은 기본 게이트웨이 모드 설정을 사용합니다. 이는 대부분의 사용자에게 적합합니다. 그러나 데이터 평면 작업에 대한 직접 모드 및 컨트롤 플레인 게이트웨이 모드 매개 변수의 튜닝 가능성을 원하는 사용자는 다음 directMode() 재정의를 사용할 수 있습니다.
Java SDK V4(Maven com.azure::azure-cosmos) Async API
/* Independent customization of Direct mode data plane and Gateway mode control plane */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);
GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();
// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);
CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
.endpoint(HOSTNAME)
.key(MASTERKEY)
.consistencyLevel(CONSISTENCY)
.directMode(directConnectionConfig,gatewayConnectionConfig)
.buildAsyncClient();
게이트웨이 연결 모드 사용자 지정
기본이 아닌 게이트웨이 모드 동작이 필요한 경우 GatewayConnectionConfig 인스턴스를 만들고 해당 속성을 사용자 지정한 다음, 사용자 지정된 속성 인스턴스를 Azure Cosmos DB 클라이언트 작성기에서 directMode() 재정의 메서드 또는 gatewayMode() 메서드에 전달합니다.
첫 번째 단계로 여기에 권장되는 다음 구성 설정을 사용합니다. 이러한 GatewayConnectionConfig 옵션은 예기치 않은 방법으로 SDK 성능에 영향을 줄 수 있는 고급 구성 설정입니다. 절충을 이해하는 데 익숙하고 필요한 경우가 아니면 사용자가 수정하지 않는 것이 좋습니다. 이 특정 주제에 문제가 발생하는 경우 Azure Cosmos DB 팀에 문의하세요.
| 구성 옵션 | Default | Recommended | 세부 정보 |
|---|---|---|---|
| maxConnectionPoolSize | "1000" | "1000" | 이는 게이트웨이 모드로 가는 요청에 대해 SDK가 만드는 최대 연결 수인 기본 http 클라이언트에 대한 연결 풀 크기의 상한 크기를 나타냅니다. SDK는 게이트웨이에 요청을 보낼 때 이러한 연결을 다시 사용합니다. |
| idleConnectionTimeout | "PT60S" | "PT60S" | 게이트웨이에 대한 단일 연결에 대한 유휴 연결 시간 제한 기간을 나타냅니다. 이 시간이 지나면 연결이 자동으로 닫히고 연결 풀에서 제거됩니다. |
다음 단계
Java SDK의 성능 팁에 대한 자세한 내용은 Azure Cosmos DB Java SDK v4에 대한 성능 팁을 참조하세요.
확장성 및 고성능을 위한 애플리케이션 설계 방법에 대한 자세한 내용은 Azure Cosmos DB의 분할 및 크기 조정을 참조하세요.
Azure Cosmos DB로 마이그레이션하기 위한 용량 계획을 수행하려고 하시나요? 용량 계획을 위해 기존 데이터베이스 클러스터에 대한 정보를 사용할 수 있습니다.
- 기존 데이터베이스 클러스터의 vCore 및 서버의 수만 알고 있는 경우 vCore 또는 vCPU를 사용하여 요청 단위 예측을 참조하세요
- 현재 데이터베이스 워크로드에 대한 일반적인 요청 비율을 알고 있는 경우 Azure Cosmos DB 용량 계획 도구를 사용하여 요청 단위 예측에 대해 읽어보세요.