Monitorowanie danych usługi Azure Cosmos DB przy użyciu ustawień diagnostycznych na platformie Azure

Artykuł
02/21/2024

DOTYCZY: Nosql Mongodb Cassandra Gremlin Tabeli

Ustawienia diagnostyczne na platformie Azure umożliwiają zbieranie dzienników zasobów. Zasoby emitują dzienniki zasobów platformy Azure i udostępniają rozbudowane, częste dane dotyczące działania tego zasobu. Te dzienniki są przechwytywane na żądanie i są one również określane jako "dzienniki płaszczyzny danych". Niektóre przykłady operacji płaszczyzny danych obejmują usuwanie, wstawianie i odczytFeed. Zawartość tych dzienników różni się w zależności od typu zasobu.

Metryki platformy i dzienniki aktywności są zbierane automatycznie, podczas gdy należy utworzyć ustawienie diagnostyczne w celu zbierania dzienników zasobów lub przekazywania ich poza usługą Azure Monitor. Możesz włączyć ustawienie diagnostyczne dla kont usługi Azure Cosmos DB i wysłać dzienniki zasobów do następujących źródeł:

Obszary robocze usługi Log Analytics
- Dane wysyłane do usługi Log Analytics można zapisywać w tabelach Diagnostyka Azure (starsza wersja) lub specyficznych dla zasobów (wersja zapoznawcza)
Centrum zdarzeń
Konto magazynu

Uwaga

Zalecamy utworzenie ustawienia diagnostycznego w trybie specyficznym dla zasobów (dla wszystkich interfejsów API z wyjątkiem interfejsu API dla tabeli) zgodnie z naszymi instrukcjami dotyczącymi tworzenia ustawień diagnostycznych za pośrednictwem interfejsu API REST. Ta opcja zapewnia dodatkowe optymalizacje kosztów z ulepszonym widokiem obsługi danych.

Wymagania wstępne

Istniejące konto usługi Azure Cosmos DB.
- Jeśli masz subskrypcję platformy Azure, utwórz nowe konto.
- Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
- Alternatywnie możesz wypróbować usługę Azure Cosmos DB bezpłatnie przed zatwierdzeniem.

Tworzenie ustawień diagnostycznych

W tym miejscu przeprowadzimy proces tworzenia ustawień diagnostycznych dla Twojego konta.

Zaloguj się w witrynie Azure Portal.
Przejdź do konta usługi Azure Cosmos DB. Otwórz okienko Ustawienia diagnostyczne w sekcji Monitorowanie, a następnie wybierz opcję Dodaj ustawienie diagnostyczne.

Ważne

Może zostać wyświetlony monit o włączenie zapytania pełnotekstowego [...] aby uzyskać bardziej szczegółowe rejestrowanie", jeśli funkcja zapytania pełnotekstowego nie jest włączona na Twoim koncie. Jeśli nie chcesz włączyć tej funkcji, możesz bezpiecznie zignorować to ostrzeżenie. Aby uzyskać więcej informacji, zobacz włączanie zapytania pełnotekstowego.

W okienku Ustawienia diagnostyczne wypełnij formularz preferowanymi kategoriami. Poniżej znajduje się lista kategorii dzienników.

Kategoria	Interfejs API	Definicja	Właściwości kluczowe
DataPlaneRequests	Zalecane w przypadku interfejsu API dla noSQL	Rejestruje żądania zaplecza jako operacje płaszczyzny danych, które są żądaniami wykonywanymi w celu tworzenia, aktualizowania, usuwania lub pobierania danych na koncie.	`Requestcharge`, , `statusCode`, `clientIPaddress`, , `partitionIDresourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	Interfejs API dla bazy danych MongoDB	Rejestruje żądania inicjowane przez użytkownika z frontonu w celu obsługi żądań do usługi Azure Cosmos DB dla bazy danych MongoDB. Po włączeniu tej kategorii pamiętaj o wyłączeniu elementu DataPlaneRequests.	`Requestcharge`, , `opCode`, , `retryCountpiiCommandText`
CassandraRequests	Interfejs API dla systemu Apache Cassandra	Rejestruje żądania inicjowane przez użytkownika z frontonu w celu obsługi żądań do usługi Azure Cosmos DB dla bazy danych Cassandra.	`operationName`, , `requestChargepiiCommandText`
GremlinRequests	Interfejs API dla języka Apache Gremlin	Rejestruje żądania inicjowane przez użytkownika z frontonu w celu obsługi żądań do usługi Azure Cosmos DB dla języka Gremlin.	`operationName`, , `requestCharge`, , `piiCommandTextretriedDueToRateLimiting`
QueryRuntimeStatistics	Interfejs API dla noSQL	Ta tabela zawiera szczegółowe informacje o operacjach zapytań wykonywanych względem interfejsu API dla konta NoSQL. Domyślnie tekst zapytania i jego parametry są zaciemnione, aby uniknąć rejestrowania danych persona l z rejestrowaniem pełnotekstowych zapytań dostępnych według żądania.	`databasename`, , `partitionkeyrangeidquerytext`
PartitionKeyStatistics	Wszystkie interfejsy API	Rejestruje statystyki kluczy partycji logicznej, reprezentując szacowany rozmiar magazynu (KB) kluczy partycji. Ta tabela jest przydatna podczas rozwiązywania problemów ze niesymetrycznością magazynu. Ten dziennik PartitionKeyStatistics jest emitowany tylko wtedy, gdy spełnione są następujące warunki: 1. Co najmniej 1% dokumentów w partycji fizycznej ma ten sam klucz partycji logicznej. 2. Poza wszystkimi kluczami w partycji fizycznej dziennik PartitionKeyStatistics przechwytuje trzy najważniejsze klucze o największym rozmiarze magazynu. Jeśli poprzednie warunki nie zostaną spełnione, dane statystyczne klucza partycji nie są dostępne. Jest w porządku, jeśli powyższe warunki nie są spełnione dla twojego konta, co zwykle oznacza, że nie ma niesymetryczności magazynu partycji logicznej. Uwaga: szacowany rozmiar kluczy partycji jest obliczany przy użyciu podejścia do próbkowania, które zakłada, że dokumenty w partycji fizycznej mają mniej więcej taki sam rozmiar. Jeśli rozmiary dokumentów nie są jednolite w partycji fizycznej, szacowany rozmiar klucza partycji może nie być dokładny.	`subscriptionId`, , `regionName`, , `partitionKeysizeKB`
PartitionKeyRUConsumption	Interfejs API dla noSQL lub interfejs API dla języka Apache Gremlin	Rejestruje zagregowane użycie jednostek RU/s dla kluczy partycji. Ta tabela jest przydatna do rozwiązywania problemów z gorącymi partycjami. Obecnie usługa Azure Cosmos DB raportuje klucze partycji dla kont interfejsu API dla kont NoSQL i tylko dla operacji odczytu/zapisu i zapisu punktów, zapytań i procedur składowanej.	`subscriptionId`, , `regionName`, `partitionKey`, , `requestChargepartitionKeyRangeId`
ControlPlaneRequests	Wszystkie interfejsy API	Rejestruje szczegółowe informacje na temat operacji płaszczyzny sterowania, w tym tworzenia konta, dodawania lub usuwania regionu, aktualizowania ustawień replikacji konta itp.	`operationName`, , `httpstatusCode`, , `httpMethodregion`
TableApiRequests	Interfejs API dla tabeli	Rejestruje żądania inicjowane przez użytkownika z frontonu w celu obsługi żądań do usługi Azure Cosmos DB dla tabeli.	`operationName`, , `requestChargepiiCommandText`

Po wybraniu szczegółów kategorii wyślij dzienniki do preferowanego miejsca docelowego. Jeśli wysyłasz dzienniki do obszaru roboczego usługi Log Analytics, wybierz pozycję Zasób określony jako tabela Docelowa.

Użyj polecenia az monitor diagnostic-settings create, aby utworzyć ustawienie diagnostyczne za pomocą interfejsu wiersza polecenia platformy Azure. Zapoznaj się z dokumentacją tego polecenia, aby uzyskać opisy jego parametrów.

Uwaga

Jeśli używasz interfejsu API dla noSQL, zalecamy ustawienie właściwości specyficznej dla eksportu do zasobu na wartość true.

Utwórz zmienne powłoki dla subscriptionId, workspaceNamediagnosticSettingNamei 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>"

Użyj az monitor diagnostic-settings create polecenia , aby utworzyć ustawienie.

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"

Użyj interfejsu API REST usługi Azure Monitor do utworzenia ustawienia diagnostycznego za pośrednictwem konsoli interaktywnej.

Uwaga

Zalecamy ustawienie właściwości logAnalyticsDestinationType na Wartość Dedykowana w celu włączenia tabel specyficznych dla zasobów.

Utwórz żądanie HTTP PUT .

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

Użyj tych nagłówków z żądaniem.

Parametry/nagłówki	Wartość/opis
name	Nazwa ustawienia diagnostycznego.
resourceUri	Identyfikator URI podźródła usługi Microsoft Szczegółowe informacje dla konta usługi Azure Cosmos DB.
wersja interfejsu API	`2017-05-01-preview`
Typ zawartości	`application/json`

Uwaga

Identyfikator URI dla podźródła usługi Microsoft Szczegółowe informacje ma następujący format: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Aby uzyskać więcej informacji na temat identyfikatorów URI zasobów usługi Azure Cosmos DB, zobacz Składnia identyfikatora URI zasobu dla interfejsu API REST usługi Azure Cosmos DB.

Ustaw treść żądania na ten ładunek 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
}

W tym miejscu użyj szablonu usługi Azure Resource Manager (ARM), aby utworzyć ustawienie diagnostyczne.

Uwaga

Ustaw właściwość logAnalyticsDestinationType na Wartość Dedykowana, aby włączyć tabele specyficzne dla zasobów.

Utwórz następujący plik szablonu JSON, aby wdrożyć ustawienia diagnostyczne dla zasobu usługi 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"
          }
        ]
      }
    }
  ]
}

Utwórz następujący plik parametrów JSON z ustawieniami odpowiednimi dla zasobu usługi 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"
    }
  }
}

Wdróż szablon przy użyciu polecenia az deployment group create.

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

Włączanie zapytania pełnotekstowego na potrzeby rejestrowania tekstu zapytania

Uwaga

Włączenie tej funkcji może spowodować dodatkowe koszty rejestrowania, aby uzyskać szczegółowe informacje o cenach, odwiedź stronę Cennik usługi Azure Monitor. Zaleca się wyłączenie tej funkcji po rozwiązaniu problemów.

Usługa Azure Cosmos DB udostępnia zaawansowane rejestrowanie na potrzeby szczegółowego rozwiązywania problemów. Włączając zapytanie pełnotekstowe, możesz wyświetlić zapytanie deobfuscated dla wszystkich żądań na koncie usługi Azure Cosmos DB. Możesz również przyznać usłudze Azure Cosmos DB uprawnienia do uzyskiwania dostępu do tych danych i wyświetlania ich w dziennikach.

Witryna Azure Portal
Interfejs wiersza polecenia platformy Azure / interfejs API REST / szablon usługi ARM

Aby włączyć tę funkcję, przejdź do Features strony na koncie usługi Azure Cosmos DB.
Wybierz opcję Enable. To ustawienie jest stosowane w ciągu kilku minut. Wszystkie nowo pozyskane dzienniki mają tekst pełnotekstowy lub PIICommand dla każdego żądania.

Upewnij się, że zalogowano się do interfejsu wiersza polecenia platformy Azure. Aby uzyskać więcej informacji, zobacz Logowanie się za pomocą interfejsu wiersza polecenia platformy Azure. Opcjonalnie upewnij się, że skonfigurowano aktywną subskrypcję dla interfejsu wiersza polecenia. Aby uzyskać więcej informacji, zobacz Zmienianie aktywnej subskrypcji interfejsu wiersza polecenia platformy Azure.

Utwórz zmienne powłoki dla accountName i resourceGroupName.

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

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

Pobierz unikatowy identyfikator istniejącego konta przy użyciu polecenia az show.

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

Zapisz unikatowy identyfikator w zmiennej powłoki o nazwie $uri.

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

Wykonaj zapytanie dotyczące zasobu przy użyciu interfejsu API REST i az rest czasownika HTTP GET , aby sprawdzić, czy zapytanie pełnotekstowe jest już włączone.

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

Jeśli zapytanie pełnotekstowe nie jest włączone, dane wyjściowe będą podobne do tego przykładu.

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

Jeśli zapytanie pełnotekstowe nie jest jeszcze włączone, włącz je ponownie za pomocą az rest czasownika HTTP PATCH i ładunku JSON.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Uwaga

Jeśli używasz interfejsu wiersza polecenia platformy Azure w wierszu polecenia programu PowerShell, musisz użyć podwójnego cudzysłowu przy użyciu znaku ukośnika odwrotnego (\).

Poczekaj kilka minut na ukończenie operacji. Sprawdź stan zapytania pełnotekstowego, używając az rest ponownie.

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

Dane wyjściowe powinny być podobne do tego przykładu.

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

Zapytania o dane

Aby dowiedzieć się, jak wykonywać zapytania przy użyciu tych nowo włączonych funkcji, zobacz:

Następne kroki

Monitorowanie dokumentacji danych usługi Azure Cosmos DB

Monitorowanie danych usługi Azure Cosmos DB przy użyciu ustawień diagnostycznych na platformie Azure

Wymagania wstępne

Tworzenie ustawień diagnostycznych

Włączanie zapytania pełnotekstowego na potrzeby rejestrowania tekstu zapytania

Zapytania o dane

Następne kroki

Dodatkowe zasoby