ARMS 支持通过 Python 探针对 RAGFlow 应用进行可观测，Python 探针是阿里云可观测产品自研的 Python 语言的可观测采集探针，基于 OpenTelemetry 标准实现了自动化埋点能力。
前提条件
确保已完成 RAGFlow 的部署。此处提供ACK中部署操作。
接入操作
RAGFlow 部署在 Kubernetes 环境
容器服务 ACK 和容器计算服务 ACS接入
步骤一：探针接入助手（ack-onepilot）安装
登录容器服务管理控制台，在集群列表页面单击 RAGFlow 集群名称。
在左侧导航栏单击组件管理，然后在右上角通过关键字搜索ack-onepilot。
在ack-onepilot卡片上单击安装。配置相关的参数，建议使用默认值，单击确认。
说明ack-onepilot的版本需要5.1.1及以上，ack-onepilot组件默认支持1000个pod规模，集群pod每超过1000个，ack-onepilot资源对应的CPU请增加0.5核、内存请增加512 MB。
安装完成后，可以在组件管理页面升级、配置或卸载ack-onepilot组件。
步骤二：修改配置以启动 RAGFlow 监控
在目标集群的工作负载 > 无状态页面进入，单击RAGFlow所在行右侧操作列的编辑。
在环境变量区域添加变量，名称为
PYTHONPATH，值为$PYTHONPATH:/ragflow/并在右上角单击更新，保存配置。在目标集群的工作负载 > 无状态页面进入，单击RAGFlow所在行右侧操作列的
后进行YAML编辑。说明YAML编辑需要ARMS资源访问权限，可参考容器服务 ACK 和容器计算服务 ACS 通过 ack-onepilot 组件安装 Python 探针中步骤三：授予 ARMS 资源的访问权限。
将以下
labels添加到spec.template.metadata层级下。labels: aliyun.com/app-language: python # Python应用必填，标明此应用是Python应用。 armsPilotAutoEnable: 'on' armsPilotCreateAppName: "ragflow" # 应用在ARMS中的展示名称
自建集群接入
步骤一：探针接入助手（ack-onepilot）安装
执行以下
wget命令下载ack-onepilot安装包，并解压下载的安装包。wget 'https://aliacs-app-catalog.oss-cn-hangzhou.aliyuncs.com/charts-incubator/ack-onepilot-5.1.1.tgz'编辑解压后安装包下的values.yaml文件，根据实际情况修改以下参数，然后保存。
registry: registry-__ACK_REGION_ID__.ack.aliyuncs.com/acs/ cluster_id: __ACK_CLUSTER_ID__ accessKey: __ACCESSKEY__ accessKeySecret: __ACCESSKEY_SECRET__ uid: "__ACK_UID__" region_id: __ACK_REGION_ID__registry：ack-onepilot镜像地址。cluster_id：自定义Kubernetes集群ID，集群的唯一标识。建议格式为<uid>-<clusterid>。accessKey和accessKeySecret：阿里云账号的AccessKey ID和AccessKey Secret。获取方法，请参见创建AccessKey。其中对应账号需包含AliyunARMSFullAccess和AliyunSTSAssumeRoleAccess权限。uid：阿里云账号ID。将鼠标悬浮于阿里云控制台右上角的头像上可以获取。region_id：阿里云地域ID，应用监控支持的地域，请参见开服地域。（可选）若目标集群是边缘集群，请通过添加nodeSelector注解将ack-onepilot组件调度到云上，以保证ack-onepilot的正常工作。
kind: Deployment apiVersion: apps/v1 metadata: name: xxx namespace: xxx spec: template: spec: nodeSelector: # 可替换成实际的node selector alibabacloud.com/is-edge-worker: "false"在ack-onepilot安装包外执行命令安装。
helm3 upgrade --install ack-onepilot ack-onepilot --namespace ack-onepilot --create-namespace
步骤二：修改配置以启动 RAGFlow 监控
如果您通过 helm 来进行 RAGFlow 的部署，应该启动了名为 ragflow 的 Deployment。
执行以下命令查看目标应用的YAML文件。
kubectl get deployment ragflow -o yaml编辑该YAML文件，在 spec.template.spec.containers 层级下添加环境变量
PYTHONPATH：env: - name: PYTHONPATH value: "$PYTHONPATH:/ragflow/"添加 ARMS 监控标签。
labels: aliyun.com/app-language: python # 标明这是 Python 应用 armsPilotAutoEnable: 'on' armsPilotCreateAppName: "ragflow" # 应用在 ARMS 中的展示名称
非Kubernetes环境
适用于以源码启动、Docker 容器手动运行、Docker Compose 编排等方式部署 RAGFlow 的用户。常见形式包括：
直接通过
bash /ragflow/docker/launch_backend_service.sh启动应用。使用
python api/ragflow_server.py命令运行ragflow服务。通过
docker-compose.yml文件等方式编排并启动容器服务。
源码启动
步骤一：配置环境变量
export ARMS_APP_NAME=xxx # 应用名称。
export ARMS_REGION_ID=xxx # 对应的阿里云账号的RegionID。
export ARMS_LICENSE_KEY=xxx # 阿里云 LicenseKey。其中LicenseKey可以通过OpenAPI获取，具体方法，参见DescribeTraceLicenseKey - 列出LicenseKey。
步骤二：下载并安装 Python 探针包
下载 Python 探针压缩包，请将
regionID替换成实际的开服地域，如cn-hangzhou。wget http://arms-apm-${regionID}.oss-${regionID}.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz解压并安装Python 探针。
tar -zxvf aliyun-python-agent.tar.gz uv pip install ./target/*.whl
步骤三：运行 Python 应用
如下修改启动命令运行 RAGFlow：
直接启动：
aliyun-instrument python api/ragflow_server.py。脚本启动：在
ragflow/docker/launch_backend_service.sh中将$PY api/ragflow_server.py修改为aliyun-instrument $PY api/ragflow_server.py。
容器启动
步骤一：配置环境变量
对于Docker环境，可以参考以下Dockerfile示例修改您的Dockerfile文件。
# 添加环境变量
ENV ARMS_APP_NAME={AppName}
ENV ARMS_REGION_ID={regionId}
ENV ARMS_LICENSE_KEY={licenseKey}其中LicenseKey可以通过OpenAPI获取，具体方法，参见DescribeTraceLicenseKey - 列出LicenseKey。
步骤二：修改服务启动脚本 entrypoint.sh
修改
ragflow/docker/entrypoint.sh，在启动脚本前面添加如下内容，其中regionID替换成实际的开服地域 ，如cn-hangzhou。wget http://arms-apm-${regionID}.oss-${regionID}.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz tar -zxvf aliyun-python-agent.tar.gz uv pip install ./target/*.whl启动命令中将
$PY api/ragflow_server.py修改为aliyun-instrument $PY api/ragflow_server.py
