Surveiller les données Azure Cosmos DB en utilisant les paramètres de diagnostic Log Analytics Azure Monitor

S’APPLIQUE À : NoSQL MongoDB Cassandra Gremlin Table

Les paramètres de diagnostic dans Azure sont utilisés pour collecter les journaux des ressources. Les ressources émettent des journaux de ressources Azure et fournissent des données riches et fréquentes sur le fonctionnement de cette ressource. Ces journaux sont capturés par requête et sont appelés « journaux de plans de données ». Les opérations Delete, Insert et readFeed sont des exemples d’opérations de plan de données. Le contenu de ces journaux d’activité varie en fonction du type de ressource.

Les indicateurs de performance de la plateforme et le journal d’activité sont collectés automatiquement, mais vous devez créer un paramètre de diagnostic pour collecter les journaux des ressources ou les transférer en dehors d’Azure Monitor. Vous pouvez activer le paramètre de diagnostic pour les comptes Azure Cosmos DB et envoyer les journaux des ressources aux sources suivantes :

• Espaces de travail Log Analytics Azure Monitor
  • Les données envoyées à Log Analytics peuvent être écrites dans des tables Diagnostics Azure (héritées) ou Spécifique à la ressource (préversion)
• Event Hub
• Compte de stockage

Notes

Nous vous recommandons de créer le paramètre de diagnostic en mode Spécifique (pour toutes les API à l’exception de l’API pour Table) à la ressource en suivant les instructions de création d’un paramètre de diagnostic via l’API REST. Cette option fournit des optimisations de coût supplémentaires grâce à une vue améliorée de la gestion des données.

Prérequis

• Compte Azure Cosmos DB existant.
  • Si vous n’avez pas d’abonnement Azure, créez-en un.
  • Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
  • Vous pouvez également essayer Azure Cosmos DB gratuitement avant de vous engager.
• Un espace de travail Log Analytics Azure Monitor existant.

Avertissement

Si vous devez supprimer une ressource, renommer ou déplacer une ressource, ou la migrer parmi des groupes de ressources ou des abonnements, supprimez d’abord ses paramètres de diagnostic. Sinon, si vous recréez cette ressource, les paramètres de diagnostic de la ressource supprimée peuvent être inclus avec la nouvelle ressource, en fonction de la configuration de la ressource pour chaque ressource. Si les paramètres de diagnostic sont inclus avec la nouvelle ressource, cela reprend la collecte des journaux de ressources tel que défini dans le paramètre de diagnostic et envoie les données de métrique et de journal applicables à la destination configurée précédemment.

En outre, il est recommandé de supprimer les paramètres de diagnostic d’une ressource que vous allez supprimer et de ne pas planifier d’utiliser à nouveau pour garder votre environnement propre.

Créer des paramètres de diagnostic

Ici, nous suivons étape par étape l’ensemble du processus de création des paramètres de diagnostic pour votre compte.

Remarque

La métrique pour les journaux d’exportation en tant que catégorie n’est actuellement pas prise en charge.

Azure portal

1. Connectez-vous au portail Azure.

2. Accédez à votre compte Azure Cosmos DB existant.

3. Dans la section Surveillance du menu des ressources, sélectionnez Paramètres de diagnostic. Sélectionnez ensuite l’option Ajouter un paramètre de diagnostic.

   

   Important

   Vous pouvez voir une invite pour « activer la requête de texte intégral [...] pour une journalisation plus détaillée » si la fonctionnalité requête de texte intégral n’est pas activée dans votre compte. Vous pouvez ignorer cet avertissement en toute sécurité si vous ne souhaitez pas l’activer. Pour plus d’informations, consultez Activer une requête de texte intégral.

4. Dans le volet Paramètres de diagnostic, nommez le paramètre exemple-paramètre, puis sélectionnez la catégorie QueryRuntimeStatistics. Envoyez les journaux à un Espace de travail Log Analytics en sélectionnant votre espace de travail existant. Enfin, sélectionnez Spécifique à la ressource comme option de destination.

   

Azure CLI

Pour créer un paramètre de diagnostic avec Azure CLI, utilisez la commande az monitor diagnostic-settings create. Pour une description des paramètres de cette commande, consultez sa documentation.

1. Vérifiez que vous êtes connecté à Azure CLI. Pour plus d’informations, consultez Se connecter avec Azure CLI.

2. Utilisez az monitor diagnostic-settings create pour créer le paramètre.

   az monitor diagnostic-settings create \
     --resource $(az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     ) \
     --workspace $(az monitor log-analytics workspace show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     ) \
     --name "example-setting" \
     --export-to-resource-specific true \
     --logs '[
       {
         "category": "QueryRuntimeStatistics",
         "enabled": true
       }
     ]'
   

   Important

   Cet exemple utilise l’argument --export-to-resource-specific pour activer des tables spécifiques à la ressource.

3. Passez en revue les résultats de la création de votre nouveau paramètre en utilisant az monitor diagnostics-settings show.

   az monitor diagnostic-settings show \
     --name "example-setting" \
     --resource $(az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     )
   

REST API

Utilisez l’API REST Azure Monitor pour créer un paramètre de diagnostic via la console interactive.

1. Vérifiez que vous êtes connecté à Azure CLI. Pour plus d’informations, consultez Se connecter avec Azure CLI.

2. Créez le paramètre de diagnostic pour votre ressource Azure Cosmos DB en utilisant une requête HTTP PUT et az rest.

   diagnosticSettingName="example-setting"
   
   resourceId=$(az cosmosdb show \
     --resource-group "<resource-group-name>" \
     --name "<account-name>" \
     --query "id" \
     --output "tsv" \
   )
   
   workspaceId=$(az monitor log-analytics workspace show \
     --resource-group "<resource-group-name>" \
     --name "<account-name>" \
     --query "id" \
     --output "tsv" \
   )
   
   az rest \
     --method "PUT" \
     --url "$resourceId/providers/Microsoft.Insights/diagnosticSettings/$diagnosticSettingName" \
     --url-parameters "api-version=2021-05-01-preview" \
     --body '{
       "properties": {
         "workspaceId": "'"$workspaceId"'",
         "logs": [
           {
             "category": "QueryRuntimeStatistics",
             "enabled": true
           }
         ],
         "logAnalyticsDestinationType": "Dedicated"
       }
     }'
   

   Important

   Cet exemple définit la propriété logAnalyticsDestinationType sur Dedicated pour activer les tables spécifiques à la ressource.

3. Réutilisez az rest avec un verbe HTTP GET pour obtenir les propriétés du paramètre de diagnostic.

   diagnosticSettingName="example-setting"
   
   resourceId=$(az cosmosdb show \
     --resource-group "<resource-group-name>" \
     --name "<account-name>" \
     --query "id" \
     --output "tsv" \
   )
   
   az rest \
     --method "GET" \
     --url "$resourceId/providers/Microsoft.Insights/diagnosticSettings/$diagnosticSettingName" \
     --url-parameters "api-version=2021-05-01-preview"
   

Bicep

Utilisez un modèle Bicep pour créer le paramètre de diagnostic.

1. Vérifiez que vous êtes connecté à Azure CLI. Pour plus d’informations, consultez Se connecter avec Azure CLI.

2. Créez un nouveau fichier appelé diagnosticSetting.bicep.

3. Entrez le contenu suivant du modèle Bicep qui déploie le paramètre de diagnostic pour votre ressource Azure Cosmos DB.

   @description('The name of the diagnostic setting to create.')
   param diagnosticSettingName string = 'example-setting'
   
   @description('The name of the Azure Cosmos DB account to monitor.')
   param azureCosmosDbAccountName string
   
   @description('The name of the Azure Monitor Log Analytics workspace to use.')
   param logAnalyticsWorkspaceName string
   
   resource azureCosmosDbAccount 'Microsoft.DocumentDB/databaseAccounts@2021-06-15' existing = {
     name: azureCosmosDbAccountName
   }
   
   resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' existing = {
     name: logAnalyticsWorkspaceName
   }
   
   resource diagnosticSetting 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = {
     name: diagnosticSettingName
     scope: azureCosmosDbAccount
     properties: {
       workspaceId: logAnalyticsWorkspace.id
       logAnalyticsDestinationType: 'Dedicated'
       logs: [
         {
           category: 'QueryRuntimeStatistics'
           enabled: true
         }
       ]
     }
   }    
   

   Important

   Cet exemple définit la propriété logAnalyticsDestinationType sur Dedicated pour activer les tables spécifiques à la ressource.

4. Déployez le modèle en utilisant az deployment group create.

   az deployment group create \
       --resource-group "<resource-group-name>" \
       --template-file diagnosticSetting.bicep \
       --parameters \
         azureCosmosDbAccountName="<azure-cosmos-db-account-name>" \
         logAnalyticsWorkspaceName="<log-analytics-workspace-name>"
   

   Conseil

   Utilisez la commande az bicep build pour convertir le modèle Bicep en modèle Azure Resource Manager.

Modèle ARM

Utilisez un modèle Azure Resource Manager pour créer le paramètre de diagnostic.

1. Vérifiez que vous êtes connecté à Azure CLI. Pour plus d’informations, consultez Se connecter avec Azure CLI.

2. Créez un nouveau fichier appelé diagnosticSetting.bicep.

3. Entrez le contenu suivant du modèle Azure Resource Manager qui déploie le paramètre de diagnostic pour votre ressource Azure Cosmos DB.

   {
     "$schema": "<https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#>",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "diagnosticSettingName": {
         "type": "string",
         "defaultValue": "example-setting",
         "metadata": {
           "description": "The name of the diagnostic setting to create."
         }
       },
       "azureCosmosDbAccountName": {
         "type": "string",
         "metadata": {
           "description": "The name of the Azure Cosmos DB account to monitor."
         }
       },
       "logAnalyticsWorkspaceName": {
         "type": "string",
         "metadata": {
           "description": "The name of the Azure Monitor Log Analytics workspace to use."
         }
       }
     },
     "resources": [
       {
         "type": "Microsoft.Insights/diagnosticSettings",
         "apiVersion": "2021-05-01-preview",
         "scope": "[format('Microsoft.DocumentDB/databaseAccounts/{0}', parameters('azureCosmosDbAccountName'))]",
         "name": "[parameters('diagnosticSettingName')]",
         "properties": {
           "workspaceId": "[resourceId('Microsoft.OperationalInsights/workspaces', parameters('logAnalyticsWorkspaceName'))]",
           "logAnalyticsDestinationType": "Dedicated",
           "logs": [
             {
               "category": "QueryRuntimeStatistics",
               "enabled": true
             }
           ]
         }
       }
     ]
   }
   

   Important

   Cet exemple définit la propriété logAnalyticsDestinationType sur Dedicated pour activer les tables spécifiques à la ressource.

4. Déployez le modèle en utilisant az deployment group create.

   az deployment group create \
       --resource-group "<resource-group-name>" \
       --template-file azuredeploy.json \
       --parameters \
         azureCosmosDbAccountName="<azure-cosmos-db-account-name>" \
         logAnalyticsWorkspaceName="<log-analytics-workspace-name>"
   

   Conseil

   Utilisez la commande az bicep decompile pour convertir le modèle Azure Resource Manager en modèle Bicep.

Activer la requête de texte intégral pour la journalisation du texte de la requête

Azure Cosmos DB fournit une journalisation avancée pour une résolution des problèmes détaillée. En activant la requête de texte intégral, vous pouvez voir la requête désobfusquée pour toutes les demandes au sein de votre compte Azure Cosmos DB. Vous autorisez également Azure Cosmos DB à accéder à ces données et à les exposer dans vos journaux.

Avertissement

L’activation de cette fonctionnalité peut entraîner des coûts de journalisation supplémentaires. Pour plus d’informations sur la tarification, consultez la tarification Azure Monitor. Il est recommandé de désactiver cette fonctionnalité après le dépannage.

Azure portal

1. Dans la page du compte Azure Cosmos DB existant, sélectionnez l’option Fonctionnalités dans la section Paramètres du menu de ressources. Sélectionnez ensuite la fonctionnalité Requête de texte intégral des diagnostics.

   

2. Dans la boîte de dialogue, sélectionnez Enable. Ce paramètre est appliqué en quelques minutes. Tous les journaux nouvellement ingérés comportent maintenant le texte intégral ou PIICommand pour chaque demande.

   

Azure CLI / API REST / Bicep / Modèle ARM

Utilisez Azure CLI pour activer la requête de texte intégral pour votre compte Azure Cosmos DB.

1. Activez la requête de texte intégral en réutilisant az rest avec un verbe HTTP PATCH et une charge utile JSON.

   az rest \
     --method "PATCH" \
     --url $(az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     ) \
     --url-parameters "api-version=2021-05-01-preview" \
     --body '{
       "properties": {
         "diagnosticLogSettings": {
           "enableFullTextQuery": "True"
         }
       }
     }'
   

2. Attendez quelques minutes que l’opération se termine. Vérifiez l’état de la requête de texte intégral en réutilisant az rest avec HTTP GET.

   az rest \
     --method "GET" \
     --url $(az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "id" \
       --output "tsv" \
     ) \
     --url-parameters "api-version=2021-05-01-preview" \
     --query "{accountName:name,fullTextQueryEnabled:properties.diagnosticLogSettings.enableFullTextQuery}"
   

   La sortie doit être similaire à l’exemple suivant.

   {
     "accountName": "<account-name>",
     "fullTextQueryEnabled": "True"
   }
   

Contenu connexe

• Requêtes de diagnostic dans l’API pour NoSQL
• Requêtes de diagnostic dans l’API pour MongoDB
• Requêtes de diagnostic dans l’API pour Apache Cassandra