Application Real-Time Monitoring Service:Python agent FAQ

aliyun-bootstrap -a install kullanılırken kurulum başarısız oluyor

Aracıyı aliyun-bootstrap -a install komutuyla yüklemek aşağıdaki hataya neden olabilir:

Installation aborted due to download failure.

Bu hata genellikle iki nedenden birinden kaynaklanır:

1. Bir ağ sorunu, aracının OSS uç noktasına erişmesini engelliyor. Ağ bağlantısını doğrulayın.

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]

2. Python yorumlayıcınızda SSL modülü eksik.

python3 -m ssl

Bu komuttan gelen bir hata, SSL modülünün Python yorumlayıcınızda eksik olduğunu gösterir. aliyun-bootstrap betiği bağımlılıkları indirmek için bu modüle ihtiyaç duyduğundan modülü Python ortamınıza yüklemeniz gerekir.

Başlatma hatası: No module named 'aliyun'

Bu hata, aracının uygulamanızın çalışma zamanında bulamadığı bir konuma yüklendiğini gösterir. Uygulamanızın ortamındaki Python yorumlayıcısının Python aracısı bağımlılıklarını bulabilmesini sağlamalısınız.

aliyun-bootstrap'in aracı paketini aranabilir bir yola yüklediğini doğrulamak için uygulamanızın ortamında aşağıdaki komutu çalıştırın:

python3 -m site

Bu komut, Python yorumlayıcısının paketleri bulmak için kullandığı arama yollarını yazdırır. Aşağıdaki örnek dizin yapısında gösterilen Python aracısı bağımlılıkları bu yollardan hiçbirinde bulunamazsa kurulum konumu yanlış demektir.

.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

aliyun-bootstrap paketinin kurulum konumunu belirtmek için aşağıdaki komutu kullanabilirsiniz:

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

${TARGET_PATH} ifadesini ortamınız için doğru yol ile değiştirin. Örneğin yol /root/demo/venv/lib/python3.12/site-packages olabilir.

Flask uygulamalarından veri raporlanmıyor

Hata ayıklama modu etkinleştirildiğinde bir Flask uygulamasını entegre etmek için aliyun-instrument yöntemini kullanamazsınız. Bunun yerine Python aracısını manuel olarak içeri aktarmak için Flask uygulamasının giriş dosyasına aşağıdaki ifadeleri eklemelisiniz. Bu sayede uygulamayı aliyun-instrument ön eki eklemeden başlatabilirsiniz.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Django uygulaması başlatılamıyor

Django uygulamanız başlatılamıyor ve AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF' benzeri bir hata gösteriyorsa DJANGO_SETTINGS_MODULE ortam değişkenini projenizin ayarlar modülüne ayarlayın.

export DJANGO_SETTINGS_MODULE=instrumentation_example.settings

Django uygulamalarından veri raporlanmıyor

Varsayılan olarak python manage.py runserver 0.0.0.0:8080 gibi komutlarla etkinleştirilen Django'nun hot reloading özelliği aracının veri raporlamasını engelleyebilir. Bunu düzeltmek için hot reloading'i devre dışı bırakmak amacıyla --noreload seçeneğini ekleyin:

python manage.py runserver 0.0.0.0:8080 --noreload

Uvicorn uygulamalarından veri raporlanmıyor

Hot reloading (--reload parametresi) veya birden çok worker (--workers parametresi) kullanan bir Uvicorn sunucusu aracının veri raporlamasını engelleyebilir. Bunu çözmek için uygulamanızın giriş dosyasına aşağıdaki satırı ekleyerek Python aracısını manuel olarak içeri aktarmanız gerekir. Uygulamayı başlatırken aliyun-instrument ön ekini kullanmayın.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Aracıyı kaldırma

Python aracısını kaldırmak için aşağıdaki komutu çalıştırın:

aliyun-bootstrap -a uninstall

Belirli bir bölge ve sürüm yükleme

En iyi performans için en yakın bölgeden aracının belirli bir sürümünü yüklemeniz gerekebilir. Aşağıdaki adımları izleyin:

1. Aracının çekileceği bölgeyi belirtmek için ARMS_REGION_ID ortam değişkenini ayarlayın.

export ARMS_REGION_ID=cn-beijing

Desteklenen bölgelerin listesi için bkz. Kullanılabilir bölgeler.

2. Aşağıdaki komutla Python aracısının belirli bir sürümünü yükleyin. Aracının başka bir sürümü yüklüyse önce onu kaldırmanızı öneririz.

# Replace ${version} with the target version number
aliyun-bootstrap -a install -v ${version}

Python aracısını Container Service for Kubernetes (ACK) ve Container Compute Service (ACS)'de ack-onepilot bileşeniyle Python aracısını yükleme bölümünde açıklanan müdahalesiz yöntemle yüklediyseniz aliyun.com/agent-version etiketini ekleyerek aracı sürümünü belirtebilirsiniz. Daha fazla bilgi için bkz. Aracı sürümlerini bağımsız olarak kontrol etme.

Yayınlanan tüm Python aracısı sürümlerinin listesi için bkz. Python aracısı sürüm notları.

Günlük dizinini belirtme

Python aracısı sürümünüzün 1.6.0 veya üzeri olduğundan emin olun. Ardından APSARA_APM_AGENT_WORKSPACE_DIR ortam değişkenini ayarlayabilirsiniz. Aracı günlük dosyalarını ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs dizininde depolar.

Varsayılan olarak aracı günlük dizinini aşağıdaki öncelik sırasına göre belirler:

1. /home/admin/.opt/.apsara-apm/python/logs (ack-onepilot bileşeni için birim dizini)

2. ~/.apsara-apm/python/logs (kullanıcı ana dizini)

3. ./.apsara-apm/python/logs (ana Python giriş dosyasıyla aynı dizin)

Günlük dosya adları aliyun-python-agent-{PID}.log biçimini takip eder; burada {PID} işlem kimliğidir (örneğin aliyun-python-agent-5921.log). Aynı dizinde ayrıca diagnose-{PID}.log tanılama günlük dosyaları bulunur.

Ağ raporlama modunu belirtme

Aracı sürümünüz 1.6.0 veya üzeriyse ağ raporlama modunu belirtmek için PROFILER_NETWORK_STRATEGY ortam değişkenini ayarlayabilirsiniz:

1. internal: Dahili ağ raporlamasını zorlar.

2. public: Genel ağ raporlamasını zorlar.

3. auto: Ağ modunu otomatik olarak algılar (varsayılan davranış).

OpenAI akışında görünmez belirteç kullanımı

Daha fazla bilgi için bkz. Akış çıkışı. Varsayılan olarak OpenAI protokolü akış çağrılarında belirteç kullanımını döndürmez. Bu bilgiyi almak için son veri parçasında belirteç kullanım ayrıntılarını dahil etmek üzere stream_options={"include_usage": true} ayarlayın.

Alt süreçlere aracı enjeksiyonunu önleme

Aracının hedef uygulama tarafından oluşturulan herhangi bir alt sürece enjekte edilmesini önlemek için APSARA_APM_INSTRUMENTATION_CHILD_PROCESS ortam değişkenini false olarak ayarlayın.