Observability Phoenix 故障排查

# Phoenix 故障排除指南 ## 安装问题 ### 找不到包 **错误**: `ModuleNotFoundError: No module named 'phoenix'` **修复**: bash pip install arize-phoenix # 验证安装 python -c "import phoenix as px; print(px.__version__)" ### 依赖冲突 **错误**: `ImportError: cannot import name 'X' from 'Y'` **修复**: bash # 创建干净的环境 python -m venv venv source venv/bin/activate # 安装 Phoenix pip install arize-phoenix # 如果使用特定功能 pip install arize-phoenix[embeddings] pip install arize-phoenix-otel pip install arize-phoenix-evals ### 与 OpenTelemetry 的版本冲突 **错误**: `ImportError: cannot import name 'TracerProvider'` **修复**: bash # 确保版本兼容 pip install opentelemetry-api>=1.20.0 pip install opentelemetry-sdk>=1.20.0 pip install arize-phoenix-otel ## 服务器问题 ### 端口已被占用 **错误**: `OSError: [Errno 48] Address already in use` **修复**: bash # 查找使用该端口的进程 lsof -i :6006 # 终止进程 kill -9 # 或使用其他端口 phoenix serve --port 6007 ### 数据库连接失败 **错误**: `sqlalchemy.exc.OperationalError: could not connect to server` **修复**: bash # 对于 PostgreSQL，验证连接 psql $PHOENIX_SQL_DATABASE_URL -c "SELECT 1" # 检查环境变量 echo $PHOENIX_SQL_DATABASE_URL # 对于 SQLite，检查权限 ls -la $PHOENIX_WORKING_DIR ### 服务器启动时崩溃 **错误**: `RuntimeError: Event loop is closed` **修复**: python # 在 Notebook 中，确保正确的异步处理 import nest_asyncio nest_asyncio.apply() import phoenix as px session = px.launch_app() ### 内存问题 **错误**: `MemoryError` 或服务器变慢 **修复**: bash # 在 Docker 中增加可用内存 docker run -m 4g arizephoenix/phoenix:latest # 或清理旧数据 from phoenix import Client client = Client() # 删除旧追踪 (参考 advanced-usage.md 中的清理脚本) ## 追踪问题 ### 追踪信息未显示 **问题**: 已注入的代码运行但 Phoenix 中没有追踪信息 **解决方案**: 1. **验证端点**: python from phoenix.otel import register # 确保端点正确 tracer_provider = register( project_name="my-app", endpoint="http://localhost:6006/v1/traces" # 包含 /v1/traces ) 2. **强制刷新追踪**: python from opentelemetry import trace # 强制发送挂起的追踪 trace.get_tracer_provider().force_flush()