Python探針使用常見問題 - Application Real-Time Monitoring Service

本文檔介紹了Python探針常見問題，協助您更好地使用Python探針。

通過aliyun-bootstrap -a install安裝探針失敗

當使用aliyun-bootstrap -a install安裝探針失敗時，可能會列印如下錯誤資訊：

Installation aborted due to download failure.

此類安裝失敗通常由兩種情況導致：

到探針OSS端點的網路連通性有問題，請檢查到探針OSS端點額度網路連通性。

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]

Python解譯器在安裝時缺失ssl模組。

python3 -m ssl

如果執行有報錯，說明您的Python解譯器在安裝的時候沒有安裝ssl依賴，aliyun-bootstrap在執行依賴下載時需要依賴ssl，請您在您的Python解譯器環境中安裝ssl模組。

通過aliyun-bootstrap安裝探針成功，但是啟動發現No module named 'aliyun'報錯

出現以上錯誤說明探針的安裝位置有誤，導致在運行時無法找到探針包，您需要保證在您的運行環境中的Python解譯器可以搜尋到Python探針的相關依賴。

您可以在您的運行環境中執行以下命令來確認aliyun-bootstrap是否把探針包安裝到了正確的位置：

python3 -m site

上述命令將會列印出Python解譯器去尋找探針包的搜尋順序，如果在以上的路徑中，均不存在Python探針相關的依賴（如下所示的依賴），則說明aliyun-bootstrap裝包的位置錯誤。

.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的包安裝位置：

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

可以將上面的TARGET_PATH替換為實際需要去裝包的路徑，比如TARGET_PATH可能是/root/demo/venv/lib/python3.12/site-packages。

Flask應用接入無資料

Flask應用在開啟debug模式時無法使用aliyun-instrument方式進行接入，需要在Flask的入口檔案添加下面的語句來手動引入Python探針，在啟動應用時無需添加aliyun-instrument首碼。

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Django應用接入後啟動報錯

如果Django應用啟動後碰到類似AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF'的啟動錯誤，可以設定DJANGO_SETTINGS_MODULE環境變數，並將模組的名字替換成專案實際的模組名。

export DJANGO_SETTINGS_MODULE=instrumentation_example.settings

Django應用接入後無資料

如果使用了Django的reload能力（通過類似python manage.py runserver 0.0.0.0:8080啟動Django應用將會預設開啟自動載入），可以添加--noreload選項關閉此能力：

python manage.py runserver 0.0.0.0:8080 --noreload

使用uvicorn伺服器啟動應用接入無資料

如果您在使用uvicorn伺服器時通過--reload參數開啟了熱載入能力，或者通過--workers啟動多個worker處理請求將會導致探針無法上報資料，需要在應用的入口檔案添加下面的語句來手動引入Python探針，在啟動應用時無需添加aliyun-instrument首碼。

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

如何卸載探針

請通過以下命令卸載Python探針

aliyun-bootstrap -a uninstall

如何安裝指定地區與版本的探針

在實際使用時，使用者可能需要從最近的地區安裝固定版本的探針以獲得最好的使用體驗，實際操作如下：

設定ARMS_REGION_ID環境變數，指定探針拉取的地區。

export ARMS_REGION_ID=cn-beijing

具體的開服地區請參考：開服地區

通過以下命令，安裝固定版本的Python探針，如果已經安裝了其他版本的探針，建議先把原探針卸載乾淨。

# ${version}替換為實際的版本號碼
aliyun-bootstrap -a install -v ${version}

如果您是通過Container Service ACK 和容器計算服務 ACS 通過 ack-onepilot 組件安裝 Python 探針中的無侵入方式接入Python探針，可以參考自主控制探針版本添加aliyun.com/agent-version標籤指定探針版本號碼。

請參考探針（Python Agent）版本說明查看所有發行的Python探針版本。

如何指定Python探針的日誌目錄

請首先保證您的Python探針版本不低於1.6.0，之後可以設APSARA_APM_AGENT_WORKSPACE_DIR環境變數，Python探針的記錄檔將會存放在${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs目錄下。

預設情況下，探針將會按照以下優先順序來指定探針的日誌目錄：

/home/admin/.opt/.apsara-apm/python/logs(ack-onepilot的volume目錄)
~/.apsara-apm/python/logs(使用者家目錄)
./.apsara-apm/python/logs(Python主檔案的同級目錄)

如何指定Python探針上報網路模式

如果您的探針版本>=1.6.0可以通過設定PROFILER_NETWORK_STRATEGY環境變數來指定探針的上報網路模式：

internal：強制內網上報。
public：強制公網上報。
auto：自動探測（預設行為）。

為什麼OpenAI流式調用看不到Token消耗？

請參考流式輸出文檔，OpenAI 協議預設不返回 Token 消耗量，需設定stream_options={"include_usage": true}，使最後一個返回的資料區塊包含Token消耗資訊。

如何不對目標進程的子進程進行探針注入

可以通過設定APSARA_APM_INSTRUMENTATION_CHILD_PROCESS環境變數設定成false避免對目標進程子進程的探針注入。