Azure'da tanılama ayarlarını kullanarak Azure Cosmos DB verilerini izleme

Makale
02/13/2024

ŞUNLAR IÇIN GEÇERLIDIR: Nosql MongoDB Cassandra Gremlin Tablo

Kaynak günlüklerini toplamak için Azure'daki tanılama ayarları kullanılır. Kaynaklar Azure kaynak günlüklerini yayar ve bu kaynağın işlemi hakkında zengin ve sık kullanılan veriler sağlar. Bu günlükler istek başına yakalanır ve "veri düzlemi günlükleri" olarak da adlandırılır. Veri düzlemi işlemlerine örnek olarak delete, insert ve readFeed verilebilir. Bu günlüklerin içeriği, kaynak türüne göre değişir.

Platform ölçümleri ve Etkinlik günlükleri otomatik olarak toplanırken, kaynak günlüklerini toplamak veya Azure İzleyici'nin dışına iletmek için bir tanılama ayarı oluşturmanız gerekir. Azure Cosmos DB hesapları için tanılama ayarını açabilir ve kaynak günlüklerini aşağıdaki kaynaklara gönderebilirsiniz:

Log Analytics çalışma alanları
- Log Analytics'e gönderilen veriler Azure Tanılama (eski) veya Kaynağa özgü (önizleme) tablolara yazılabilir
Olay hub'ı
Depolama Hesabı

Not

REST API aracılığıyla tanılama ayarı oluşturma yönergelerimizi izleyerek tanılama ayarını kaynağa özgü modda (Tablo api'leri dışındaki tüm API'ler için) oluşturmanızı öneririz. Bu seçenek, verileri işlemek için geliştirilmiş bir görünümle ek maliyet iyileştirmeleri sağlar.

Önkoşullar

Mevcut bir Azure Cosmos DB hesabı.
- Azure aboneliğiniz varsa yeni bir hesap oluşturun.
- Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.
- Alternatif olarak, işlemeden önce Azure Cosmos DB'yi ücretsiz deneyebilirsiniz.

Tanılama ayarlarını oluşturma

Burada, hesabınız için tanılama ayarları oluşturma işleminde size yol gösteririz.

Azure Portal’ında oturum açın.
Azure Cosmos DB hesabınıza gidin. İzleme bölümünün altındaki Tanılama ayarları bölmesini açın ve tanılama ayarı ekle seçeneğini belirleyin.

Önemli

"Tam metin sorgusunu etkinleştirme [...] daha ayrıntılı günlüğe kaydetme için", hesabınızda tam metin sorgu özelliği etkinleştirilmediyse. Bu özelliği etkinleştirmek istemiyorsanız bu uyarıyı güvenle yoksayabilirsiniz. Daha fazla bilgi için bkz . Tam metin sorgusunu etkinleştirme.

Tanılama ayarları bölmesinde formu tercih ettiğiniz kategorilerle doldurun. Burada günlük kategorilerinin listesi yer alır.

Kategori	API	Açıklama	Anahtar Özellikler
DataPlaneRequests	NoSQL için API için önerilir	Arka uç isteklerini, hesaptaki verileri oluşturmak, güncelleştirmek, silmek veya almak için yürütülen istekler olan veri düzlemi işlemleri olarak günlüğe kaydeder.	`Requestcharge`, `statusCode`, `clientIPaddress`, `partitionID`, , `resourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	MongoDB için API	MongoDB için Azure Cosmos DB'ye istek sunmak için ön uçtan kullanıcı tarafından başlatılan istekleri günlüğe kaydeder. Bu kategoriyi etkinleştirdiğinizde DataPlaneRequests'i devre dışı bırakın.	`Requestcharge`, `opCode`, `retryCount`, `piiCommandText`
CassandraRequests	Apache Cassandra için API	Cassandra için Azure Cosmos DB'ye istek sunmak için ön uçtan kullanıcı tarafından başlatılan istekleri günlüğe kaydeder.	`operationName`, `requestCharge`, `piiCommandText`
GremlinRequests	Apache Gremlin için API	Gremlin için Azure Cosmos DB'ye istek sunmak için ön uçtan kullanıcı tarafından başlatılan istekleri günlüğe kaydeder.	`operationName`, `requestCharge`, `piiCommandText`, `retriedDueToRateLimiting`
QueryRuntimeStatistics	NoSQL için API	Bu tabloda NoSQL hesabı için BIR API'de yürütülen sorgu işlemleri ayrıntılı olarak açıklanmıştır. Varsayılan olarak, istek tarafından sağlanan tam metin sorgu günlüğüyle persona l verilerinin günlüğe kaydedilmesini önlemek için sorgu metni ve parametreleri karartılır.	`databasename`, `partitionkeyrangeid`, `querytext`
PartitionKeyStatistics	Tüm API'ler	Mantıksal bölüm anahtarlarının istatistiklerini, bölüm anahtarlarının tahmini depolama boyutunu (KB) temsil ederek günlüğe kaydeder. Bu tablo, depolama dengesizliği sorunlarını giderirken kullanışlıdır. Bu PartitionKeyStatistics günlüğü yalnızca aşağıdaki koşullar doğruysa gönderilir: 1. Fiziksel bölümdeki belgelerin en az %1'i aynı mantıksal bölüm anahtarına sahiptir. 2. Fiziksel bölümdeki tüm anahtarlar dışında, PartitionKeyStatistics günlüğü en büyük depolama boyutuna sahip ilk üç anahtarı yakalar. Önceki koşullar karşılanmazsa bölüm anahtarı istatistikleri verileri kullanılamaz. Yukarıdaki koşulların hesabınız için karşılanmadığı durumlarda sorun yoktur. Bu durum genellikle mantıksal bölüm depolama dengesizliği olmadığını gösterir. Not: Bölüm anahtarlarının tahmini boyutu, fiziksel bölümdeki belgelerin kabaca aynı boyutta olduğunu varsayar bir örnekleme yaklaşımı kullanılarak hesaplanır. Belge boyutları fiziksel bölümde tekdüzen değilse, tahmini bölüm anahtarı boyutu doğru olmayabilir.	`subscriptionId`, `regionName`, `partitionKey`, `sizeKB`
PartitionKeyRUConsumption	NoSQL IÇIN API veya Apache Gremlin için API	Bölüm anahtarlarının saniye başına toplam RU/sn tüketimini günlüğe kaydeder. Bu tablo sık erişimli bölümlerin sorunlarını gidermek için kullanışlıdır. Şu anda Azure Cosmos DB yalnızca NoSQL hesapları için API ve nokta okuma/yazma, sorgu ve saklı yordam işlemleri için bölüm anahtarlarını raporlar.	`subscriptionId`, `regionName`, `partitionKey`, `requestCharge`, , `partitionKeyRangeId`
ControlPlaneRequests	Tüm API'ler	Hesap oluşturma, bölge ekleme veya kaldırma, hesap çoğaltma ayarlarını güncelleştirme gibi denetim düzlemi işlemleriyle ilgili ayrıntıları günlüğe kaydeder.	`operationName`, `httpstatusCode`, `httpMethod`, `region`
TableApiRequests	Tablo için API	Tablo için Azure Cosmos DB'ye istek sunmak için ön uçtan kullanıcı tarafından başlatılan istekleri günlüğe kaydeder.	`operationName`, `requestCharge`, `piiCommandText`

Kategoriler ayrıntılarınızı seçtikten sonra Günlüklerinizi tercih ettiğiniz hedefe gönderin. Günlükleri log analytics çalışma alanına gönderiyorsanız Hedef tablo olarak Kaynağa özgü seçeneğini belirlediğinizden emin olun.

Azure CLI ile bir tanılama ayarı oluşturmak için az monitor diagnostic-settings create komutunu kullanın. Parametrelerinin açıklamaları için bu komutun belgelerine bakın.

Not

NoSQL için API kullanıyorsanız kaynağa özel dışarı aktarma özelliğini true olarak ayarlamanızı öneririz.

, diagnosticSettingNameve workspaceNameresourceGroupNameiçin subscriptionIdkabuk değişkenleri oluşturun.

# 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>"

Ayarı oluşturmak için kullanın az monitor diagnostic-settings create .

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"

Etkileşimli konsol aracılığıyla tanılama ayarı oluşturmak için Azure İzleyici REST API'sini kullanın.

Not

Kaynağa özgü tabloları etkinleştirmek için logAnalyticsDestinationType özelliğini Ayrılmış olarak ayarlamanızı öneririz.

HTTP PUT isteği oluşturun.

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

İstekle birlikte bu üst bilgileri kullanın.

Parametreler/Üst Bilgiler	Değer/Açıklama
Adı	Tanılama ayarınızın adı.
resourceUri	Azure Cosmos DB hesabı için Microsoft Analizler alt kaynak URI'si.
api sürümü	`2017-05-01-preview`
İçerik Türü	`application/json`

Not

Microsoft Analizler alt kaynağının URI'si şu biçimdedir: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Azure Cosmos DB kaynak URI'leri hakkında daha fazla bilgi için bkz . Azure Cosmos DB REST API için kaynak URI söz dizimi.

İsteğin gövdesini bu JSON yüküne ayarlayın.

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

Burada, tanılama ayarı oluşturmak için bir Azure Resource Manager (ARM) şablonu kullanın.

Not

Kaynağa özgü tabloları etkinleştirmek için logAnalyticsDestinationType özelliğini Ayrılmış olarak ayarlayın.

Azure Cosmos DB kaynağınız için tanılama ayarlarını dağıtmak için aşağıdaki JSON şablon dosyasını oluşturun.

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

Azure Cosmos DB kaynağınıza uygun ayarlarla aşağıdaki JSON parametre dosyasını oluşturun.

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

kullanarak az deployment group createşablonu dağıtın.

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

Sorgu metnini günlüğe kaydetmek için tam metin sorgusunu etkinleştirme

Not

Bu özelliğin etkinleştirilmesi ek günlüğe kaydetme maliyetlerine neden olabilir. Fiyatlandırma ayrıntıları için Azure İzleyici fiyatlandırması bölümünü ziyaret edin. Sorun giderme sonrasında bu özelliği devre dışı bırakması önerilir.

Azure Cosmos DB, ayrıntılı sorun giderme işlemleri için gelişmiş günlük kaydı sağlar. Tam metin sorgusunu etkinleştirerek Azure Cosmos DB hesabınızdaki tüm istekler için engelsiz sorguyu görüntüleyebilirsiniz. Ayrıca Azure Cosmos DB'nin bu verilere erişmesine ve günlüklerinizde bu verilere erişmesine izin verirsiniz.

Azure portalı
Azure CLI / REST API / ARM şablonu

Bu özelliği etkinleştirmek için Azure Cosmos DB hesabınızdaki sayfaya Features gidin.
Enable öğesini seçin. Bu ayar birkaç dakika içinde uygulanır. Yeni alınan tüm günlüklerde her istek için tam metin veya PIICommand metni bulunur.

Azure CLI'da oturum açtığınızdan emin olun. Daha fazla bilgi için bkz . Azure CLI ile oturum açma. İsteğe bağlı olarak, CLI'nız için etkin aboneliği yapılandırdığınızdan emin olun. Daha fazla bilgi için bkz . Etkin Azure CLI aboneliğini değiştirme.

ve resourceGroupNameiçin accountName kabuk değişkenleri oluşturun.

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

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

kullanarak az showmevcut hesabınızın benzersiz tanımlayıcısını alın.

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

Benzersiz tanımlayıcıyı adlı $uribir kabuk değişkeninde depolayın.

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

Tam metin sorgusunun zaten etkin olup olmadığını denetlemek için REST API'yi kullanarak ve az rest bir HTTP GET fiiliyle kaynağı sorgular.

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

Tam metin sorgusu etkinleştirilmemişse, çıktı bu örneğe benzer olacaktır.

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

Tam metin sorgusu henüz etkinleştirilmemişse, http PATCH fiili ve JSON yüküyle kullanarak az rest yeniden etkinleştirin.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Not

PowerShell isteminde Azure CLI kullanıyorsanız, ters eğik çizgi (\) karakteri kullanarak çift tırnak işaretinden kurtulmanız gerekir.

İşlemin tamamlanması için birkaç dakika bekleyin. Yeniden kullanarak az rest tam metin sorgusunun durumunu denetleyin.

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

Çıktı bu örneğe benzer olmalıdır.

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

Verileri sorgulama

Yeni etkinleştirilen bu özellikleri kullanarak sorgulamayı öğrenmek için bkz:

Sonraki adımlar

Azure Cosmos DB veri başvurularını izleme