Monitorování dat ve službě Azure Cosmos DB s využitím nastavení diagnostiky v Azure

Článek
02/13/2024

PLATÍ PRO: NoSQL MongoDB Cassandra Gremlin Tabulka

Nastavení diagnostiky v Azure slouží ke shromažďování protokolů prostředků. Prostředky generují protokoly prostředků Azure a poskytují bohaté a časté údaje o provozu tohoto prostředku. Tyto protokoly se zaznamenávají na požadavek a označují se také jako "protokoly roviny dat". Mezi příklady operací roviny dat patří odstranění, vložení a čteníFeed. Obsah těchto protokolů se liší podle typu prostředku.

Metriky platformy a protokoly aktivit se shromažďují automaticky, zatímco musíte vytvořit nastavení diagnostiky pro shromažďování protokolů prostředků nebo jejich předávání mimo Azure Monitor. Můžete zapnout nastavení diagnostiky pro účty služby Azure Cosmos DB a odesílat protokoly prostředků do následujících zdrojů:

Pracovní prostory Služby Log Analytics
- Data odesílaná do Log Analytics je možné zapsat do tabulek Azure Diagnostics (starší verze) nebo tabulek specifických pro prostředky (Preview).
Centrum událostí
Účet úložiště

Poznámka:

Doporučujeme vytvořit nastavení diagnostiky v režimu specifickém pro prostředky (pro všechna rozhraní API s výjimkou rozhraní API pro tabulku) podle našich pokynů pro vytvoření nastavení diagnostiky prostřednictvím rozhraní REST API. Tato možnost poskytuje další optimalizace nákladů s vylepšeným zobrazením pro zpracování dat.

Požadavky

Existující účet služby Azure Cosmos DB.
- Pokud máte předplatné Azure, vytvořte nový účet.
- Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.
- Alternativně můžete před potvrzením vyzkoušet službu Azure Cosmos DB zdarma .

Vytvoření nastavení diagnostiky

Tady si projdeme proces vytváření nastavení diagnostiky pro váš účet.

Přihlaste se k portálu Azure.
Přejděte ke svému účtu služby Azure Cosmos DB. Otevřete podokno Nastavení diagnostiky v části Monitorování a vyberte možnost Přidat nastavení diagnostiky.

Důležité

Může se zobrazit výzva k povolení fulltextového dotazu [...] pro podrobnější protokolování, pokud není ve vašem účtu povolená funkce fulltextového dotazu . Toto upozornění můžete bezpečně ignorovat, pokud nechcete tuto funkci povolit. Další informace najdete v tématu povolení fulltextového dotazu.

V podokně Nastavení diagnostiky vyplňte formulář upřednostňovanými kategoriemi. Tady je seznam kategorií protokolů.

Kategorie	API	Definice	Hlavní vlastnosti
DataPlaneRequests	Doporučeno pro rozhraní API for NoSQL	Protokoluje požadavky back-endu jako operace roviny dat, což jsou požadavky spouštěné za účelem vytvoření, aktualizace, odstranění nebo načtení dat v rámci účtu.	`Requestcharge`, `statusCode`, `clientIPaddress`, , `partitionIDresourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	Rozhraní API pro MongoDB	Protokoluje požadavky iniciované uživatelem z front-endu a obsluhuje požadavky do služby Azure Cosmos DB pro MongoDB. Pokud tuto kategorii povolíte, nezapomeňte zakázat dataPlaneRequests.	`Requestcharge`, `opCode`, , `retryCountpiiCommandText`
CassandraRequests	Rozhraní API pro Apache Cassandra	Protokoluje požadavky iniciované uživatelem z front-endu a obsluhuje požadavky do služby Azure Cosmos DB for Cassandra.	`operationName`, , `requestChargepiiCommandText`
GremlinRequests	Rozhraní API pro Apache Gremlin	Protokoluje požadavky iniciované uživatelem z front-endu a obsluhuje požadavky do služby Azure Cosmos DB pro Gremlin.	`operationName`, `requestCharge`, , `piiCommandTextretriedDueToRateLimiting`
QueryRuntimeStatistics	Rozhraní API pro NoSQL	Tato tabulka podrobně popisuje operace dotazu prováděné na účtu ROZHRANÍ API pro NoSQL. Ve výchozím nastavení je text dotazu a jeho parametry obfuskované, aby se zabránilo protokolování dat persona l s protokolováním fulltextových dotazů, které jsou dostupné podle požadavku.	`databasename`, , `partitionkeyrangeidquerytext`
PartitionKeyStatistics	Všechna rozhraní API	Zaznamená statistiku logických klíčů oddílů tak, že představuje odhadovanou velikost úložiště (kB) klíčů oddílů. Tato tabulka je užitečná při řešení potíží se nerovnoměrnou distribucemi úložiště. Tento protokol PartitionKeyStatistics se vygeneruje pouze v případě, že platí následující podmínky: 1. Nejméně 1 % dokumentů ve fyzickém oddílu má stejný logický klíč oddílu. 2. Ze všech klíčů ve fyzickém oddílu zachytí protokol PartitionKeyStatistics první tři klíče s největší velikostí úložiště. Pokud předchozí podmínky nejsou splněné, data statistiky klíče oddílu nejsou k dispozici. Je v pořádku, pokud výše uvedené podmínky nejsou splněny pro váš účet, což obvykle znamená, že nemáte žádné nerovnoměrné rozdělení úložiště logických oddílů. Poznámka: Odhadovaná velikost klíčů oddílů se počítá pomocí metody vzorkování, která předpokládá, že dokumenty ve fyzickém oddílu mají přibližně stejnou velikost. Pokud velikost dokumentu není jednotná ve fyzickém oddílu, nemusí být odhadovaná velikost klíče oddílu přesná.	`subscriptionId`, `regionName`, , `partitionKeysizeKB`
PartitionKeyRUConsumption	Rozhraní API pro NoSQL nebo rozhraní API pro Apache Gremlin	Zaznamená agregovanou spotřebu ru/s za sekundu klíčů oddílů. Tato tabulka je užitečná pro řešení potíží s horkými oddíly. Azure Cosmos DB v současné době hlásí klíče oddílů pro účty API pro NoSQL a pouze pro operace čtení a zápisu bodů, dotazů a uložených procedur.	`subscriptionId`, `regionName`, `partitionKey`, , `requestChargepartitionKeyRangeId`
ControlPlaneRequests	Všechna rozhraní API	Zaznamenává podrobnosti o operacích řídicí roviny, mezi které patří vytvoření účtu, přidání nebo odebrání oblasti, aktualizace nastavení replikace účtu atd.	`operationName`, `httpstatusCode`, , `httpMethodregion`
Požadavky TableApiRequests	Rozhraní API pro tabulku	Protokoluje požadavky iniciované uživatelem z front-endu, aby sloužily žádostem do služby Azure Cosmos DB for Table.	`operationName`, , `requestChargepiiCommandText`

Jakmile vyberete podrobnosti o kategoriích, odešlete protokoly do preferovaného cíle. Pokud odesíláte protokoly do pracovního prostoru služby Log Analytics, nezapomeňte jako cílovou tabulku vybrat prostředek specifický .

Pomocí příkazu az monitor diagnostic-settings create vytvořte nastavení diagnostiky pomocí Azure CLI. Popis jeho parametrů najdete v dokumentaci k tomuto příkazu.

Poznámka:

Pokud používáte rozhraní API pro NoSQL, doporučujeme nastavit vlastnost specifickou pro export do prostředku na hodnotu true.

Vytváření proměnných prostředí pro subscriptionId, diagnosticSettingNameworkspaceName a 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>"

Slouží az monitor diagnostic-settings create k vytvoření nastavení.

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"

K vytvoření nastavení diagnostiky prostřednictvím interaktivní konzoly použijte rozhraní REST API služby Azure Monitor.

Poznámka:

Pro povolení tabulek specifických pro prostředky doporučujeme nastavit vlastnost logAnalyticsDestinationType na hodnotu Dedicated .

Vytvořte požadavek HTTP PUT .

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

Tyto hlavičky použijte s požadavkem.

Parametry nebo hlavičky	Hodnota/popis
Jméno	Název nastavení diagnostiky
resourceUri	Identifikátor URI podsourcu Microsoft Přehledy pro účet služby Azure Cosmos DB.
api-version	`2017-05-01-preview`
Typ obsahu	`application/json`

Poznámka:

Identifikátor URI pro podsourc microsoft Přehledy je v tomto formátu: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Další informace o identifikátorech URI prostředků služby Azure Cosmos DB najdete v syntaxi identifikátorů URI prostředků pro rozhraní REST API služby Azure Cosmos DB.

Nastavte text požadavku na tuto datovou část 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
}

Tady pomocí šablony Azure Resource Manageru (ARM) vytvořte nastavení diagnostiky.

Poznámka:

Nastavte logAnalyticsDestinationType vlastnost Dedicated tak, aby povolte tabulky specifické pro prostředky.

Vytvořte následující soubor šablony JSON pro nasazení nastavení diagnostiky pro prostředek 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"
          }
        ]
      }
    }
  ]
}

Vytvořte následující soubor parametrů JSON s nastavením, které je vhodné pro váš prostředek 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"
    }
  }
}

Nasaďte šablonu pomocí az deployment group create.

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

Povolení fulltextového dotazu pro protokolování textu dotazu

Poznámka:

Povolení této funkce může vést k dalším nákladům na protokolování. Podrobnosti o cenách najdete na stránce s cenami služby Azure Monitor. Po řešení potíží doporučujeme tuto funkci zakázat.

Azure Cosmos DB poskytuje rozšířené protokolování pro podrobné řešení potíží. Povolením fulltextového dotazu můžete zobrazit deobfuscovaný dotaz pro všechny požadavky v rámci účtu služby Azure Cosmos DB. Také udělíte oprávnění ke službě Azure Cosmos DB pro přístup k datům a jejich zpřístupnění v protokolech.

Azure Portal
Azure CLI / REST API / šablona ARM

Pokud chcete tuto funkci povolit, přejděte na Features stránku ve svém účtu služby Azure Cosmos DB.
Vyberte možnost Enable. Toto nastavení se použije během několika minut. Všechny nově přijaté protokoly mají pro každý požadavek celý text nebo text PIICommand.

Ujistěte se, že jste přihlášeni k Azure CLI. Další informace najdete v tématu Přihlášení pomocí Azure CLI. Volitelně se ujistěte, že jste pro rozhraní příkazového řádku nakonfigurovali aktivní předplatné. Další informace najdete v tématu Změna aktivního předplatného Azure CLI.

Vytváření proměnných prostředí pro accountName a resourceGroupName.

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

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

Získejte jedinečný identifikátor existujícího účtu pomocí az show.

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

Uložte jedinečný identifikátor do proměnné prostředí s názvem $uri.

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

Dotazujte se na prostředek pomocí rozhraní REST API a az rest pomocí příkazu HTTP GET a zkontrolujte, jestli je již povolený fulltextový dotaz.

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

Pokud není povolený fulltextový dotaz, bude výstup podobný tomuto příkladu.

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

Pokud fulltextový dotaz ještě není povolený, povolte ho az rest znovu s příkazem HTTP PATCH a datovou částí JSON.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Poznámka:

Pokud v příkazovém řádku PowerShellu používáte Azure CLI, budete muset uvozovky uvozovek uvozovek uvozovat pomocí zpětného lomítka (\) znaku.

Počkejte několik minut, než se operace dokončí. Znovu zkontrolujte stav fulltextového dotazu 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}}"

Výstup by měl být podobný tomuto příkladu.

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

Zadávání dotazů na data

Informace o dotazování pomocí těchto nově povolených funkcí najdete tady:

Další kroky

Referenční informace k monitorování dat služby Azure Cosmos DB

Monitorování dat ve službě Azure Cosmos DB s využitím nastavení diagnostiky v Azure

Požadavky

Vytvoření nastavení diagnostiky

Povolení fulltextového dotazu pro protokolování textu dotazu

Zadávání dotazů na data

Další kroky

Další materiály