Azure Cosmos DB Java SDK v4에 대한 연결 구성 조정

  • 아티클

적용 대상: NoSQL

Important

이 문서의 성능 팁은 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 Java SDK v4를 사용하는 경우 직접 모드 Azure Cosmos DB 요청은 TCP를 통해 수행됩니다. 내부적으로 직접 모드는 특별한 아키텍처를 사용하여 네트워크 리소스를 동적으로 관리하고 최고의 성능을 얻습니다. 직접 모드에서 사용되는 클라이언트 쪽 아키텍처를 사용하면 네트워크 사용률을 예측할 수 있고 Azure Cosmos DB 복제본에 멀티플렉싱 방식으로 액세스할 수 있습니다. 아키텍처에 대한 자세한 내용은 직접 모드 연결 아키텍처를 참조하세요.

아래와 같이 directMode() 메서드를 사용하여 클라이언트 작성기에서 연결 모드를 구성할 수 있습니다. 기본 설정을 사용하여 직접 모드를 구성하려면 인수 없이 directMode() 메서드를 호출합니다. 직접 모드 연결 설정을 사용자 지정하려면 DirectConnectionConfig를 directMode() API에 전달합니다.

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 팀에 문의하세요.

구성 옵션 기본값 권장 세부 정보
idleConnectionTimeout "PT0"(0) "PT0"(0) 엔드포인트/백 엔드 노드(복제본을 나타냄)에 대한 단일 연결의 유휴 연결 시간 제한을 나타냅니다. 기본적으로 SDK는 백 엔드 노드에 대한 유휴 연결을 자동으로 닫지 않습니다.
idleEndpointTimeout "PT1H" "PT1H" 엔드포인트/백 엔드 노드(복제본을 나타냄)에 대한 연결 풀의 유휴 연결 시간 제한을 나타냅니다. 기본적으로 특정 엔드포인트/백 엔드 노드에 들어오는 요청이 없는 경우 SDK는 네트워크 리소스 및 I/O 비용을 절약하기 위해 1시간 후에 해당 엔드포인트/백 엔드 노드에 대한 연결 풀의 모든 연결을 닫습니다. 희박하거나 산발적인 트래픽 패턴의 경우 이 값을 6시간, 12시간 또는 24시간과 같은 더 높은 숫자로 설정하여 SDK가 연결을 자주 열지 않아도 되도록 하는 것이 좋습니다. 그러나 이렇게 하면 네트워크 리소스가 활용되고 지정된 시간에 더 많은 수의 연결이 열린 상태로 유지됩니다. 0으로 설정하면 유휴 엔드포인트 검사가 사용하지 않도록 설정됩니다.
maxConnectionsPerEndpoint "130" "130" 엔드포인트/백 엔드 노드(복제본을 나타낸)에 대한 연결 풀의 상한 크기를 나타냅니다. SDK는 요청 시 및 들어오는 동시 요청을 기반으로 엔드포인트/백 엔드 노드에 대한 연결을 만듭니다. 기본적으로 필요한 경우 SDK는 엔드포인트/백 엔드 노드에 대한 최대 130개의 연결을 만듭니다. (참고: SDK는 이러한 130개의 연결을 미리 만들지 않습니다.)
maxRequestsPerConnection "30" "30" 특정 엔드포인트/백 엔드 노드(복제본을 나타냄)에 대한 단일 연결에서 대기할 수 있는 최대 요청 수의 상한 크기를 나타냅니다. DK는 요청 시 및 들어오는 동시 요청을 기반으로 엔드포인트/백 엔드 노드에 대한 단일 연결 요청을 큐에 추가합니다. 기본적으로 필요한 경우 SDK는 특정 엔드포인트/백 엔드 노드에 대한 단일 연결에 최대 30개의 요청을 큐에 추가합니다. (참고: SDK는 이러한 30개의 요청을 단일 연결에 미리 큐에 추가하지 않습니다.)
connectTimeout "PT5S" "~PT1S" 엔드포인트/백 엔드 노드를 사용하여 단일 연결을 설정할 연결 설정 시간 제한을 나타냅니다. 기본적으로 SDK는 오류를 throw하기 전에 연결 설정을 위해 최대 5초 동안 대기합니다. TCP 연결 설정은 연결 설정 시간의 대기 시간을 증가시키는 다단계 핸드셰이크를 사용하므로 고객은 네트워크 대역폭 및 환경 설정에 따라 이 값을 설정하는 것이 좋습니다. 참고: ~PT1S의 이 권장 사항은 Cosmos DB 계정의 공동 배치 지역에 배포된 애플리케이션에만 적용됩니다.
networkRequestTimeout "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 팀에 문의하세요.

구성 옵션 기본값 권장 세부 정보
maxConnectionPoolSize "1000" "1000" 게이트웨이 모드로 가는 요청에 대해 SDK가 만들 최대 연결 수인 기본 http 클라이언트에 대한 연결 풀 크기의 상한 크기를 나타냅니다. SDK는 게이트웨이에 요청을 보낼 때 이러한 연결을 다시 사용합니다.
idleConnectionTimeout "PT60S" "PT60S" 게이트웨이에 대한 단일 연결의 유휴 연결 시간 제한 기간을 나타냅니다. 이 시간 후에는 연결이 자동으로 닫혀 연결 풀에서 제거됩니다.

다음 단계

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

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

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