FAQ agen Python - Application Real-Time Monitoring Service

FAQ ini menjawab pertanyaan umum mengenai agen Python.

Instalasi gagal saat menggunakan aliyun-bootstrap -a install

Menginstal agen dengan perintah aliyun-bootstrap -a install dapat menyebabkan error berikut:

Installation aborted due to download failure.

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

Terjadi masalah jaringan yang menghalangi agen mengakses titik akhir OSS-nya. Verifikasi koneksi jaringan.

Starting Aliyun Python Agent installation...
agent download url: https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz
Checking network connectivity...
Downloading agent from https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz...
Downloading: 100%|████████████████████████████████████████████████████████████| 1.00M/1.00M [00:00<00:00, 6.21MB/s]
Extracting wheels from archive...
Extracting files: 100%|███████████████████████████████████████████████████████| 27/27 [00:00<00:00, 2151.05file/s]
Found 27 wheel files
Installing 27 packages...
Installing packages:   0%|                                                   | 0/27 [00:00<?, ?pkg/s]
Installing packages:   0%|                                                   | 0/27 [00:00<?, ?pkg/s]

Interpreter Python Anda tidak memiliki modul SSL.

python3 -m ssl

Jika perintah tersebut menghasilkan error, berarti modul SSL tidak tersedia di interpreter Python Anda. Skrip aliyun-bootstrap memerlukan modul ini untuk mengunduh dependensi, sehingga Anda harus menginstalnya di lingkungan Python Anda.

Error saat startup: No module named 'aliyun'

Error ini menunjukkan bahwa agen diinstal di lokasi yang tidak dapat ditemukan oleh aplikasi Anda saat runtime. Pastikan interpreter Python di lingkungan aplikasi Anda dapat menemukan dependensi agen Python tersebut.

Jalankan perintah berikut di lingkungan aplikasi Anda untuk memverifikasi bahwa aliyun-bootstrap menginstal paket agen ke jalur yang dapat dicari:

python3 -m site

Perintah ini mencetak daftar jalur pencarian yang digunakan interpreter Python untuk menemukan paket. Jika dependensi agen Python, seperti yang ditunjukkan dalam struktur direktori contoh di bawah, tidak ditemukan di salah satu jalur tersebut, maka lokasi instalasinya salah.

.venv
  bin
  lib
    python3.12
      site-packages  library root
        _distutils_hack
        aliyun
          instrumentation
          opentelemetry
          sdk
          semconv
            __init__.py
        aliyun_instrumentation_dashscope-1.0.0.dist-info
        aliyun_instrumentation_dify-1.1.0.dist-info
        aliyun_instrumentation_langchain-1.1.0.dist-info
        aliyun_instrumentation_llama_index-1.0.3.dev0.dist-info
        aliyun_instrumentation_openai-1.0.1.dist-info
        aliyun_instrumentation_vllm-0.1.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_common-1.25.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_grpc-1.25.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_http-1.25.0.dist-info
        aliyun_opentelemetry_instrumentation-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_aiohttp_client-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_asgi-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_django-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_fastapi-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_flask-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_httpx-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_logging-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_redis-0.46b0.dev0.dist-info

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

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

Ganti ${TARGET_PATH} dengan jalur yang sesuai untuk lingkungan Anda. Contohnya, jalurnya bisa berupa /root/demo/venv/lib/python3.12/site-packages.

Tidak ada data yang dilaporkan dari aplikasi Flask

Anda tidak dapat menggunakan metode aliyun-instrument untuk mengintegrasikan aplikasi Flask ketika mode debug diaktifkan. Sebagai gantinya, tambahkan pernyataan berikut ke file entri aplikasi Flask untuk mengimpor agen Python secara manual. Hal ini memungkinkan Anda menjalankan aplikasi tanpa menambahkan awalan aliyun-instrument.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Aplikasi Django gagal dijalankan

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

export DJANGO_SETTINGS_MODULE=instrumentation_example.settings

Tidak ada data yang dilaporkan dari aplikasi Django

Fitur hot reloading Django, yang diaktifkan secara default dengan perintah seperti python manage.py runserver 0.0.0.0:8080, dapat mencegah agen melaporkan data. Untuk memperbaikinya, tambahkan opsi --noreload untuk menonaktifkan hot reloading:

python manage.py runserver 0.0.0.0:8080 --noreload

Tidak ada data yang dilaporkan dari aplikasi Uvicorn

Menggunakan server Uvicorn dengan hot reloading (parameter --reload) atau multiple workers (parameter --workers) dapat mencegah agen melaporkan data. Untuk mengatasi hal ini, impor agen Python secara manual dengan menambahkan baris berikut ke file entri aplikasi Anda. Jangan gunakan awalan aliyun-instrument saat menjalankan aplikasi.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Uninstal agen

Untuk menguninstal agen Python, jalankan perintah berikut:

aliyun-bootstrap -a uninstall

Instal versi dan wilayah tertentu

Untuk performa optimal, Anda mungkin perlu menginstal versi agen tertentu dari wilayah terdekat. Ikuti langkah-langkah berikut:

Atur variabel lingkungan ARMS_REGION_ID untuk menentukan wilayah tempat agen diambil.

export ARMS_REGION_ID=cn-beijing

Untuk daftar wilayah yang didukung, lihat Wilayah yang tersedia.

Instal versi tertentu dari agen Python dengan perintah berikut. Jika versi agen lain sudah terinstal, kami menyarankan untuk menguninstalnya terlebih dahulu.

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

Jika Anda menginstal agen Python menggunakan metode non-intrusif yang dijelaskan dalam Instal agen Python dengan komponen ack-onepilot di Container Service for Kubernetes (ACK) dan Container Compute Service (ACS), Anda dapat menentukan versi agen dengan menambahkan label aliyun.com/agent-version. Untuk informasi lebih lanjut, lihat Kontrol versi agen secara independen.

Untuk daftar semua versi agen Python yang telah dirilis, lihat Catatan rilis agen Python.

Tentukan direktori log

Pastikan versi agen Python Anda adalah 1.6.0 atau lebih baru. Anda kemudian dapat mengatur variabel lingkungan APSARA_APM_AGENT_WORKSPACE_DIR. Agen menyimpan file log-nya di direktori ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs.

Secara default, agen menentukan direktori log berdasarkan urutan prioritas berikut:

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

Tentukan mode pelaporan jaringan

Jika versi agen Anda adalah 1.6.0 atau lebih baru, Anda dapat mengatur variabel lingkungan PROFILER_NETWORK_STRATEGY untuk menentukan mode pelaporan jaringan:

internal: Memaksa pelaporan melalui jaringan internal.
public: Memaksa pelaporan melalui jaringan publik.
auto: Mendeteksi mode jaringan secara otomatis (perilaku default).

Penggunaan token tidak terlihat dalam streaming OpenAI

Untuk informasi lebih lanjut, lihat Output streaming. Secara default, protokol OpenAI tidak mengembalikan informasi penggunaan token dalam panggilan streaming. Untuk menerima informasi ini, atur stream_options={"include_usage": true} agar detail penggunaan token disertakan dalam chunk data terakhir.

Cegah injeksi agen ke proses anak

Untuk mencegah agen melakukan injeksi ke proses anak apa pun yang dibuat oleh aplikasi target, atur variabel lingkungan APSARA_APM_INSTRUMENTATION_CHILD_PROCESS ke false.