Diagnóstico y solución de problemas al usar el SDK de .NET de Azure Cosmos DB

SE APLICA A: NoSQL

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

En este artículo, se tratan problemas comunes, soluciones alternativas, pasos de diagnóstico y herramientas cuando se usa el SDK de .NET con cuentas de Azure Cosmos DB for NoSQL. El SDK de .NET proporciona la representación lógica del lado cliente para acceder a Azure Cosmos DB for NoSQL. En este artículo se describen herramientas y enfoques para ayudarle si surge algún problema.

Lista de comprobación para la solución de problemas

Tenga en cuenta la siguiente lista de comprobación antes de que la aplicación pase a la fase de producción. El uso de la lista de comprobación impedirá que se produzcan distintos problemas comunes que podrían surgir. Puede diagnosticar rápidamente cuándo se produce un problema:

• Utilice el SDK más reciente. No se debe utilizar la previsualización de SDK en la producción. Esto evitará problemas conocidos que ya están solucionados.
• Revise los consejos de rendimiento y siga las prácticas sugeridas. Esto ayudará a evitar el escalado, la latencia y otros problemas de rendimiento.
• Habilite el registro de SDK para ayudarle a solucionar un problema. La habilitación del registro puede afectar al rendimiento, por lo que es mejor hacerlo solo para solucionar problemas. Puede habilitar los registros siguientes:
  • Registre métricas mediante Azure Portal. Las métricas del portal muestran la telemetría de Azure Cosmos DB, que resulta útil para determinar si el problema corresponde a Azure Cosmos DB o al cliente.
  • Registre la cadena de diagnóstico de las operaciones o excepciones.

Eche un vistazo a la sección Problemas y soluciones de este artículo.

Compruebe que la sección de problemas de GitHub se esté supervisando activamente. Compruebe si encuentra algún problema similar con una solución alternativa ya registrada. Si no logró solucionarlo, registre un problema de GitHub. Puede abrir una incidencia de soporte técnico para problemas urgentes.

Captura de diagnósticos

Todas las respuestas del SDK, incluida CosmosException, tienen una propiedad Diagnostics. Esta propiedad registra toda la información relacionada con la solicitud única, incluidos los reintentos o errores transitorios.

Los diagnósticos se devuelven como una cadena. La cadena cambia con cada versión a medida que se mejora para ofrecer mejores soluciones a los problemas de los distintos escenarios. Con cada versión del SDK, la cadena tendrá cambios importantes en el formato. No analice la cadena para evitar cambios importantes. En el siguiente ejemplo de código se muestra cómo leer los registros de diagnóstico mediante el SDK de .NET:

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

Problemas comunes y soluciones alternativas

Sugerencias generales

• Siga cualquier vínculo aka.ms incluido en los detalles de la excepción.
• Ejecute la aplicación en la misma región de Azure que su cuenta de Azure Cosmos DB, si es posible.
• Es posible que experimente problemas de conectividad o disponibilidad debido a falta de recursos en el equipo cliente. Le recomendamos que supervise el uso de la CPU en los nodos que ejecutan el cliente de Azure Cosmos DB y la escalación vertical u horizontal si están ejecutando una carga alta.

Comprobación de las métricas del portal

La comprobación de las métricas del portal le ayudarán a determinar si hay un problema por parte del cliente o si hay un problema con el servicio. Por ejemplo, si las métricas contienen una alta tasa de solicitudes de velocidad limitada (código de estado HTTP 429), lo que significa que la solicitud se ha limitado, consulte la sección Tasa de solicitudes demasiado grande.

Diseño de reintentos

Consulte nuestra guía para diseñar aplicaciones resistentes con los SDK de Azure Cosmos DB para instrucciones sobre cómo diseñar aplicaciones resistentes y saber cuál es la semántica de reintentos del SDK.

SNAT

Si la aplicación está implementada en Azure Virtual Machines sin una dirección IP pública, los puertos SNAT de Azure se usan de manera predeterminada para establecer conexiones con cualquier punto de conexión fuera de la VM. El número de conexiones permitidas desde la máquina virtual hasta el punto de conexión de Azure Cosmos DB está limitado por la configuración de Azure SNAT. Esta situación puede conducir a la limitación de la conexión, al cierre de la conexión o a los tiempos de espera de solicitudes mencionados anteriormente.

Los puertos SNAT de Azure se usan solo cuando la VM tiene una dirección IP privada y se conecta a una dirección IP pública. Hay dos soluciones alternativas para evitar la limitación de SNAT de Azure (siempre que esté usando una única instancia de cliente en toda la aplicación):

• Agregue el punto de conexión de servicio de Azure Cosmos DB a la subred de la red virtual de Azure Virtual Machines. Para obtener más información, consulte puntos de conexión de servicio de red virtual de Azure.

  Cuando se habilita el punto de conexión de servicio, las solicitudes ya no se envían desde una dirección IP pública a Azure Cosmos DB. En su lugar, se envían la red virtual y la identidad de la subred. Este cambio puede producir caídas de firewall si solo se permiten direcciones IP públicas. Si usa un firewall, cuando se habilite el punto de conexión de servicio, agregue una subred al firewall mediante las ACL de Virtual Network.

• Asigne una dirección IP pública a la VM de Azure.

Latencia de red alta

Consulte nuestra guía de solución de problemas de latencia para obtener más información sobre la solución de problemas de latencia.

Errores de autenticación de proxy

Si ve errores que se muestran como HTTP 407:

Response status code does not indicate success: ProxyAuthenticationRequired (407);

El SDK no genera este error ni procede del servicio Azure Cosmos DB. Se trata de un error relacionado con la configuración de red. Es probable que falte la autenticación de proxy necesaria en un proxy de la configuración de red. Si no espera usar un proxy, póngase en contacto con el equipo de red. Si usa un proxy, asegúrese de establecer la configuración de WebProxy correcta en CosmosClientOptions.WebProxy al crear la instancia de cliente.

Problemas de consulta comunes

Las métricas de consulta le ayudarán a determinar dónde está dedicando más tiempo la consulta. En las métricas de consulta, puede ver la cantidad que se dedica al back-end en comparación con el cliente. Obtenga más información en la guía de rendimiento de consultas.

Si se produce el siguiente error: Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies: y usa Windows, debe actualizar a la versión más reciente de este sistema operativo.

Pasos siguientes

• Obtenga información sobre las instrucciones de rendimiento del SDK para .NET
• Obtenga información sobre los procedimientos recomendados para el SDK de .NET