Sugerencias de optimización de rendimiento para Azure Cosmos DB Sync Java SDK v2

• SDK de Java v4
• SDK sincrónico para Java v2
• SDK de Java v2 sincrónico
• SDK de .NET v3
• SDK de .NET v2
• SDK de Python

Importante

No se trata de la versión de SDK de Azure Cosmos DB para Java más reciente. Debe actualizar el proyecto al SDK de Java v4 de Azure Cosmos DB y, a continuación, leer la guía de sugerencias de rendimiento del SDK de Java v4 de Azure Cosmos DB. Siga las instrucciones de la guía Migración al SDK de Java de Azure Cosmos DB v4 y la guía de Reactor frente a RxJava para actualizar.

Estas sugerencias de rendimiento son solo para el SDK de Java de Sincronización de Azure Cosmos DB v2. Consulte el repositorio de Maven para obtener más información.

Importante

El 29 de febrero de 2024 se retirará el SDK de Java de sincronización de Azure Cosmos DB v2.x; el SDK y todas las aplicaciones que usan el SDK seguirán funcionando; Azure Cosmos DB simplemente dejará de proporcionar más mantenimiento y soporte técnico para este SDK. Se recomienda seguir las instrucciones anteriores para migrar al SDK de Java v4 de Azure Cosmos DB.

Azure Cosmos DB es una base de datos distribuida rápida y flexible que se escala sin problemas con una latencia y un rendimiento garantizados. No es necesario realizar cambios de arquitectura importantes ni escribir código complejo para escalar la base de datos con Azure Cosmos DB. Escalar o reducir verticalmente es tan sencillo como realizar una única llamada API. Para más información, consulte cómo aprovisionar el rendimiento del contenedor o cómo aprovisionar el rendimiento de la base de datos. Sin embargo, dado que se accede a Azure Cosmos DB a través de llamadas de red, hay optimizaciones del lado cliente que puede realizar para lograr un rendimiento máximo al usar el SDK de Java de Sincronización de Azure Cosmos DB v2.

Por lo tanto, si se pregunta "¿Cómo puedo mejorar el rendimiento de mi base de datos?", considere las siguientes opciones:

Networking

1. Modo de conexión: uso de DirectHttps

   La forma en que un cliente se conecta a Azure Cosmos DB tiene implicaciones importantes en el rendimiento, especialmente en términos de latencia observada del lado cliente. Hay una opción de configuración clave disponible para configurar connectionPolicy de cliente: connectionMode. Los dos ConnectionModes disponibles son:

   1. Puerta de enlace (valor predeterminado)

   2. DirectHttps

      El modo de puerta de enlace es compatible con todas las plataformas del SDK y es el valor predeterminado configurado. Si la aplicación se ejecuta dentro de una red corporativa con restricciones estrictas de firewall, la puerta de enlace es la mejor opción, ya que usa el puerto HTTPS estándar y un único punto de conexión. Sin embargo, el equilibrio de rendimiento es que el modo de puerta de enlace implica un salto de red adicional cada vez que los datos se leen o escriben en Azure Cosmos DB. Por este motivo, el modo DirectHttps ofrece un mejor rendimiento debido a menos saltos de red.

      El SDK de Java de sincronización de Azure Cosmos DB v2 usa HTTPS como protocolo de transporte. HTTPS usa TLS para la autenticación inicial y el cifrado del tráfico. Al usar el SDK de Java de Sincronización de Azure Cosmos DB v2, solo es necesario abrir el puerto HTTPS 443.

      ConnectionMode se configura durante la construcción de la instancia de DocumentClient con el parámetro ConnectionPolicy.

   Sincronización del SDK de Java V2 (Maven com.microsoft.azure::azure-documentdb)

   public ConnectionPolicy getConnectionPolicy() {
     ConnectionPolicy policy = new ConnectionPolicy();
     policy.setConnectionMode(ConnectionMode.DirectHttps);
     policy.setMaxPoolSize(1000);
     return policy;
   }
   
   ConnectionPolicy connectionPolicy = new ConnectionPolicy();
   DocumentClient client = new DocumentClient(HOST, MASTER_KEY, connectionPolicy, null);
   

   

2. Colocación de los clientes en la misma región de Azure para aumentar el rendimiento

   Cuando sea posible, coloque las aplicaciones que llaman a Azure Cosmos DB en la misma región que la base de datos de Azure Cosmos DB. Para obtener una comparación aproximada, las llamadas a Azure Cosmos DB en la misma región se realizan en menos de 1 o 2 ms, pero la latencia entre las costas este y oeste de Estados Unidos es >50 ms. Esta latencia podría variar de una solicitud a otra, según la ruta tomada por la solicitud cuando pasa del cliente al límite del centro de datos de Azure. Para conseguir la menor latencia posible, asegúrese de que la aplicación que llama se encuentra en la misma región de Azure que el punto de conexión de Azure Cosmos DB aprovisionado. Para obtener una lista de regiones disponibles, consulte Regiones de Azure.

   

Uso del SDK

1. Instalación del SDK más reciente

   Los SDK de Azure Cosmos DB se mejoran constantemente para proporcionar el mejor rendimiento. Para determinar las mejoras más recientes del SDK, visite el SDK de Azure Cosmos DB.

2. Uso de un cliente de Azure Cosmos DB singleton para aumentar la duración de la aplicación

   Cada instancia de DocumentClient es segura para subprocesos y realiza una administración eficaz de la conexión y el almacenamiento en caché de direcciones cuando se trabaja en modo directo. Para permitir una administración de conexiones eficaz y un mejor rendimiento de DocumentClient, se recomienda usar una sola instancia de DocumentClient por AppDomain durante la vigencia de la aplicación.

3. Aumento de MaxPoolSize por host al usar el modo de puerta de enlace

   Las solicitudes de Azure Cosmos DB se realizan a través de HTTPS/REST cuando se usa el modo de puerta de enlace y están sujetas al límite de conexión predeterminado por nombre de host o dirección IP. Es posible que tenga que establecer MaxPoolSize en un valor mayor (200-1000) para que la biblioteca cliente pueda usar varias conexiones simultáneas a Azure Cosmos DB. En el SDK de Java de sincronización de Azure Cosmos DB v2, el valor predeterminado de ConnectionPolicy.getMaxPoolSize es 100. Use setMaxPoolSize para cambiar el valor.

4. Optimización de consultas paralelas para colecciones con particiones

   La versión 1.9.0 y posteriores del SDK de Java de Sincronización de Azure Cosmos DB admiten consultas paralelas, lo que le permite consultar una colección con particiones en paralelo. Para obtener más información, consulte ejemplos de código relacionados con el trabajo con los SDK. Las consultas paralelas están diseñadas para mejorar la latencia y el rendimiento de las consultas respecto a sus homólogos en serie.

   (a) Ajuste de setMaxDegreeOfParallelism: Las consultas paralelas funcionan consultando diferentes particiones simultáneamente. Sin embargo, los datos de una colección particionada individualmente se recuperan en serie con respecto a la consulta. Por lo tanto, use setMaxDegreeOfParallelism para establecer el número de particiones que tiene la máxima posibilidad de lograr la consulta más eficaz, siempre que todas las demás condiciones del sistema sigan siendo las mismas. Si no conoce el número de particiones, puede usar setMaxDegreeOfParallelism para establecer un número alto y el sistema elige el mínimo (número de particiones, entrada proporcionada por el usuario) como el grado máximo de paralelismo.

   Es importante tener en cuenta que las consultas paralelas producen las mejores ventajas si los datos se distribuyen uniformemente entre todas las particiones con respecto a la consulta. Si la colección con particiones se particiona de tal manera que todos o la mayoría de los datos devueltos por una consulta se concentran en algunas particiones (una partición en el peor de los casos), el rendimiento de la consulta se vería afectado por esas particiones.

   (b) Ajuste de setMaxBufferedItemCount: La consulta paralela está diseñada para precargar resultados mientras el cliente procesa el lote actual de resultados. La captura previa ayuda a mejorar la latencia general de una consulta. setMaxBufferedItemCount limita el número de resultados precargados. Al establecer setMaxBufferedItemCount en el número esperado de resultados devueltos (o un número superior), esto permite que la consulta reciba el máximo beneficio de la captura previa.

   La captura previa funciona de la misma manera independientemente del maxDegreeOfParallelism y hay un único búfer para los datos de todas las particiones.

5. Implementar el retroceso en los intervalos de getRetryAfterInMilliseconds

   Durante las pruebas de rendimiento, debe aumentar la carga hasta que se limite una pequeña tasa de solicitudes. Si se le aplica una limitación, la aplicación cliente debe reducir su actividad durante el intervalo de reintento especificado por el servidor. Respetar el retroceso garantiza que dedique un tiempo mínimo a la espera entre reintentos. La compatibilidad con directivas de reintento se incluye en la versión 1.8.0 y posteriores del SDK de Java de Sincronización de Azure Cosmos DB. Para obtener más información, vea getRetryAfterInMilliseconds.

6. Escalado horizontal de la carga de trabajo de cliente

   Si está probando en niveles de alto rendimiento (>50 000 RU/s), la aplicación cliente puede convertirse en el cuello de botella debido al límite de la máquina en el uso de CPU o red. Si llega a este punto, puede seguir insertando la cuenta de Azure Cosmos DB mediante la escala horizontal de las aplicaciones cliente en varios servidores.

7. Uso del direccionamiento basado en nombres

   Use direccionamiento basado en nombres, donde los vínculos tienen el formato dbs/MyDatabaseId/colls/MyCollectionId/docs/MyDocumentId, en lugar de SelfLinks (_self), que tienen el formato dbs/<database_rid>/colls/<collection_rid>/docs/<document_rid> para evitar recuperar ResourceIds de todos los recursos usados para construir el vínculo. Además, a medida que estos recursos se vuelven a crear (posiblemente con el mismo nombre), es posible que el almacenamiento en caché no le ayude.

8. Ajuste del tamaño de página de las consultas o fuentes de lectura para mejorar el rendimiento.

   Al realizar una lectura masiva de documentos mediante la funcionalidad de fuente de lectura (por ejemplo, readDocuments) o al emitir una consulta SQL, los resultados se devuelven de forma segmentada si el conjunto de resultados es demasiado grande. De forma predeterminada, los resultados se devuelven en fragmentos de 100 elementos o 1 MB, el límite que se alcance primero.

   Para reducir el número de recorridos de ida y vuelta de red necesarios para recuperar todos los resultados aplicables, puede aumentar el tamaño de página mediante el encabezado de solicitud x-ms-max-item-count hasta 1000. En los casos en los que necesite mostrar solo unos pocos resultados, por ejemplo, si la interfaz de usuario o la API de aplicación devuelve solo 10 resultados a la vez, también puede reducir el tamaño de página a 10 para reducir el rendimiento consumido para lecturas y consultas.

   También puede establecer el tamaño de página mediante el método setPageSize.

Directiva de indexación

1. Exclusión de rutas de acceso sin utilizar de la indexación para acelerar las escrituras

   La directiva de indexación de Azure Cosmos DB permite especificar, mediante directorios de indexación, las rutas de acceso de documentos que se van a incluir o excluir de la indexación (setIncludedPaths y setExcludedPaths). El uso de rutas de acceso de indexación puede ofrecer un rendimiento de escritura mejorado y un almacenamiento de índices reducido en escenarios en los que los patrones de consulta se conocen de antemano, dado que los costos de indexación están directamente correlacionados con el número de rutas de acceso únicas indexadas. Por ejemplo, el código siguiente muestra cómo excluir una sección completa (subárbol) de los documentos de la indexación mediante el comodín "*".

   Sincronización del SDK de Java V2 (Maven com.microsoft.azure::azure-documentdb)

   Index numberIndex = Index.Range(DataType.Number);
   numberIndex.set("precision", -1);
   indexes.add(numberIndex);
   includedPath.setIndexes(indexes);
   includedPaths.add(includedPath);
   indexingPolicy.setIncludedPaths(includedPaths);
   collectionDefinition.setIndexingPolicy(indexingPolicy);
   

   Para más información, consulte Directivas de indexación de Azure Cosmos DB.

Capacidad de procesamiento

1. Medición y optimización del uso menor de unidades de solicitud por segundo

   Azure Cosmos DB ofrece un amplio conjunto de operaciones de base de datos, incluidas consultas relacionales y jerárquicas con funciones definidas por el usuario, procedimientos almacenados y desencadenadores. Todo funciona con los documentos dentro de una colección de base de datos. El costo asociado a cada una de estas operaciones variará en función de la CPU, la E/S y la memoria necesarias para completar la operación. En lugar de administrar y pensar sobre los recursos de hardware, puede pensar en una unidad de solicitud (RU) como una medida única para los recursos necesarios para realizar varias operaciones de la base de datos y dar servicio a una solicitud de la aplicación.

   El rendimiento se aprovisiona en función del número de unidades de solicitud establecido para cada contenedor. El consumo de la unidad de solicitud se evalúa como frecuencia por segundo. Las aplicaciones que superan la frecuencia de unidad de solicitud aprovisionada para su contenedor están limitadas hasta que la frecuencia cae por debajo del nivel aprovisionado del contenedor. Si la aplicación requiere un mayor nivel de rendimiento, puede aumentar el rendimiento mediante el aprovisionamiento de unidades de solicitud adicionales.

   La complejidad de una consulta afecta a la cantidad de unidades de solicitud consumidas para una operación. El número de predicados, la naturaleza de los predicados, el número de UDF y el tamaño del conjunto de datos de origen influyen en el costo de operaciones de consulta.

   Para medir la sobrecarga de cualquier operación (crear, actualizar o eliminar), inspeccione el encabezado x-ms-request-charge (o la propiedad RequestCharge equivalente en ResourceResponse<T> o FeedResponse<T> para medir el número de unidades de solicitud consumidas por estas operaciones.

   Sincronización del SDK de Java V2 (Maven com.microsoft.azure::azure-documentdb)

   ResourceResponse<Document> response = client.createDocument(collectionLink, documentDefinition, null, false);
   
   response.getRequestCharge();
   

   El cargo de solicitud devuelto en este encabezado es una fracción de la capacidad de proceso aprovisionada. Por ejemplo, si tiene aprovisionadas 2000 RU/s y si la consulta anterior devolviera 1000 documentos de 1 KB, el costo de la operación es de 1000. Por lo tanto, al cabo de un segundo, el servidor atenderá solo dos de estas solicitudes antes de limitar la velocidad de las solicitudes posteriores. Para más información, consulte Unidades de solicitud y la calculadora de unidades de solicitud.

2. Administración de la limitación de velocidad y la tasa de solicitudes demasiado grande

   Cuando un cliente intenta superar la capacidad de proceso reservada para una cuenta, no habrá ninguna degradación del rendimiento en el servidor y no se utilizará ninguna capacidad de proceso más allá del nivel reservado. El servidor finalizará de forma preventiva la solicitud con RequestRateTooLarge (código de estado HTTP 429) y devolverá el encabezado x-ms-retry-after-ms para indicar la cantidad de tiempo, en milisegundos, que el usuario debe esperar antes de volver a intentar realizar la solicitud.

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

   Los SDK capturan implícitamente esta respuesta, respetan el encabezado retry-after especificado por el servidor y reintentan la solicitud. A menos que varios clientes obtengan acceso a la cuenta al mismo tiempo, el siguiente reintento se realizará correctamente.

   Si tiene más de un cliente que funciona de forma acumulativa de forma coherente por encima de la tasa de solicitudes, es posible que el número de reintentos predeterminado establecido actualmente en 9 internamente por el cliente no sea suficiente; en este caso, el cliente inicia una excepción DocumentClientException con el código de estado 429 a la aplicación. El recuento de reintentos predeterminado se puede cambiar mediante setRetryOptions en la instancia de ConnectionPolicy . De forma predeterminada, documentClientException con el código de estado 429 se devuelve después de un tiempo de espera acumulado de 30 segundos si la solicitud sigue funcionando por encima de la tasa de solicitudes. Esto sucede incluso cuando el número de reintentos actual es inferior al número de reintentos máximo de 9, el valor predeterminado, o un valor definido por el usuario.

   Aunque el comportamiento de reintento automático ayuda a mejorar la resistencia y la usabilidad en la mayoría de las aplicaciones, podría no resultar ventajoso al realizar comparativas de rendimiento, en especial al medir la latencia. La latencia observada del cliente aumentará si el experimento llega a la limitación del servidor y hace que el SDK del cliente realice reintentos de forma silenciosa. Para evitar aumentos de latencia durante los experimentos de rendimiento, mida el gasto devuelto por cada operación y asegúrese de que las solicitudes funcionan por debajo de la tasa de solicitudes observada. Para más información, consulte Unidades de solicitud.

3. Diseño de documentos más pequeños para un mayor rendimiento

   El gasto de solicitud (es decir, el costo de procesamiento de solicitudes) de una operación dada está directamente correlacionado con el tamaño del documento. Las operaciones con documentos grandes cuestan más que las operaciones con documentos pequeños.

Pasos siguientes

Para más información sobre cómo diseñar la aplicación para escalarla y obtener un alto rendimiento, consulte Partición y escalado en Azure Cosmos DB.