Python探针使用常见问题

通过aliyun-bootstrap -a install安装探针失败

当使用aliyun-bootstrap -a install安装探针失败时，可能会打印如下错误信息：

Installation aborted due to download failure.

此类安装失败通常由两种情况导致：

1. 到探针OSS端点的网络连通性有问题，请检查到探针OSS端点额度网络连通性：

2. 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装包的位置错误。

您可以通过如下命令来强制指定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

使用uvicorn服务器启动应用接入无数据

如果您在使用uvicorn服务器时通过--reload参数开启了热加载能力，将会导致探针无法上报数据，需要在应用的入口文件添加下面的语句来手动引入Python探针，在启动应用时无需添加aliyun-instrument前缀。

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

如何卸载探针

请通过以下命令卸载Python探针

aliyun-bootstrap -a uninstall

如何安装指定地域与版本的探针

在实际使用时，用户可能需要从最近的地域安装固定版本的探针以获得最好的使用体验，实际操作如下：

1. 设置ARMS_REGION_ID环境变量，指定探针拉取的区域，如：

export ARMS_REGION_ID=cn-beijing

具体的开服区域请参考：开服地域

2. 通过以下命令，安装固定版本的Python探针：

# ${version}替换为实际的版本号
aliyun-bootstrap -a install -v ${version}

请参考探针（Python Agent）版本说明查看所有已发布的Python探针版本。

如何指定Python探针的日志目录

请首先保证您的Python探针版本不低于1.6.0，之后可以设APSARA_APM_AGENT_WORKSPACE_DIR环境变量，Python探针的日志文件将会存放在${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs目录下。