Azure Cosmos DB-gegevens bewaken met behulp van de diagnostische instellingen in Azure

Artikel
10/30/2023

VAN TOEPASSING OP: Nosql MongoDB Cassandra Gremlin Tabel

Diagnostische instellingen in Azure worden gebruikt om resourcelogboeken te verzamelen. Resources verzenden Azure-resourcelogboeken en bieden uitgebreide, frequente gegevens over de werking van die resource. Deze logboeken worden vastgelegd per aanvraag en worden ook wel 'gegevensvlaklogboeken' genoemd. Enkele voorbeelden van de gegevensvlakbewerkingen zijn verwijderen, invoegen en readFeed. De inhoud van deze logboeken verschilt per resourcetype.

Metrische platformgegevens en activiteitenlogboeken worden automatisch verzameld, terwijl u een diagnostische instelling moet maken om resourcelogboeken te verzamelen of door te sturen buiten Azure Monitor. U kunt de diagnostische instelling voor Azure Cosmos DB-accounts inschakelen en resourcelogboeken naar de volgende bronnen verzenden:

Log Analytics-werkruimten
- Gegevens die naar Log Analytics worden verzonden, kunnen worden geschreven naar Azure Diagnostics-tabellen (verouderd) of resourcespecifieke (preview) -tabellen
Event Hub
Opslagaccount

Notitie

We raden u aan om de diagnostische instelling te maken in de resourcespecifieke modus (voor alle API's behalve API voor Table) volgens onze instructies voor het maken van diagnostische instellingen via REST API. Deze optie biedt extra kostenoptimalisaties met een verbeterde weergave voor het verwerken van gegevens.

Vereisten

Een bestaand Azure Cosmos DB-account.
- Als u een Azure-abonnement hebt, maakt u een nieuw account.
- Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.
- U kunt azure Cosmos DB ook gratis proberen voordat u zich doorvoert.

Diagnostische instellingen maken

Hier doorlopen we het proces voor het maken van diagnostische instellingen voor uw account.

Meld u aan bij de Azure-portal.
Navigeer naar uw Azure Cosmos DB-account. Open het deelvenster Diagnostische instellingen onder de sectie Bewaking en selecteer vervolgens de optie Diagnostische instelling toevoegen.

Belangrijk

Mogelijk ziet u een prompt voor het inschakelen van een volledige tekstquery [...] voor gedetailleerdere logboekregistratie' als de functie voor volledige tekstquery's niet is ingeschakeld in uw account. U kunt deze waarschuwing veilig negeren als u deze functie niet wilt inschakelen. Zie Volledige-tekstquery inschakelen voor meer informatie.

Vul in het deelvenster Diagnostische instellingen het formulier in met de gewenste categorieën. Hier volgt een lijst met logboekcategorieën.

Categorie	API	Definitie	Belangrijke eigenschappen
DataPlaneRequests	Aanbevolen voor API voor NoSQL	Registreert back-endaanvragen als gegevensvlakbewerkingen. Dit zijn aanvragen die worden uitgevoerd om gegevens in het account te maken, bij te werken, te verwijderen of op te halen.	`RequestchargeclientIPaddress`, `statusCode`, `partitionIDresourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	API voor MongoDB	Registreert door de gebruiker geïnitieerde aanvragen van de front-end om aanvragen naar Azure Cosmos DB voor MongoDB te verwerken. Wanneer u deze categorie inschakelt, moet u DataPlaneRequests uitschakelen.	`Requestcharge`, , , `opCoderetryCountpiiCommandText`
CassandraRequests	API voor Apache Cassandra	Registreert door de gebruiker geïnitieerde aanvragen van de front-end om aanvragen naar Azure Cosmos DB voor Cassandra te verwerken.	`operationName`, , `requestChargepiiCommandText`
GremlinRequests	API voor Apache Gremlin	Registreert door de gebruiker geïnitieerde aanvragen van de front-end om aanvragen naar Azure Cosmos DB voor Gremlin te verwerken.	`operationName`, , , `requestChargepiiCommandTextretriedDueToRateLimiting`
QueryRuntimeStatistics	API voor NoSQL	Deze tabel bevat querybewerkingen die worden uitgevoerd op basis van een API voor NoSQL-account. Standaard worden de querytekst en de bijbehorende parameters verborgen om te voorkomen dat persoonlijke gegevens in logboekregistratie worden opgenomen met logboekregistratie van volledige tekstquery's die beschikbaar zijn op aanvraag.	`databasename`, , `partitionkeyrangeidquerytext`
PartitionKeyStatistics	Alle API's	Registreert de statistieken van logische partitiesleutels door de geschatte opslaggrootte (KB) van de partitiesleutels weer te geven. Deze tabel is handig bij het oplossen van scheeftrekken van opslag. Dit logboek PartitionKeyStatistics wordt alleen verzonden als aan de volgende voorwaarden wordt voldaan: 1. Ten minste 1% van de documenten in de fysieke partitie hebben dezelfde logische partitiesleutel. 2. Uit alle sleutels in de fysieke partitie legt het logboek PartitionKeyStatistics de bovenste drie sleutels met de grootste opslaggrootte vast. Als niet aan de vorige voorwaarden wordt voldaan, zijn de gegevens van de partitiesleutelstatistieken niet beschikbaar. Het is geen probleem als aan de bovenstaande voorwaarden voor uw account wordt voldaan, wat meestal aangeeft dat u geen scheeftrekken van logische partitieopslag hebt. Opmerking: De geschatte grootte van de partitiesleutels wordt berekend met behulp van een steekproefbenadering die ervan uitgaat dat de documenten in de fysieke partitie ongeveer dezelfde grootte hebben. Als de documentgrootten niet uniform zijn in de fysieke partitie, is de geschatte partitiesleutelgrootte mogelijk niet nauwkeurig.	`subscriptionId`, , , `regionNamepartitionKeysizeKB`
PartitionKeyRUConsumption	API voor NoSQL of API voor Apache Gremlin	Registreert het geaggregeerde RU/s-verbruik per seconde van partitiesleutels. Deze tabel is handig voor het oplossen van problemen met dynamische partities. Momenteel rapporteert Azure Cosmos DB alleen partitiesleutels voor API voor NoSQL-accounts en voor puntlees-/schrijf-, query- en opgeslagen procedurebewerkingen.	`subscriptionIdpartitionKey`, `regionName`, `requestChargepartitionKeyRangeId`
ControlPlaneRequests	Alle API's	Registreert details over besturingsvlakbewerkingen, waaronder het maken van een account, het toevoegen of verwijderen van een regio, het bijwerken van accountreplicatie-instellingen, enzovoort.	`operationName`, , , `httpstatusCodehttpMethodregion`
TableApiRequests	API voor Table	Registreert door de gebruiker geïnitieerde aanvragen van de front-end voor het verwerken van aanvragen naar Azure Cosmos DB for Table.	`operationName`, , `requestChargepiiCommandText`

Nadat u de details van categorieën hebt geselecteerd, verzendt u uw logboeken naar uw favoriete bestemming. Als u logboeken naar een Log Analytics-werkruimte verzendt, selecteert u Resourcespecifiek als doeltabel.

Gebruik de opdracht az monitor diagnostic-settings create om een diagnostische instelling te maken met de Azure CLI. Raadpleeg de documentatie voor deze opdracht voor beschrijvingen van de parameters.

Notitie

Als u API voor NoSQL gebruikt, raden we u aan om de eigenschap export-to-resource-specific in te stellen op true.

Shell-variabelen maken voor subscriptionId, diagnosticSettingNameworkspaceName en 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>"

Gebruik az monitor diagnostic-settings create dit om de instelling te maken.

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"

Gebruik de Azure Monitor REST API voor het maken van een diagnostische instelling via de interactieve console.

Notitie

Het is raadzaam om de eigenschap logAnalyticsDestinationType in te stellen op Dedicated voor het inschakelen van resourcespecifieke tabellen.

Maak een HTTP-aanvraag PUT .

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

Gebruik deze headers met de aanvraag.

Parameters/headers	Waarde/beschrijving
name	De naam van uw diagnostische instelling.
resourceUri	Microsoft Insights-subresource-URI voor Azure Cosmos DB-account.
api-version	`2017-05-01-preview`
Content-Type	`application/json`

Notitie

De URI voor de Microsoft Insights-subresource heeft deze indeling: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Zie de syntaxis van resource-URI's van Azure Cosmos DB voor Azure Cosmos DB REST API voor meer informatie over azure Cosmos DB-resource-URI's.

Stel de hoofdtekst van de aanvraag in op deze JSON-nettolading.

{
    "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
}

Gebruik hier een ARM-sjabloon (Azure Resource Manager) om een diagnostische instelling te maken.

Notitie

Stel de eigenschap logAnalyticsDestinationType in op Dedicated om resourcespecifieke tabellen in te schakelen.

Maak het volgende JSON-sjabloonbestand om diagnostische instellingen voor uw Azure Cosmos DB-resource te implementeren.

{
  "$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"
          }
        ]
      }
    }
  ]
}

Maak het volgende JSON-parameterbestand met instellingen die geschikt zijn voor uw Azure Cosmos DB-resource.

{
  "$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"
    }
  }
}

Implementeer de sjabloon met behulp van az deployment group create.

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

Volledige-tekstquery inschakelen voor querytekst voor logboekregistratie

Notitie

Als u deze functie inschakelt, kan dit leiden tot extra logboekregistratiekosten. Ga naar de prijzen van Azure Monitor voor prijsinformatie. Het wordt aanbevolen deze functie uit te schakelen na het oplossen van problemen.

Azure Cosmos DB biedt geavanceerde logboekregistratie voor gedetailleerde probleemoplossing. Door een volledige-tekstquery in te schakelen, kunt u de niet-verborgen query voor alle aanvragen in uw Azure Cosmos DB-account weergeven. U geeft ook toestemming voor Azure Cosmos DB om deze gegevens in uw logboeken te openen en weer te geven.

Azure-portal
Azure CLI/REST API/ARM-sjabloon

Als u deze functie wilt inschakelen, gaat u naar de Features pagina in uw Azure Cosmos DB-account.
Selecteer Enable. Deze instelling wordt binnen een paar minuten toegepast. Alle nieuw opgenomen logboeken hebben de volledige tekst of PIICommand-tekst voor elke aanvraag.

Zorg ervoor dat u bent aangemeld bij de Azure CLI. Zie aanmelden met Azure CLI voor meer informatie. Zorg er desgewenst voor dat u het actieve abonnement voor uw CLI hebt geconfigureerd. Zie Het actieve Azure CLI-abonnement wijzigen voor meer informatie.

Shell-variabelen maken voor accountName en resourceGroupName.

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

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

Haal de unieke id voor uw bestaande account op met behulp van az show.

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

Sla de unieke id op in een shellvariabele met de naam $uri.

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

Voer een query uit op de resource met behulp van de REST API en az rest een HTTP-werkwoord GET om te controleren of de volledige-tekstquery al is ingeschakeld.

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

Als een query voor volledige tekst niet is ingeschakeld, is de uitvoer vergelijkbaar met dit voorbeeld.

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

Als de query voor volledige tekst nog niet is ingeschakeld, schakelt u deze az rest opnieuw in met een HTTP-woord PATCH en een JSON-nettolading.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Notitie

Als u Azure CLI in een PowerShell-prompt gebruikt, moet u de dubbele aanhalingstekens escapen met behulp van een backslash (\teken).

Wacht enkele minuten totdat de bewerking is voltooid. Controleer de status van de volledige-tekstquery opnieuw met behulp van az rest .

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

De uitvoer moet vergelijkbaar zijn met dit voorbeeld.

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

Querygegevens

Zie voor meer informatie over het uitvoeren van query's met deze nieuwe functies:

Volgende stappen

Azure Cosmos DB-gegevensreferentie bewaken

Azure Cosmos DB-gegevens bewaken met behulp van de diagnostische instellingen in Azure

Vereisten

Diagnostische instellingen maken

Volledige-tekstquery inschakelen voor querytekst voor logboekregistratie

Querygegevens

Volgende stappen

Aanvullende resources