Überwachen der Azure Cosmos DB-Daten mithilfe der Diagnoseeinstellungen in Azure

Artikel
02/18/2024

GILT FÜR: NoSQL MongoDB Cassandra Gremlin Tabelle

Diagnoseeinstellungen in Azure werden zum Sammeln von Ressourcenprotokollen verwendet. Ressourcen geben Azure-Ressourcenprotokolle aus und liefern umfangreiche und regelmäßige Daten über den Betrieb der jeweiligen Ressource. Diese Protokolle werden pro Anforderung erfasst und werden auch als „Datenebenenprotokolle“ bezeichnet“. Einige Beispiele für Datenebenenvorgänge sind „delete“, „insert“ und „readFeed“. Der Inhalt dieser Protokolle variiert je nach Ressourcentyp.

Plattformmetriken und das Aktivitätsprotokoll werden automatisch gesammelt, aber Sie müssen eine Diagnoseeinstellung erstellen, um Ressourcenprotokolle zu sammeln oder außerhalb von Azure Monitor weiterzuleiten. Sie können die Diagnoseeinstellung für Azure Cosmos DB-Konten aktivieren und Ressourcenprotokolle an die folgenden Quellen senden:

Log Analytics-Arbeitsbereiche
- An Log Analytics gesendete Daten können in Azure-Diagnosetabellen (Legacy) oder ressourcenspezifische Tabellen (Vorschau) geschrieben werden
Event Hub
Speicherkonto

Hinweis

Sie sollten die Diagnoseeinstellung (für alle APIs außer der API für Table) im ressourcenspezifischen Modus erstellen. Befolgen Sie dazu unsere Anweisungen zum Erstellen der Diagnoseeinstellung über die REST-API. Diese Option bietet zusätzliche Kostenoptimierungen mit einer verbesserten Ansicht für die Verarbeitung von Daten.

Voraussetzungen

Ein vorhandenes Azure Cosmos DB-Konto
- Falls Sie bereits über ein Azure-Abonnement verfügen, erstellen Sie ein neues Konto.
- Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
- Alternativ können Sie Azure Cosmos DB kostenlos testen, bevor Sie sich festlegen.

Erstellen von Diagnoseeinstellungen

Hier erfahren Sie mehr über den Prozess Diagnoseeinstellungen für Ihr Konto zu erstellen.

Melden Sie sich beim Azure-Portal an.
Navigieren Sie zu Ihrem Azure Cosmos DB-Konto. Öffnen Sie den Bereich Diagnoseeinstellungen im Überwachungsabschnitt, und wählen Sie dann die Option Diagnoseeinstellung hinzufügen aus.

Wichtig

Möglicherweise wird die Eingabeaufforderung „Volltextabfrage [...] zur detaillierteren Protokollierung aktivieren“ angezeigt, wenn die Funktion Volltextabfrage in Ihrem Konto nicht aktiviert ist. Sie können diese Warnung bedenkenlos ignorieren, wenn Sie diese Funktion nicht aktivieren möchten. Weitere Informationen finden Sie unter Aktivieren der Volltextabfrage.

Geben Sie im Bereich Diagnoseeinstellungen Ihre bevorzugten Kategorien in das Formular ein. Hier ist eine Liste der Protokollkategorien enthalten.

Kategorie	API	Definition	Schlüsseleigenschaften
DataPlaneRequests	Empfohlen für API für NoSQL	Protokolliert Back-End-Anforderungen als Vorgänge auf Datenebene. Dabei handelt es sich um Anforderungen zum Erstellen, Aktualisieren, Löschen oder Abrufen von Daten innerhalb des Kontos.	`Requestcharge`, `statusCode`, `clientIPaddress`, `partitionID`, `resourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	API für MongoDB	Protokolliert vom Benutzer initiierte Anforderungen vom Front-End zur Verarbeitung von Anforderungen an Azure Cosmos DB für MongoDB. Wenn Sie diese Kategorie aktivieren, muss DataPlaneRequests deaktiviert werden.	`Requestcharge`, `opCode`, `retryCount`, `piiCommandText`
CassandraRequests	API für Apache Cassandra	Protokolliert vom Benutzer initiierte Anforderungen vom Front-End zur Verarbeitung von Anforderungen an Azure Cosmos DB für Cassandra.	`operationName`, `requestCharge`, `piiCommandText`
GremlinRequests	API für Apache Gremlin	Protokolliert vom Benutzer initiierte Anforderungen vom Front-End zur Verarbeitung von Anforderungen an Azure Cosmos DB für Gremlin.	`operationName`, `requestCharge`, `piiCommandText`, `retriedDueToRateLimiting`
QueryRuntimeStatistics	API für NoSQL	In dieser Tabelle sind die Abfragevorgänge aufgeführt, die für ein API für NoSQL-Konto ausgeführt wurden. Der Abfragetext und seine Parameter werden standardmäßig verborgen. Auf diese Weise wird verhindert, dass personenbezogene Informationen mit der Volltextabfrageprotokollierung protokolliert werden, die auf Anforderung verfügbar ist.	`databasename`, `partitionkeyrangeid`, `querytext`
PartitionKeyStatistics	Alle APIs	Protokolliert die Statistiken von logischen Partitionsschlüsseln, indem die geschätzte Speichergröße (KB) der Partitionsschlüssel dargestellt wird. Diese Tabelle ist bei der Problembehandlung aufgrund einer ungleichmäßigen Datenverteilung nützlich. Dieses PartitionKeyStatistics-Protokoll wird nur ausgegeben, wenn die folgenden Bedingungen zutreffen: 1. Mindestens 1 % der Dokumente in der physischen Partition haben den gleichen logischen Partitionsschlüssel. 2. Von allen Schlüsseln der physischen Partition erfasst das PartitionKeyStatistics-Protokoll die drei Schlüssel mit der größten Speichergröße. Wenn die vorherigen Bedingungen nicht erfüllt sind, sind die Partitionsschlüsselstatistik-Daten nicht verfügbar. Es ist in Ordnung, wenn die oben genannten Bedingungen für Ihr Konto nicht erfüllt sind. Dies deutet in der Regel darauf hin, dass bei Ihnen keine logische Partitionsspeicherschiefe vorliegt. Hinweis: Die geschätzte Größe der Partitionsschlüssel wird mit einem Stichprobenverfahren berechnet, das davon ausgeht, dass alle Dokumente der physischen Partition ungefähr die gleiche Größe haben. Wenn die Dokumentgrößen in der physischen Partition nicht einheitlich sind, ist die geschätzte Größe der Partitionsschlüssel möglicherweise nicht korrekt.	`subscriptionId`, `regionName`, `partitionKey`, `sizeKB`
PartitionKeyRUConsumption	API für NoSQL oder API für Apache Gremlin	Protokolliert den aggregierten RU/s-Verbrauch von Partitionsschlüsseln. Diese Tabelle ist für die Problembehandlung bei heißen Partitionen nützlich. Derzeit meldet Azure Cosmos DB Partitionsschlüssel nur für die API für NoSQL-Konten und für Vorgänge für Punktlesen/Punktschreiben, Abfragen und gespeicherte Prozeduren.	`subscriptionId`, `regionName`, `partitionKey`, `requestCharge`, `partitionKeyRangeId`
ControlPlaneRequests	Alle APIs	Protokolliert Details zu Vorgängen auf Steuerungsebene. Dazu gehören das Erstellen eines Kontos, das Hinzufügen oder Entfernen einer Region, das Aktualisieren der Einstellungen für die Kontoreplikation usw.	`operationName`, `httpstatusCode`, `httpMethod`, `region`
TableApiRequests	API für Table	Protokolliert vom Benutzer initiierte Anforderungen vom Front-End zur Verarbeitung von Anforderungen an Azure Cosmos DB für Table.	`operationName`, `requestCharge`, `piiCommandText`

Nachdem Sie Ihre Kategoriendetails ausgewählt haben, senden Sie Ihre Protokolle an Ihr bevorzugtes Ziel. Wenn Sie Protokolle an einen Log Analytics-Arbeitsbereichsenden, wählen Sie Ressourcespezifisch als Zieltabelle aus.

Verwenden Sie den Befehl az monitor diagnostic-settings create, um eine Diagnoseeinstellung mit der Azure CLI zu erstellen. Beschreibungen der zugehörigen Parameter finden Sie in der Dokumentation zu diesem Befehl.

Hinweis

Wenn Sie die API für NoSQL verwenden, sollten Sie die export-to-resource-specific-Eigenschaft auf true setzen.

Erstellen Sie Shellvariablen für subscriptionId, diagnosticSettingName, workspaceName und 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>"

Verwenden Sie az monitor diagnostic-settings create, um die Einstellung zu erstellen.

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"

Verwenden Sie die Azure Monitor-REST-API, um eine Diagnoseeinstellung über die interaktive Konsole zu erstellen.

Hinweis

Sie sollten die logAnalyticsDestinationType-Eigenschaft auf Dediziert setzen, um ressourcenspezifische Tabellen zu aktivieren.

Erstellen Sie eine HTTP PUT-Anforderung.

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

Verwenden Sie diese Header für die Anforderung.

Parameter/Header	Wert/Beschreibung
name	Der Name Ihrer Diagnoseeinstellung.
resourceUri	Microsoft Insights-Unterressourcen-URI für das Azure Cosmos DB-Konto.
api-version	`2017-05-01-preview`
Content-Type	`application/json`

Hinweis

Der URI für die Microsoft Insights-Unterressource hat das folgende Format: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Weitere Informationen zu Azure Cosmos DB-Ressourcen-URIs finden Sie unter Syntax von Ressourcen-URIs für die Azure Cosmos DB-REST-API.

Legen Sie den Text der Anforderung auf diese JSON-Nutzlast fest.

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

Verwenden Sie hier eine ARM-Vorlage (Azure Resource Manager-Vorlage), um eine Diagnoseeinstellung zu erstellen.

Hinweis

Legen Sie die logAnalyticsDestinationType-Eigenschaft auf Dedicated fest, um ressourcenspezifische Tabellen zu aktivieren.

Erstellen Sie die folgende JSON-Vorlagendatei, um Diagnoseeinstellungen für Ihre Azure Cosmos DB-Ressource bereitzustellen.

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

Erstellen Sie die folgende JSON-Parameterdatei mit den Einstellungen, die für Ihre Azure Cosmos DB-Ressource geeignet sind.

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

Bereitstellen der Vorlage mithilfe von az deployment group create.

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

Aktivieren der Volltextabfrage zur Protokollierung von Abfragetext

Hinweis

Die Aktivierung dieses Features kann zu zusätzlichen Protokollierungskosten führen. Preisinformationen finden Sie unter Azure Monitor Preise. Sie sollten dieses Feature nach der Problembehandlung deaktivieren.

Azure Cosmos DB bietet erweiterte Protokollierung für eine detaillierte Problembehandlung. Wenn Sie die Volltextabfrage aktivieren, können Sie die entschleierte Abfrage für alle Anforderungen in Ihrem Azure Cosmos DB-Konto anzeigen. Außerdem erteilen Sie Azure Cosmos DB die Erlaubnis, auf diese Daten zuzugreifen und sie in Ihren Protokollen anzuzeigen.

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

Navigieren Sie zum Aktivieren dieses Features in Ihrem Azure Cosmos DB-Konto zur Seite Features.
Wählen Sie Enable aus. Diese Einstellung wird innerhalb weniger Minuten angewendet. Alle neu eingelesenen Protokolle enthalten den Volltext oder den PIICommand-Text für jede Anfrage.

Vergewissern Sie sich, dass Sie bei der Azure CLI angemeldet sind. Weitere Informationen finden Sie unter Anmelden mit der Azure CLI. Stellen Sie optional sicher, dass Sie das aktive Abonnement für Ihre CLI konfiguriert haben. Weitere Informationen finden Sie unter Ändern des aktiven Azure CLI-Abonnements.

Erstellen Sie Shellvariablen für accountName und resourceGroupName.

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

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

Rufen Sie den eindeutigen Bezeichner für Ihr vorhandenes Konto mit az show ab.

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

Speichern Sie den eindeutigen Bezeichner in einer Shellvariablen namens $uri.

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

Fragen Sie die Ressource über die REST-API und az restmit einem HTTPGET-Verb ab, um zu prüfen, ob die Volltextabfrage bereits aktiviert ist.

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

Wenn die Volltextabfrage nicht aktiviert ist, ähnelt die Ausgabe diesem Beispiel.

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

Wenn die Volltextabfrage noch nicht aktiviert ist, aktivieren Sie sie mithilfe von az rest erneut mit einem HTTP PATCH-Verb und einer JSON-Nutzlast.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Hinweis

Wenn Sie Azure CLI innerhalb einer PowerShell-Eingabeaufforderung verwenden, müssen Sie die doppelten Anführungszeichen mit einem Backslash (\) escapen.

Warten Sie einige Minuten, bis der Vorgang abgeschlossen ist. Überprüfen Sie den Status der Volltextabfrage, indem Sie az rest erneut verwenden.

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

Die Ausgabe sollte dem folgenden Beispiel ähneln.

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

Daten abfragen

Informationen zum Abfragen mithilfe dieser neu aktivierten Features finden Sie unter:

Nächste Schritte

Referenz zur Überwachung von Daten in Azure Cosmos DB

Überwachen der Azure Cosmos DB-Daten mithilfe der Diagnoseeinstellungen in Azure

Voraussetzungen

Erstellen von Diagnoseeinstellungen

Aktivieren der Volltextabfrage zur Protokollierung von Abfragetext

Daten abfragen

Nächste Schritte

Zusätzliche Ressourcen