Surveillez les données Azure Cosmos DB à l’aide des paramètres de diagnostic dans Azure

Article
02/21/2024

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 également appelés « journaux du plan 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
- 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.

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.

Connectez-vous au portail Azure.
Accédez à votre compte Azure Cosmos DB. Ouvrez le volet Paramètres de diagnostic sous la section Surveillance, puis sélectionnez 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.

Dans le volet Paramètres de diagnostic, renseignez le formulaire avec vos catégories préférées. Vous trouverez ici la liste des catégories de journaux.

Category	API	Définition	Propriétés de clé
DataPlaneRequests	Recommandé pour l’API pour NoSQL	Consigne les requêtes back-end en tant qu’opérations de plan de données qui sont des requêtes exécutées pour créer, mettre à jour, supprimer ou récupérer des données dans le compte.	`Requestcharge`, `statusCode`, `clientIPaddress`, `partitionID`, `resourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	API pour MongoDB	Journalise les requêtes initiées par l’utilisateur depuis le serveur front-end pour servir des requêtes à Azure Cosmos DB for MongoDB. Quand vous activez cette catégorie, veillez à désactiver DataPlaneRequests.	`Requestcharge`, `opCode`, `retryCount`, `piiCommandText`
CassandraRequests	API pour Apache Cassandra	Consigne les requêtes initiées par l’utilisateur depuis le serveur front-end pour servir des requêtes à Azure Cosmos DB for Cassandra.	`operationName`, `requestCharge`, `piiCommandText`
GremlinRequests	API Apache Gremlin	Consigne les requêtes initiées par l’utilisateur depuis le serveur front-end pour servir des requêtes à Azure Cosmos DB pour Gremlin.	`operationName`, `requestCharge`, `piiCommandText`, `retriedDueToRateLimiting`
QueryRuntimeStatistics	API pour NoSQL	Ce tableau détaille les opérations de requête exécutées sur un compte d’API pour NoSQL. Par défaut, le texte de la requête et ses paramètres sont masqués pour éviter de journaliser les données personnelles avec la journalisation de requête en texte intégral disponible à la demande.	`databasename`, `partitionkeyrangeid`, `querytext`
PartitionKeyStatistics	Toutes les API	Consigne les statistiques des clés de partition logique en représentant la taille de stockage estimée (Ko) des clés de partition. Cette table est utile lors de la résolution des problèmes liés à l’asymétrie du stockage. Ce journal PartitionKeyStatistics est émis uniquement si les conditions suivantes sont remplies : 1. Au moins 1 % des documents de la partition physique ont la même clé de partition logique. 2. Parmi toutes les clés de la partition physique, le journal PartitionKeyStatistics capture les trois premières clés avec la plus grande taille de stockage. Si les conditions précédentes ne sont pas remplies, les données de statistiques de clé de partition ne sont pas disponibles. Il n’est pas grave que les conditions ci-dessus ne soient pas remplies pour votre compte, ce qui indique généralement que vous n’avez pas d’asymétrie d’espace de stockage de partition logique. Remarque : la taille estimée des clés de partition est calculée à l’aide d’une approche d’échantillonnage qui suppose que les documents de la partition physique sont à peu près de la même taille. Si les tailles de document ne sont pas uniformes dans la partition physique, la taille estimée de la clé de partition peut ne pas être exacte.	`subscriptionId`, `regionName`, `partitionKey`, `sizeKB`
PartitionKeyRUConsumption	API pour NoSQL ou API pour Apache Gremlin	Consigne la consommation agrégée de RU/s des clés de partition. Cette table est utile pour le dépannage des partitions à chaud. Actuellement, Azure Cosmos DB signale uniquement des clés de partition pour les comptes d’API pour NoSQL et pour des opérations de lecture/écriture, des requêtes et de procédure stockée du point.	`subscriptionId`, `regionName`, `partitionKey`, `requestCharge`, `partitionKeyRangeId`
ControlPlaneRequests	Toutes les API	Consigne les détails des opérations du plan de contrôle, ce qui comprend la création d’un compte, l’ajout ou la suppression d’une région, la mise à jour des paramètres de réplication du compte, etc.	`operationName`, `httpstatusCode`, `httpMethod`, `region`
TableApiRequests	API pour Table	Consigne les requêtes initiées par l’utilisateur depuis le serveur front-end pour servir des requêtes à Azure Cosmos DB for Table.	`operationName`, `requestCharge`, `piiCommandText`

Après avoir sélectionné vos détails de catégorie, envoyez vos journaux à votre destination préférée. Si vous envoyez des journaux à un espace de travail Log Analytics, assurez-vous de sélectionner Ressource spécifique comme table Destination.

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.

Notes

Si vous utilisez l’API pour NoSQL, nous vous recommandons de définir la propriété export-to-resource-specific sur true.

Créez des variables d’interpréteur de commandes pour subscriptionId, diagnosticSettingName, workspaceName et resourceGroupName.

# Variable for subscription id
subscriptionId="<subscription-id>"

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for workspace name
workspaceName="<workspace-name>"

# Variable for diagnostic setting name
diagnosticSettingName="<diagnostic-setting-name>"

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

az monitor diagnostic-settings create \
    --resource "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDb/databaseAccounts/" \
    --name $diagnosticSettingName \
    --export-to-resource-specific true \
    --logs '[{"category": "QueryRuntimeStatistics","categoryGroup": null,"enabled": true,"retentionPolicy": {"enabled": false,"days": 0}}]' \
    --workspace "/subscriptions/$subscriptionId/resourcegroups/$resourceGroupName/providers/microsoft.operationalinsights/workspaces/$workspaceName"

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

Notes

Si vous utilisez l’API SQL, définissez la propriété logAnalyticsDestinationType sur Dedicated pour activer les tables spécifiques à la ressource.

Créez une requête PUT HTTP.

PUT
https://management.azure.com/{resource-id}/providers/microsoft.insights/diagnosticSettings/service?api-version={api-version}

Utilisez ces en-têtes avec la requête.

Paramètres/en-têtes	Valeur/description
name	Nom de votre paramètre de diagnostic
resourceUri	URI de sous-ressource Microsoft Insights pour le compte Azure Cosmos DB.
api-version	`2017-05-01-preview`
Content-Type	`application/json`

Notes

L’URI de la sous-ressource Microsoft Insights est au format suivant : subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Pour plus d’informations sur les URI de ressources Azure Cosmos DB, consultez Syntaxe de l’URI de ressource pour l’API REST Azure Cosmos DB.

Définissez le corps de la requête sur cette charge utile JSON.

{
    "id": "/subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}",
    "type": "Microsoft.Insights/diagnosticSettings",
    "name": "name",
    "location": null,
    "kind": null,
    "tags": null,
    "properties": {
        "storageAccountId": null,
        "serviceBusRuleId": null,
        "workspaceId": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups/{RESOURCE_GROUP}/providers/microsoft.operationalinsights/workspaces/{WORKSPACE_NAME}",
        "eventHubAuthorizationRuleId": null,
        "eventHubName": null,
        "logs": [
            {
                "category": "DataPlaneRequests",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "QueryRuntimeStatistics",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "PartitionKeyStatistics",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "PartitionKeyRUConsumption",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "ControlPlaneRequests",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            }
        ],
        "logAnalyticsDestinationType": "Dedicated"
    },
    "identity": null
}

Ici, utilisez un modèle Azure Resource Manager (ARM) pour créer un paramètre de diagnostic.

Notes

Définissez la propriété logAnalyticsDestinationType sur Dedicated pour activer les tables propres aux ressources.

Créez le fichier de modèle JSON suivant afin de déployer les paramètres 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": {
    "settingName": {
      "type": "string",
      "metadata": {
        "description": "The name of the diagnostic setting."
      }
    },
    "dbName": {
      "type": "string",
      "metadata": {
        "description": "The name of the database."
      }
    },
    "workspaceId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the workspace."
      }
    },
    "storageAccountId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the storage account."
      }
    },
    "eventHubAuthorizationRuleId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the event hub authorization rule."
      }
    },
    "eventHubName": {
      "type": "string",
      "metadata": {
        "description": "The name of the event hub."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Insights/diagnosticSettings",
      "apiVersion": "2021-05-01-preview",
      "scope": "[format('Microsoft.DocumentDB/databaseAccounts/{0}', parameters('dbName'))]",
      "name": "[parameters('settingName')]",
      "properties": {
        "workspaceId": "[parameters('workspaceId')]",
        "storageAccountId": "[parameters('storageAccountId')]",
        "eventHubAuthorizationRuleId": "[parameters('eventHubAuthorizationRuleId')]",
        "eventHubName": "[parameters('eventHubName')]",
        "logAnalyticsDestinationType": "[parameters('logAnalyticsDestinationType')]",
        "logs": [
          {
            "category": "DataPlaneRequests",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "MongoRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "QueryRuntimeStatistics",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "PartitionKeyStatistics",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "PartitionKeyRUConsumption",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "ControlPlaneRequests",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "CassandraRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "GremlinRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "TableApiRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          }
        ],
        "metrics": [
          {
            "timeGrain": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            },
            "category": "Requests"
          }
        ]
      }
    }
  ]
}

Créez le fichier de paramètres JSON suivant à l’aide des paramètres appropriés pour votre ressource Azure Cosmos DB.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "settingName": {
      "value": "{DIAGNOSTIC_SETTING_NAME}"
    },
    "dbName": {
      "value": "{ACCOUNT_NAME}"
    },
    "workspaceId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups/{RESOURCE_GROUP}/providers/microsoft.operationalinsights/workspaces/{WORKSPACE_NAME}"
    },
    "storageAccountId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.Storage/storageAccounts/{STORAGE_ACCOUNT_NAME}"
    },
    "eventHubAuthorizationRuleId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups{RESOURCE_GROUP}/providers/Microsoft.EventHub/namespaces/{EVENTHUB_NAMESPACE}/authorizationrules/{EVENTHUB_POLICY_NAME}"
    },
    "eventHubName": {
      "value": "{EVENTHUB_NAME}"
    },
    "logAnalyticsDestinationType": {
      "value": "Dedicated"
    }
  }
}

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

az deployment group create \
    --resource-group <resource-group-name> \
    --template-file <path-to-template>.json \
    --parameters @<parameters-file-name>.json

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

Notes

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 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.

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

Pour activer cette fonctionnalité, accédez à la page Features de votre compte Azure Cosmos DB.
Sélectionnez Enable. Ce paramètre est appliqué en quelques minutes. Tous les journaux nouvellement ingérés comportent le texte intégral ou PIICommand pour chaque demande.

Vérifiez que vous êtes connecté à Azure CLI. Pour plus d’informations, consultez Se connecter avec Azure CLI. Si vous le souhaitez, vérifiez que vous avez configuré l’abonnement actif pour votre interface CLI. Consultez Modifier l’abonnement Azure CLI actif pour plus d’informations.

Créez des variables d’interpréteur de commandes pour accountName et resourceGroupName.

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for account name
accountName="<account-name>"

Obtenez l’identificateur unique de votre compte existant à l’aide de az show.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query id

Stockez l’identifiant unique dans une variable shell nommée $uri.

uri=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query id \
        --output tsv
)

Interrogez la ressource à l’aide de l’API REST et az rest avec un verbe HTTP GET pour vérifier si la requête de texte intégral est déjà activée.

az rest \
    --method GET \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --query "{accountName:name,fullTextQuery:{state:properties.diagnosticLogSettings.enableFullTextQuery}}"

Si la requête de texte intégral n’est pas activée, la sortie est similaire à celle de l’exemple suivant.

{
  "accountName": "<account-name>",
  "fullTextQuery": {
    "state": "None"
  }
}

Si la requête de texte intégral n’est pas déjà activée, activez-la à nouveau avec az rest, un verbe HTTP PATCH et une charge utile JSON.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Notes

Si vous utilisez Azure CLI dans une invite PowerShell, vous devez échapper les guillemets doubles avec une barre oblique inverse (\).

Attendez quelques minutes que l’opération se termine. Vérifiez l’état de la requête de texte intégral en utilisant az rest à nouveau.

az rest \
    --method GET \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --query "{accountName:name,fullTextQuery:{state:properties.diagnosticLogSettings.enableFullTextQuery}}"

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

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

Interroger des données

Pour savoir comment interroger à l’aide de ces fonctionnalités nouvellement activées, consultez :

Étapes suivantes

Supervision des informations de référence sur les données Azure Cosmos DB

Surveillez les données Azure Cosmos DB à l’aide des paramètres de diagnostic dans Azure

Prérequis

Créer des paramètres de diagnostic

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

Interroger des données

Étapes suivantes

Ressources supplémentaires