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

Artikel
04/13/2024

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 mengajukan masalah GitHub. Jika ada opsi untuk menambahkan tag ke masalah GitHub Anda, tambahkan *Cosmos* tag.

Mencatat dan menangkap diagnostik

Penting

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

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

Pengelogan tingkat DEBUG terperinci, termasuk badan permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan logging_enable argumen:

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 mencatat menggunakan CosmosHttpLoggingPolicy, yang meluas dari inti HttpLoggingPolicyazure , dengan meneruskan pencatat Anda ke logger argumen . Secara default, ia akan menggunakan perilaku dari HttpLoggingPolicy. Meneruskan enable_diagnostics_logging argumen akan mengaktifkan CosmosHttpLoggingPolicy, dan akan memiliki informasi tambahan dalam respons yang relevan dengan penelusuran kesalahan 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, pengelogan dapat diaktifkan untuk satu operasi dengan meneruskan pencatat ke permintaan tunggal. Namun, jika Anda ingin menggunakan CosmosHttpLoggingPolicy untuk mendapatkan informasi tambahan, enable_diagnostics_logging argumen perlu diteruskan di 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)

Rancangan percobaan ulang

Lihat panduan kami untuk merancang aplikasi tangguh dengan Azure Cosmos DB SDK untuk panduan tentang cara merancang aplikasi tangguh dan mempelajari yang merupakan semantik coba lagi dari SDK.

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 di host tempat aplikasi berjalan. Jika penggunaan CPU 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 dengan tarif terbatas yang tinggi (kode status HTTP 429). yang berarti permintaan akan dibatasi, periksa bagian Tingkat permintaan terlalu besar.

Pembatasan koneksi

pembatasan Koneksi ion dapat terjadi karena kelelahan port [batas koneksi pada komputer host] atau [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 angka ini membatasi jumlah total koneksi juga. 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.

Kelelahan port Azure SNAT (PAT)

Jika aplikasi Anda diterapkan di Azure Virtual Machines tanpa alamat IP publik, secara default port Azure SNAT membangun koneksi ke titik akhir 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 pribadi 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 Azure Cosmos DB Emulator ditandatangani sendiri. Agar Python SDK berfungsi dengan emulator, impor sertifikat emulator. Untuk informasi selengkapnya, lihat Mengekspor sertifikat Azure Cosmos DB Emulator.

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 berikutnya

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