FAQ agen Python - Application Real-Time Monitoring Service

Dokumen ini menjawab pertanyaan umum (FAQ) mengenai agen Python.

Instalasi agen gagal saat menggunakan aliyun-bootstrap -a install

Jika instalasi agen gagal ketika Anda menjalankan perintah aliyun-bootstrap -a install, pesan error berikut akan muncul:

Installation aborted due to download failure.

Kegagalan ini biasanya disebabkan oleh salah satu dari dua hal berikut:

Terjadi masalah konektivitas jaringan ke endpoint OSS agen. Periksa koneksi jaringan Anda ke endpoint tersebut.

Interpreter Python diinstal tanpa modul ssl. Untuk memverifikasi hal ini, jalankan perintah berikut:

python3 -m ssl

Jika perintah tersebut mengembalikan error, berarti modul ssl tidak tersedia. Tool aliyun-bootstrap memerlukan modul ssl untuk mengunduh dependensi. Untuk mengatasi masalah ini, instal modul ssl di lingkungan Python Anda.

Instalasi berhasil tetapi aplikasi gagal dimulai dengan kesalahan "No module named 'aliyun'"

Error ini menunjukkan bahwa agen diinstal di lokasi yang tidak dapat ditemukan oleh interpreter Python aplikasi saat runtime. Untuk mengatasinya, pastikan dependensi agen Python berada di path yang dapat ditemukan oleh interpreter Python aplikasi Anda.

Anda dapat menjalankan perintah berikut di lingkungan runtime aplikasi untuk memverifikasi bahwa paket agen diinstal di lokasi yang benar:

python3 -m site

Perintah ini mencetak daftar path pencarian yang digunakan interpreter Python untuk menemukan paket. Jika dependensi agen Python, seperti yang ditunjukkan pada gambar berikut, tidak berada di salah satu path tersebut, artinya aliyun-bootstrap menginstal paket ke lokasi yang salah.

Anda dapat menggunakan perintah berikut untuk menentukan lokasi instalasi yang benar untuk aliyun-bootstrap:

aliyun-bootstrap -a install -t ${TARGET_PATH}

Ganti ${TARGET_PATH} dengan path paket yang benar. Sebagai contoh, berdasarkan gambar sebelumnya, ${TARGET_PATH} adalah /root/demo/venv/lib/python3.12/site-packages.

Tidak ada data dari aplikasi Flask

Aplikasi Flask dalam mode debug tidak dapat diintegrasikan menggunakan aliyun-instrument. Sebagai gantinya, tambahkan pernyataan berikut ke file entri Flask untuk mengimpor agen Python secara manual, lalu jalankan aplikasi tanpa awalan aliyun-instrument.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Aplikasi Django gagal dimulai setelah instrumentasi

Jika aplikasi Django Anda gagal dijalankan dan menampilkan error startup seperti AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF', atur variabel lingkungan DJANGO_SETTINGS_MODULE ke nama modul pengaturan proyek Anda.

export DJANGO_SETTINGS_MODULE=instrumentation_example.settings

Tidak ada data yang dilaporkan untuk aplikasi Django

Fitur auto-reloading di Django diaktifkan secara default saat Anda menjalankan aplikasi dengan perintah seperti python manage.py runserver 0.0.0.0:8080. Nonaktifkan fitur ini dengan menambahkan opsi --noreload:

python manage.py runserver 0.0.0.0:8080 --noreload

Tidak ada data yang dilaporkan untuk aplikasi yang menggunakan server Uvicorn

Jika Anda mengaktifkan hot reloading menggunakan parameter --reload atau menjalankan beberapa worker dengan parameter --workers pada server Uvicorn, agen tidak dapat melaporkan data. Untuk mengatasinya, tambahkan pernyataan berikut ke file entri aplikasi guna mengimpor agen Python secara manual. Saat menjalankan aplikasi, Anda tidak perlu menambahkan awalan aliyun-instrument.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Menguninstall agen

Untuk menguninstall agen Python, jalankan perintah berikut:

aliyun-bootstrap -a uninstall

Cara menginstal probe untuk wilayah dan versi tertentu

Untuk pengalaman terbaik, Anda mungkin perlu menginstal versi tertentu dari agen dari wilayah terdekat. Prosedurnya sebagai berikut:

Atur variabel lingkungan ARMS_REGION_ID untuk menentukan wilayah tempat mengambil agen. Contohnya:

export ARMS_REGION_ID=cn-beijing

Untuk daftar semua wilayah yang didukung, lihat Wilayah yang tersedia.

Jalankan perintah berikut untuk menginstal versi tertentu dari agen Python. Jika Anda telah menginstal versi lain, uninstall terlebih dahulu.

# Ganti ${version} dengan nomor versi aktual.
aliyun-bootstrap -a install -v ${version}

Jika Anda menginstal agen Python menggunakan metode non-intrusif yang dijelaskan dalam Instal agen Python menggunakan komponen ack-onepilot di Container Service for Kubernetes (ACK) dan Container Compute Service (ACS), Anda dapat merujuk ke Mengontrol versi agen secara manual untuk menambahkan tag aliyun.com/agent-version guna menentukan nomor versi agen.

Untuk daftar semua versi agen Python yang telah dirilis, lihat Panduan Versi Agen Python.

Menentukan direktori log untuk agen Python

Untuk agen Python V1.6.0 atau yang lebih baru, Anda dapat mengatur variabel lingkungan APSARA_APM_AGENT_WORKSPACE_DIR untuk menentukan direktori log kustom. Agen Python menyimpan file log-nya di direktori ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs.

Secara default, probe memilih direktori log berdasarkan prioritas berikut:

/home/admin/.opt/.apsara-apm/python/logs (direktori volume untuk ack-onepilot)
~/.apsara-apm/python/logs (direktori home pengguna)
./.apsara-apm/python/logs (direktori yang sama dengan file Python utama)

Menentukan mode jaringan untuk agen Python

Untuk versi agen 1.6.0 atau yang lebih baru, Anda dapat mengatur variabel lingkungan PROFILER_NETWORK_STRATEGY untuk menentukan mode jaringan dalam pelaporan data:

internal: Memaksa agen melaporkan data melalui jaringan internal.
public: Memaksa agen melaporkan data melalui jaringan publik.
auto: Mendeteksi mode jaringan secara otomatis. Ini adalah perilaku default.