Övervaka Azure Cosmos DB-data med hjälp av diagnostikinställningar i Azure

Artikel
02/13/2024

GÄLLER FÖR: Nosql Mongodb Cassandra Gremlin Tabell

Diagnostikinställningar i Azure används för att samla in resursloggar. Resurser genererar Azure-resursloggar och ger omfattande, frekventa data om hur resursen fungerar. Dessa loggar registreras per begäran och kallas även "dataplansloggar". Några exempel på dataplansåtgärder är borttagning, infogning och readFeed. Innehållet i loggarna varierar beroende på resurstyp.

Plattformsmått och aktivitetsloggar samlas in automatiskt, medan du måste skapa en diagnostikinställning för att samla in resursloggar eller vidarebefordra dem utanför Azure Monitor. Du kan aktivera diagnostikinställningen för Azure Cosmos DB-konton och skicka resursloggar till följande källor:

Log Analytics-arbetsytor
- Data som skickas till Log Analytics kan skrivas till Azure Diagnostics -tabeller (äldre) eller resursspecifika tabeller (förhandsversion)
Händelsehubb
Lagringskonto

Kommentar

Vi rekommenderar att du skapar diagnostikinställningen i resursspecifikt läge (för alla API:er utom API för tabell) genom att följa våra instruktioner för att skapa diagnostikinställning via REST API. Det här alternativet ger ytterligare kostnadsoptimeringar med en förbättrad vy för hantering av data.

Förutsättningar

Ett befintligt Azure Cosmos DB-konto.
- Om du har en Azure-prenumeration skapar du ett nytt konto.
- Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.
- Du kan också prova Azure Cosmos DB kostnadsfritt innan du checkar in.

Skapa diagnostikinställningar

Här går vi igenom processen med att skapa diagnostikinställningar för ditt konto.

Logga in på Azure-portalen.
Gå till ditt Azure Cosmos DB-konto. Öppna fönstret Diagnostikinställningar under avsnittet Övervakning och välj sedan alternativet Lägg till diagnostikinställning.

Viktigt!

Du kan se en uppmaning om att "aktivera fulltextfråga [...] för mer detaljerad loggning" om frågefunktionen i fulltext inte är aktiverad i ditt konto. Du kan ignorera den här varningen på ett säkert sätt om du inte vill aktivera den här funktionen. Mer information finns i aktivera fulltextfråga.

I fönstret Diagnostikinställningar fyller du formuläret med önskade kategorier. Här är en lista över loggkategorier.

Kategori	API	Definition	Nyckelegenskaper
DataPlaneRequests	Rekommenderas för API för NoSQL	Loggar serverdelsbegäranden som dataplansåtgärder, som är begäranden som körs för att skapa, uppdatera, ta bort eller hämta data i kontot.	`Requestcharge`, `statusCode`, `clientIPaddress`, , , `partitionIDresourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	API för MongoDB	Loggar användarinitierade begäranden från klientdelen för att hantera begäranden till Azure Cosmos DB för MongoDB. När du aktiverar den här kategorin måste du inaktivera DataPlaneRequests.	`Requestcharge`, `opCode`, , `retryCountpiiCommandText`
CassandraRequests	API för Apache Cassandra	Loggar användarinitierade begäranden från klientdelen för att hantera begäranden till Azure Cosmos DB för Cassandra.	`operationName`, , `requestChargepiiCommandText`
GremlinRequests	API för Apache Gremlin	Loggar användarinitierade begäranden från klientdelen för att hantera begäranden till Azure Cosmos DB för Gremlin.	`operationName`, `requestCharge`, , `piiCommandTextretriedDueToRateLimiting`
QueryRuntimeStatistics	API för NoSQL	Den här tabellen beskriver frågeåtgärder som körs mot ett API för NoSQL-konto. Som standard är frågetexten och dess parametrar fördunklade för att undvika loggning av persona l-data med fulltextfrågeloggning tillgänglig via begäran.	`databasename`, , `partitionkeyrangeidquerytext`
PartitionKeyStatistics	Alla API:er	Loggar statistiken för logiska partitionsnycklar genom att representera den uppskattade lagringsstorleken (KB) för partitionsnycklarna. Den här tabellen är användbar när du felsöker lagringsförskjutningar. Den här PartitionKeyStatistics-loggen genereras endast om följande villkor är sanna: 1. Minst 1 % av dokumenten i den fysiska partitionen har samma logiska partitionsnyckel. 2. Av alla nycklar i den fysiska partitionen samlar PartitionKeyStatistics-loggen in de tre översta nycklarna med störst lagringsstorlek. Om de tidigare villkoren inte uppfylls är data för partitionsnyckelstatistik inte tillgängliga. Det är okej om ovanstående villkor inte uppfylls för ditt konto, vilket vanligtvis indikerar att du inte har någon logisk partitionslagringsförskjutning. Obs! Den uppskattade storleken på partitionsnycklarna beräknas med en samplingsmetod som förutsätter att dokumenten i den fysiska partitionen är ungefär lika stora. Om dokumentstorlekarna inte är enhetliga i den fysiska partitionen kanske den uppskattade storleken på partitionsnyckeln inte är korrekt.	`subscriptionId`, `regionName`, , `partitionKeysizeKB`
PartitionKeyRUConsumption	API för NoSQL eller API för Apache Gremlin	Loggar den aggregerade RU/s-förbrukningen per sekund för partitionsnycklar. Den här tabellen är användbar för att felsöka frekventa partitioner. För närvarande rapporterar Azure Cosmos DB endast partitionsnycklar för API för NoSQL-konton och för punktläsning/skrivning, frågor och lagrade procedurer.	`subscriptionId`, `regionName`, `partitionKey`, , , `requestChargepartitionKeyRangeId`
ControlPlaneRequests	Alla API:er	Loggar information om kontrollplansåtgärder, till exempel att skapa ett konto, lägga till eller ta bort en region, uppdatera kontoreplikeringsinställningar osv.	`operationName`, `httpstatusCode`, , `httpMethodregion`
TableApiRequests	API för tabell	Loggar användarinitierade begäranden från klientdelen för att hantera begäranden till Azure Cosmos DB for Table.	`operationName`, , `requestChargepiiCommandText`

När du har valt kategoriinformationen skickar du sedan loggarna till önskat mål. Om du skickar loggar till en Log Analytics-arbetsyta ska du välja Resursspecifik som måltabell.

Använd kommandot az monitor diagnostic-settings create för att skapa en diagnostikinställning med Azure CLI. I dokumentationen för det här kommandot finns beskrivningar av dess parametrar.

Kommentar

Om du använder API för NoSQL rekommenderar vi att du ställer in den export-till-resursspecifika egenskapen till true.

Skapa gränssnittsvariabler för subscriptionId, diagnosticSettingNameworkspaceName och 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>"

Använd az monitor diagnostic-settings create för att skapa inställningen.

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"

Använd Rest-API:et för Azure Monitor för att skapa en diagnostikinställning via den interaktiva konsolen.

Kommentar

Vi rekommenderar att du anger egenskapen logAnalyticsDestinationType till Dedikerad för att aktivera resursspecifika tabeller.

Skapa en HTTP-begäran PUT .

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

Använd dessa rubriker med begäran.

Parametrar/rubriker	Värde/beskrivning
Namn	Namnet på diagnostikinställningen.
resourceUri	Microsoft Insights-underresurs-URI för Azure Cosmos DB-konto.
api-version	`2017-05-01-preview`
Innehållstyp	`application/json`

Kommentar

URI:n för Microsoft Insights-underresursen är i det här formatet: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Mer information om Azure Cosmos DB-resurs-URI:er finns i resurs-URI-syntax för Azure Cosmos DB REST API.

Ange begärandetexten till den här JSON-nyttolasten.

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

Här använder du en ARM-mall (Azure Resource Manager) för att skapa en diagnostikinställning.

Kommentar

Ange egenskapen logAnalyticsDestinationType till Dedikerad för att aktivera resursspecifika tabeller.

Skapa följande JSON-mallfil för att distribuera diagnostikinställningar för din Azure Cosmos DB-resurs.

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

Skapa följande JSON-parameterfil med inställningar som är lämpliga för din Azure Cosmos DB-resurs.

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

Distribuera mallen med .az deployment group create

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

Aktivera fulltextfråga för att logga frågetext

Kommentar

Om du aktiverar den här funktionen kan det leda till ytterligare loggningskostnader för prisinformation i Prissättning för Azure Monitor. Vi rekommenderar att du inaktiverar den här funktionen efter felsökning.

Azure Cosmos DB tillhandahåller avancerad loggning för detaljerad felsökning. Genom att aktivera fulltextfråga kan du visa den inaktuella frågan för alla begäranden i ditt Azure Cosmos DB-konto. Du ger också behörighet för Azure Cosmos DB att komma åt och visa dessa data i dina loggar.

Azure-portalen
Azure CLI/REST API/ARM-mall

Om du vill aktivera den här funktionen går du till sidan Features i ditt Azure Cosmos DB-konto.
Välj Enable. Den här inställningen tillämpas inom några minuter. Alla nyligen inmatade loggar har fulltext- eller PIICommand-text för varje begäran.

Kontrollera att du är inloggad på Azure CLI. Mer information finns i logga in med Azure CLI. Du kan också kontrollera att du har konfigurerat den aktiva prenumerationen för din CLI. Mer information finns i ändra den aktiva Azure CLI-prenumerationen.

Skapa gränssnittsvariabler för accountName och resourceGroupName.

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

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

Hämta den unika identifieraren för ditt befintliga konto med hjälp av az show.

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

Lagra den unika identifieraren i en gränssnittsvariabel med namnet $uri.

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

Fråga resursen med hjälp av REST-API:et och az rest med ett HTTP-verb GET för att kontrollera om fulltextfrågan redan är aktiverad.

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

Om fulltextfrågan inte är aktiverad skulle utdata likna det här exemplet.

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

Om fulltextfrågan inte redan är aktiverad aktiverar du den igen az rest med ett HTTP-verb PATCH och en JSON-nyttolast.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Kommentar

Om du använder Azure CLI i en PowerShell-prompt måste du undvika dubbla citattecken med hjälp av ett omvänt snedstreck (\).

Vänta några minuter tills åtgärden har slutförts. Kontrollera statusen för fulltextfrågan med hjälp az rest av igen.

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

Utdata bör likna det här exemplet.

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

Fråga efter data

Information om hur du frågar med hjälp av dessa nyligen aktiverade funktioner finns i:

Nästa steg

Övervaka Azure Cosmos DB-datareferens

Övervaka Azure Cosmos DB-data med hjälp av diagnostikinställningar i Azure

Förutsättningar

Skapa diagnostikinställningar

Aktivera fulltextfråga för att logga frågetext

Fråga efter data

Nästa steg

Ytterligare resurser