优化 Azure Cosmos DB Java SDK v4 的连接配置

项目
06/08/2023

适用范围： NoSQL

重要

本文中的性能提示仅适用于 Azure Cosmos DB Java SDK v4。请查看 Azure Cosmos DB Java SDK v4 发行说明、Maven 存储库、Azure Cosmos DB Java SDK v4 故障排除指南了解详细信息。如果你当前使用的是早于 v4 的版本，请参阅迁移到 Azure Cosmos DB Java SDK v4 指南，获取升级到 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。

异步
Sync

Java SDK V4 (Maven com.azure::azure-cosmos) 异步 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(120);
directConnectionConfig.setIdleConnectionTimeout(Duration.ofMillis(100));

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(150);

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();

Java SDK V4 (Maven com.azure::azure-cosmos) 同步 API


/* Direct mode, default settings */
CosmosClient clientDirectDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode()
        .buildClient();

/* Direct mode, custom settings */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(120);
directConnectionConfig.setIdleConnectionTimeout(Duration.ofMillis(100));

CosmosClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig)
        .buildClient();

/* Gateway mode, default settings */
CosmosClient clientGatewayDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode()
        .buildClient();

/* 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(150);

CosmosClient clientGatewayCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode(gatewayConnectionConfig)
        .buildClient();

/* No connection mode, defaults to Direct mode with default settings */
CosmosClient clientDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .buildClient();

自定义直接连接模式

如果需要非默认的直接模式行为，则在 Azure Cosmos DB 客户端生成器中创建 DirectConnectionConfig 实例并自定义其属性，然后将自定义的属性实例传递到 directMode() 方法。

这些配置设置控制以上讨论的基础直接模式体系结构的行为。

第一步是使用下面推荐的配置设置。这些 DirectConnectionConfig 选项是高级配置设置，可能会以意想不到的方式影响 SDK 性能；我们建议用户不要对其进行修改，除非他们深刻了解其中的得失，并且进行修改是绝对必要的。如果遇到有关此特定主题方面的问题，请与 Azure Cosmos DB 团队联系。

配置选项	默认	建议	详细信息
idleConnectionTimeout	"PT0" (ZERO)	"PT0" (ZERO)	表示到终结点/后端节点（表示副本）的单个连接的空闲连接超时持续时间。默认情况下，SDK 不会自动关闭与后端节点的空闲连接。
idleEndpointTimeout	"PT1H"	"PT1H"	表示终结点/后端节点（表示副本）的连接池的空闲连接超时持续时间。默认情况下，如果没有对特定终结点/后端节点的传入请求，SDK 将在 1 小时后关闭连接池中与该终结点/后端节点的所有连接，以节省网络资源和 I/O 成本。如果流量稀疏或具有偶发性，建议将此值设置为更大的数字（例如 6 小时、12 小时甚至 24 小时），这样 SDK 就不必频繁打开连接。但这样做会使用网络资源，并且在任何给定时间都会有更多的连接保持打开状态。如果将其设置为“零”，则会禁用空闲终结点检查。
maxConnectionsPerEndpoint	"130"	"130"	表示终结点/后端节点（表示副本）的连接池大小的上限。 SDK 会根据传入的并发请求按需创建与终结点/后端节点的连接。默认情况下，如果需要，SDK 将创建最多 130 个到终结点/后端节点的连接。（请注意：SDK 不会预先创建这 130 个连接）。
maxRequestsPerConnection	"30"	"30"	表示特定终结点/后端节点（表示副本）的单个连接上能排队的最大请求数上限。 SDK 根据传入的并发请求，按需对终结点/后端节点的单个连接的请求进行排队。默认情况下，如果需要，SDK 最多可向特定终结点/后端节点的单个连接排队 30 个请求。（请注意：SDK 不会预先将 30 个请求排队到单个连接）。
connectTimeout	"PT5S"	"~PT1S"	表示与终结点/后端节点建立单个连接的连接建立超时的持续时间。默认情况下，SDK 在引发错误之前会等待最多 5 秒种。 TCP 连接建立使用多步骤握手，这会导致连接建立时间延迟增长，因此，建议客户根据其网络带宽和环境设置来设置此值。备注：~PT1S 仅推荐用于部署在其 Cosmos DB 帐户的并置区域中的应用程序。
networkRequestTimeout	"PT5S"	"PT5S"	表示单个请求的网络超时持续时间。将请求写入网络连接后，SDK 将等待至达到该持续时间，以处理服务响应。 SDK 仅允许使用介于 1 秒（最小值）和 10 秒（最大值）之间的值。将值设置得过高可能会导致重试次数减少，并降低重试成功的可能性。

网关连接模式

控制平面操作（如数据库和容器 CRUD）始终使用网关模式。即使用户已为数据平面操作配置了直接模式，控制平面和元数据操作也将使用默认的网关模式设置。大多数用户是这种情况。但是，如果用户想将直接模式用于数据平面操作，同时获得控制平面网关模式参数的可调性，则可以使用以下 directMode() 的重写：

异步
Sync

Java SDK V4 (Maven com.azure::azure-cosmos) 异步 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(120);
directConnectionConfig.setIdleConnectionTimeout(Duration.ofMillis(100));

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(150);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig,gatewayConnectionConfig)
        .buildAsyncClient();

Java SDK V4 (Maven com.azure::azure-cosmos) 同步 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(120);
directConnectionConfig.setIdleConnectionTimeout(Duration.ofMillis(100));

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(150);

CosmosClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig,gatewayConnectionConfig)
        .buildClient();

自定义网关连接模式

如果需要非默认的网关模式行为，则请在 Azure Cosmos DB 客户端生成器中创建 GatewayConnectionConfig 实例并自定义其属性，然后将自定义的属性实例传递到上面的 directMode() 覆盖方法或 gatewayMode() 方法。

第一步是使用下面推荐的配置设置。这些 GatewayConnectionConfig 选项是高级配置设置，可能会以意想不到的方式影响 SDK 性能；我们建议，除非用户充分了解这种修改所产生的影响并认为修改是绝对必要的，否则不要对其进行修改。如果遇到有关此特定主题方面的问题，请与 Azure Cosmos DB 团队联系。

配置选项	默认	建议	详细信息
maxConnectionPoolSize	"1000"	"1000"	表示基础 http 客户端的连接池的大小上限，即 SDK 将为进入网关模式的请求创建的最大连接数。 SDK 在向网关发送请求时会重复使用这些连接。
idleConnectionTimeout	"PT60S"	"PT60S"	表示网关的单个连接的空闲连接超时持续时间。达到此时间后，连接将自动关闭，并从连接池中删除。

后续步骤

若要详细了解 Java SDK 的性能提示，请参阅 Azure Cosmos DB Java SDK v4 的性能提示。

若要深入了解如何设计应用程序以实现缩放和高性能，请参阅 Azure Cosmos DB 中的分区和缩放。

尝试为迁移到 Azure Cosmos DB 进行容量计划？可以使用有关现有数据库群集的信息进行容量规划。

如果只知道现有数据库群集中的 vCore 和服务器数量，请阅读使用 vCore 或 vCPU 估算请求单位
若知道当前数据库工作负载的典型请求速率，请阅读使用 Azure Cosmos DB 容量计划工具估算请求单位