Partager via

Obtention des métriques d'exécution de requêtes SQL et analyse des performances des requêtes avec le SDK Python pour Azure Cosmos DB

S’APPLIQUE À : NoSQL

Cet article explique comment profiler les performances des requêtes SQL sur Azure Cosmos DB à l’aide des métriques d’exécution des requêtes. Il contient des métriques cumulées provenant de l’ensemble des partitions physiques pour la demande, une liste de métriques pour chaque partition physique et le coût total de la demande. Ces mesures sont décrites plus en détail dans l’article Réglage des performances des requêtes.

Activation des métriques de requête

Pour obtenir les métriques de requête, il faut définir l’indicateur populate_query_metrics sur True dans vos paramètres de requête comme indiqué ci-dessous. Vous pourriez être intéressé par l’activation des métriques d’index à des fins de débogage et vous pouvez l’activer en définissant l’indicateur populate_query_metrics sur True :

results = container.query_items(
    query=queryText,
    enable_cross_partition_query=True,
    populate_index_metrics=True,
    populate_query_metrics=True
)

Obtenir les métriques d’exécution des requêtes

Dans le SDK Python, vous pouvez lire les valeurs de l’en-tête x-ms-documentdb-query-metrics à partir du client de conteneur pour obtenir les métriques d’exécution des requêtes. L’extrait de code suivant montre comment lire les métriques d’exécution des requêtes :

results = container.query_items(
    query=queryText,
    enable_cross_partition_query=True,
    populate_query_metrics=True
)

items = [item for item in results]
'''
Please note that the last_response_headers are available only after the first iteration of the results as the query execution starts only when result iteration begins
'''
print("Query Metrics: ",container.client_connection.last_response_headers['x-ms-documentdb-query-metrics'])

Le résultat vous fournit des informations relatives à l’exécution de la requête comme suit :

totalExecutionTimeInMs=0.27;
queryCompileTimeInMs=0.04;
queryLogicalPlanBuildTimeInMs=0.00;
queryPhysicalPlanBuildTimeInMs=0.02;
queryOptimizationTimeInMs=0.00;
VMExecutionTimeInMs=0.02;
indexLookupTimeInMs=0.00;
instructionCount=17;
documentLoadTimeInMs=0.01;
systemFunctionExecuteTimeInMs=0.00;
userFunctionExecuteTimeInMs=0.00;
retrievedDocumentCount=3;
retrievedDocumentSize=1005;
outputDocumentCount=3;
outputDocumentSize=1056;
writeOutputTimeInMs=0.00;
indexUtilizationRatio=1.00

Les résultats ci-dessus peuvent vous donner des aperçus sur l’efficacité de votre requête. Vous pouvez consulter le totalExecutionTimeInMs pour voir combien de temps la requête a pris pour s’exécuter. L’index UtilizationRatio peut vous donner des aperçus sur la manière dont votre requête utilise l’index. Pour comprendre les métriques en détail, consultez l’article Métriques d’exécution des requêtes.

Obtenir les frais de requêtes d’interrogation

Vous pouvez capturer le nombre total d’unités de requête (RU, Request Units) consommées en lisant la valeur x-ms-request-charge. Vous n’avez pas besoin de définir explicitement de paramètres pour récupérer la valeur des frais de requête. L’exemple suivant montre comment obtenir les frais de requête pour chaque continuation d’une requête :

items = [item for item in results]
print("Request Units consumed: ",container.client_connection.last_response_headers['x-ms-request-charge'])

Obtenir l’utilisation de l’index

L’examen de l’utilisation de l’index peut vous aider à déboguer les requêtes lentes. Un bon score d’utilisation de l’index doit être proche de 1. Les requêtes qui ne peuvent pas utiliser l’index donnent lieu à une analyse complète de tous les documents d’un conteneur avant de renvoyer le jeu de résultats.

Voici un exemple de requête d’analyse :

SELECT VALUE c.description 
FROM   c 
WHERE UPPER(c.description) = "BABYFOOD, DESSERT, FRUIT DESSERT, WITHOUT ASCORBIC ACID, JUNIOR"

Le filtre de cette requête utilise la fonction système UPPER qui n’est pas servie à partir de l’index. L’exécution de cette requête sur une collection volumineuse a généré les métriques de requête suivantes pour la première continuation :

QueryMetrics

Retrieved Document Count                 :          60,951
Retrieved Document Size                  :     399,998,938 bytes
Output Document Count                    :               7
Output Document Size                     :             510 bytes
Index Utilization                        :            0.00 %
Total Query Execution Time               :        4,500.34 milliseconds
Query Preparation Time                   :             0.2 milliseconds
Index Lookup Time                        :            0.01 milliseconds
Document Load Time                       :        4,177.66 milliseconds
Runtime Execution Time                   :           407.9 milliseconds
Document Write Time                      :            0.01 milliseconds

Notez les valeurs suivantes dans la sortie des métriques de requête :

Retrieved Document Count                 :          60,951
Retrieved Document Size                  :     399,998,938 bytes

Cette requête a chargé 60 951 documents totalisant 399 998 938 d’octets. Le chargement d’un tel nombre d’octets a un coût élevé en terme d’unités de requête. L’exécution de la requête prend également beaucoup de temps, comme le montre clairement la propriété de durée totale :

Total Query Execution Time               :        4,500.34 milliseconds

Cela signifie que l’exécution de la requête a pris 4,5 secondes (et il ne s’agissait là que d’une seule continuation).

Pour optimiser cet exemple de requête, évitez d’utiliser la fonction UPPER dans le filtre. Au lieu de cela, lorsque de la création ou de la mise à jour de documents, les valeurs c.description doivent être insérées en caractères majuscules. La requête devient alors :

SELECT VALUE c.description 
FROM   c 
WHERE c.description = "BABYFOOD, DESSERT, FRUIT DESSERT, WITHOUT ASCORBIC ACID, JUNIOR"

Cette requête peut désormais être servie à partir de l’index. Vous pouvez également utiliser des propriétés calculées pour indexer les résultats des fonctions système ou des calculs complexes qui entraîneraient une analyse complète.

Pour consulter les recommandations d’index potentielles et vérifier quels index ont été utilisés, vous devez définir le paramètre populate_index_metrics sur True, puis vous pouvez lire les valeurs de l’en-tête x-ms-documentdb-index-utilization à partir du client de conteneur. L’extrait de code suivant montre comment lire les métriques d’utilisation de l’index :

results = container.query_items(
    query=queryText,
    enable_cross_partition_query=True,
    populate_index_metrics = True
)
items = [item for item in results]
print("Index Utilization Info: ",container.client_connection.last_response_headers['x-ms-cosmos-index-utilization'])

Pour en savoir plus sur le réglage des performances des requêtes, voir l’article Régler les performances des requêtes.

Références

Étapes suivantes