Memecahkan masalah saat Anda menggunakan Azure Cosmos DB Python SDK dengan API untuk akun NoSQL

Berlaku untuk: ✅ NoSQL

Penting

Artikel ini membahas pemecahan masalah untuk Azure Cosmos DB Python SDK saja. Silakan lihat catatan Rilis Readme Azure Cosmos DB Python SDK, Paket (PyPI), Paket (Conda), dan tips performa untuk informasi selengkapnya.

Artikel ini membahas masalah umum, solusi, langkah diagnostik, dan alat saat Anda menggunakan Azure Cosmos DB Python SDK dengan Azure Cosmos DB untuk akun NoSQL. Azure Cosmos DB Python SDK menyediakan representasi logis sisi klien untuk mengakses Azure Cosmos DB for NoSQL. Artikel ini menjelaskan alat dan pendekatan untuk membantu Anda jika mengalami masalah.

Mulai dengan daftar ini:

Lihat bagian Masalah umum dan solusi dalam artikel ini.
Lihat Python SDK di repositori pusat Azure Cosmos DB, yang tersedia sumber terbuka di GitHub. Ini memiliki bagian masalah yang dipantau secara aktif. Periksa untuk melihat apakah ada masalah serupa dengan solusi yang sudah diajukan. Salah satu tip bermanfaat adalah memfilter masalah menurut *Cosmos* tag.
Tinjau tips performa untuk Azure Cosmos DB Python SDK, dan ikuti praktik yang disarankan.
Baca artikel lainnya, jika Anda tidak menemukan solusi. Kemudian ajukan masalah GitHub. Jika ada opsi untuk menambahkan tag ke masalah GitHub Anda, tambahkan *Cosmos* tag.

Mencatat dan mengumpulkan data diagnostik

Penting

Sebaiknya gunakan versi terbaru python SDK. Anda dapat memeriksa riwayat rilis di sini

Pustaka ini menggunakan pustaka log standar untuk diagnostik pencatatan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Log level DEBUG yang terperinci, termasuk isi permintaan/respons dan header yang tidak disunting, dapat diaktifkan pada klien dengan argumen logging_enable.

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:

database = client.create_database(DATABASE_NAME, logging_enable=True)

Atau, Anda dapat melakukan logging menggunakan CosmosHttpLoggingPolicy, yang berasal dari HttpLoggingPolicy inti azure, dengan meneruskan logger Anda ke argumen logger. Secara default, ia akan menggunakan perilaku dari HttpLoggingPolicy. Meneruskan argumen enable_diagnostics_logging akan mengaktifkan CosmosHttpLoggingPolicy, dan akan menyertakan informasi tambahan dalam respons yang relevan untuk diagnostik masalah Cosmos.

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

Demikian pula, pencatatan log dapat diaktifkan untuk satu operasi dengan meneruskan logger ke permintaan tunggal. Namun, jika Anda ingin menggunakan CosmosHttpLoggingPolicy untuk mendapatkan informasi tambahan, argumen enable_diagnostics_logging perlu diberikan pada konstruktor klien.

# This example enables the `CosmosHttpLoggingPolicy` and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

Desain ulang coba

Lihat panduan kami untuk merancang aplikasi yang tangguh dengan Azure Cosmos DB SDK guna mendapatkan panduan tentang cara merancang aplikasi tangguh dan mempelajari semantik pengulangan dari SDK tersebut.

Masalah umum dan solusi

Saran umum

Untuk performa terbaik:

Pastikan aplikasi berjalan di wilayah yang sama dengan akun Azure Cosmos DB Anda.
Periksa penggunaan CPU pada host tempat aplikasi berjalan. Jika penggunaan CPU adalah 50 persen atau lebih, jalankan aplikasi Anda di host dengan konfigurasi yang lebih tinggi. Atau Anda dapat mendistribusikan beban pada lebih banyak komputer.
- Jika menjalankan aplikasi di Azure Kubernetes Service, Anda dapat menggunakan Azure Monitor untuk memantau pemanfaatan CPU.

Periksa metrik portal

Memeriksa metrik portal akan membantu menentukan apakah itu masalah di sisi klien atau layanan yang bermasalah. Misalnya, jika metrik berisi permintaan yang dibatasi dengan tingkat yang tinggi (kode status HTTP 429), yang berarti permintaan tersebut sedang dibatasi, maka periksa bagian Tingkat permintaan terlalu besar.

Pembatasan laju koneksi

Pembatasan koneksi dapat terjadi karena [batas koneksi pada komputer host] atau [Kelelahan port Azure SNAT (PAT) ].

Batas koneksi pada komputer host

Beberapa sistem Linux, seperti Red Hat, memiliki batas atas jumlah total file terbuka. Soket di Linux diimplementasikan sebagai file, sehingga jumlah ini juga membatasi jumlah total koneksi. Jalankan perintah berikut.

ulimit -a

Jumlah file terbuka maksimum yang diizinkan, yang diidentifikasi sebagai "nofile", harus setidaknya dua kali lipat ukuran kumpulan koneksi Anda. Untuk informasi selengkapnya, lihat tips performa Azure Cosmos DB Python SDK.

Kekurangan port Azure SNAT (PAT)

Jika aplikasi Anda disebarkan di Azure Virtual Machines tanpa alamat IP publik, secara default port Azure SNAT membuat koneksi ke titik akhir apa pun di luar VM Anda. Jumlah koneksi yang diizinkan dari VM ke titik akhir Azure Cosmos DB dibatasi oleh konfigurasi Azure SNAT.

Port Azure SNAT hanya digunakan saat VM Anda memiliki alamat IP privat dan proses dari VM mencoba menyambungkan ke alamat IP publik. Ada dua solusi untuk menghindari batasan Azure SNAT:

Menambahkan titik akhir layanan Azure Cosmos DB Anda ke subnet jaringan virtual Azure Virtual Machines Anda. Untuk informasi selengkapnya, lihat Titik akhir layanan Microsoft Azure Virtual Network.

Ketika titik akhir layanan diaktifkan, permintaan tidak lagi dikirimkan dari IP publik ke Azure Cosmos DB. Sebagai gantinya, jaringan virtual dan identitas subnet dikirim. Perubahan ini dapat mengakibatkan firewall turun jika hanya IP publik yang diizinkan. Jika Anda menggunakan firewall, saat Anda mengaktifkan titik akhir layanan, tambahkan subnet ke firewall menggunakan Virtual Network ACL.
Tetapkan IP publik ke Azure VM Anda.

Tidak dapat menjangkau layanan - firewall

azure.core.exceptions.ServiceRequestError: menunjukkan bahwa SDK tidak dapat menjangkau layanan. Ikuti Batas koneksi pada komputer host.

Kegagalan menyambungkan ke emulator Azure Cosmos DB

Sertifikat HTTPS Emulator Azure Cosmos DB ditandatangani sendiri. Agar Python SDK berfungsi dengan emulator, impor sertifikat emulator. Untuk informasi selengkapnya, lihat Mengekspor sertifikat Emulator Azure Cosmos DB.

Proksi HTTP

Jika Anda menggunakan proksi HTTP, pastikan proksi tersebut dapat mendukung jumlah koneksi yang dikonfigurasi di SDK ConnectionPolicy. Jika tidak, Anda akan menghadapi masalah koneksi.

Masalah kueri umum

Metrik kueri akan membantu menentukan di mana kueri menghabiskan sebagian besar waktu. Dari metrik kueri, Anda dapat melihat berapa banyak yang dihabiskan untuk back-end vs klien. Pelajari selengkapnya di panduan performa kueri.

Langkah selanjutnya

Pelajari tentang Panduan performa untuk Python SDK
Pelajari tentang praktik terbaik untuk Python SDK

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-19