Phoenix Python Tracing 接入指南用 arize-phoenix-otel 在 5 分钟内完成 LLM 应用追踪配置【免费下载链接】phoenixAI Observability Evaluation项目地址: https://gitcode.com/gh_mirrors/phoenix13/phoenix本篇指南以 Phoenix 仓库中phoenix-tracingskill 的setup-python.md为骨架系统讲解如何在 Python 应用中通过arize-phoenix-otel包完成 OpenInference / OTel 追踪配置从 3 行代码的快速接入到环境变量、.env.phoenix凭证文件、register()全参数解析、自动插桩与生产级批处理配置。读完你能够独立把任意 Python LLM 应用OpenAI、LangChain、LlamaIndex 等接入 Phoenix 的可观测平台并理解底层端点构造、配置优先级与故障排查路径。背景这份文档在 Phoenix 中的定位setup-python.md是 Phoenix 仓库 phoenix-tracing skill 中优先级标注为Critical所有追踪场景的必读前置的参考文档它定义的是“把追踪从零打通”的标准步骤安装arize-phoenix-otel、配置 collector 端点与项目名、开启自动插桩、验证 traces 是否到达 Phoenix UI。其配套文档还包括自动插桩细节instrumentation-auto-python.md、项目组织projects-python.md与生产加固production-python.md本指南会在相应小节顺带引用。在仓库源码中本指南对应的实现位于 packages/phoenix-otel核心代码是 src/phoenix/otel/otel.py 中的register()与各类 Phoenix-aware 的 OTel 组件以及 src/phoenix/otel/settings.py 中的环境变量解析逻辑。安装与三行快速开始安装 SDKpip install arize-phoenix-otel版本与运行环境约束以当前仓库的 pyproject.toml 为准requires-python 3.10, 3.15classifiers 中显式列出了 Python 3.10、3.11、3.12、3.13文档所述 “Supported: Python 3.10–3.13” 即指此范围3.14 亦在包元数据中声明。arize-phoenix-otel是对 OpenTelemetry 原语的轻量封装提供 Phoenix 感知的默认值并依赖openinference-instrumentation、opentelemetry-sdk、opentelemetry-exporter-otlp等底层组件见 pyproject.toml因此不需要额外安装裸 OTel SDK。快速开始3 行from phoenix.otel import register register(project_namemy-app, auto_instrumentTrue)默认连接本机 Phoenix 实例HTTP OTLP 为http://localhost:6006追加/v1/tracesgRPC 使用默认端口4317由 settings.py 中的GRPC_PORT 4317定义可用PHOENIX_GRPC_PORT覆盖。auto_instrumentTrue会自动插桩所有已安装的 OpenInference 受支持库。先启动 Phoenix 服务端追踪数据需要一个接收端。仓库文档start-phoenix.mdx给出了三种启动方式本地终端uvx arize-phoenix serve或pip install arize-phoenix phoenix serve见 launch-phoenix-terminal.mdx容器docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest见 launch-phoenix-docker.mdx自托管参考仓库 self-hosting 相关文档。Phoenix 服务端同时监听6006UI 与 OTLP HTTP与4317OTLP gRPC启动后保持运行即可。配置方式全景register()的配置来源按优先级分为三层代码参数 进程环境变量 .env.phoenix文件 内置默认值。下面逐一展开。环境变量推荐环境变量用途示例PHOENIX_API_KEYPhoenix Cloud 鉴权必填自托管开启了鉴权时同样适用your-api-keyPHOENIX_COLLECTOR_ENDPOINTCollector 端点可指向本地或云http://localhost:6006PHOENIX_PROJECT项目名规范变量优先my-appPHOENIX_PROJECT_NAME项目名受支持的别名my-appPHOENIX_GRPC_PORT覆盖 gRPC 默认端口 43174317PHOENIX_CLIENT_HEADERS自定义 HTTP 头W3C Baggage 格式URL 编码AuthorizationBearer%20tokenPHOENIX_DISCOVER_CONFIG设为false/0/no/off可禁用.env.phoenix发现falseexport PHOENIX_API_KEYyour-api-key # Phoenix Cloud 必需 export PHOENIX_COLLECTOR_ENDPOINThttp://localhost:6006 # 或云实例 URL export PHOENIX_PROJECTmy-app # 可选PHOENIX_PROJECT_NAME 是受支持别名关于PHOENIX_PROJECT与PHOENIX_PROJECT_NAME的优先级PHOENIX_PROJECT是规范项目名变量并优先采用PHOENIX_PROJECT_NAME是受支持的别名。若两者同时设置且值不同规范变量生效且 SDK 会记录一次同时点名两个变量的一次性警告。该行为在 settings.py 的get_env_project_name()中实现并由 test_settings.py 的test_get_env_project_name验证两者取值相同时不算冲突。此外端点解析还有一层 OTel 标准回退当PHOENIX_COLLECTOR_ENDPOINT未设置时会回退读取OTEL_EXPORTER_OTLP_ENDPOINT见 settings.py 的get_env_collector_endpoint()这与 OTel 生态工具链保持兼容。凭证文件发现.env.phoenix当某个设置既没有作为参数传入、也没有在进程环境中设置时register()会从当前工作目录向上逐级查找最近的.env.phoenix文件一直找到文件系统根目录取首个匹配并以 dotenv 格式读取其中的PHOENIX_前缀键# .env.phoenix PHOENIX_COLLECTOR_ENDPOINThttp://localhost:6006 PHOENIX_API_KEYyour-api-key这条机制非常适合凭证交接场景把 API Key 等敏感配置放在项目根目录的.env.phoenix中不进代码、不进 shell 历史。源码层面的关键行为settings.py优先级显式参数和进程环境变量永远优先——文件绝不覆盖任何已设置的值分组解析凭证组PHOENIX_API_KEY、PHOENIX_CLIENT_HEADERS、OTEL_EXPORTER_OTLP_HEADERS与服务器位置组PHOENIX_COLLECTOR_ENDPOINT、OTEL_EXPORTER_OTLP_ENDPOINT、PHOENIX_GRPC_PORT各自作为一个整体从单一来源层解析避免“文件里的 gRPC 端口改写进程提供的端点”这类跨层混用白名单只读取PHOENIX_前缀且键名合法的条目OTEL_EXPORTER_OTLP_ENDPOINT这类非PHOENIX_键会被忽略对应测试test_non_phoenix_keys_ignored见 test_settings.py格式支持空行与#注释被跳过、支持export前缀、支持单双引号包裹的值、自动去除键值两侧空白见test_parse_env_file的参数化用例test_settings.py安全校验文件必须是普通文件且归当前用户所有_is_trusted_env_file_statsettings.py若文件权限过宽其他用户可读会警告建议收紧权限文件大小上限 64KB超出则忽略无效 UTF-8 内容被忽略缓存发现结果按工作目录缓存于进程生命周期内包括“未找到文件”这一结果。长驻进程如 notebook在创建或修改文件后需要调用phoenix.otel.settings.clear_env_file_cache()让后续解析重新发现settings.py测试见test_clear_env_file_cache_picks_up_new_filetest_settings.py禁用设置PHOENIX_DISCOVER_CONFIGfalse可整体关闭文件发现仅从进程环境读取该开关。Python 代码配置from phoenix.otel import register tracer_provider register( project_namemy-app, # 项目名 endpointhttp://localhost:6006, # Phoenix 端点 auto_instrumentTrue, # 自动插桩受支持的库 batchTrue, # 使用 BatchSpanProcessor生产推荐 )register()的完整签名与行为见 otel.py参数说明默认值project_name项目名覆盖PHOENIX_PROJECT/PHOENIX_PROJECT_NAME环境变量未设置时取defaultendpointPhoenix / Collector URL覆盖PHOENIX_COLLECTOR_ENDPOINT环境变量再缺省为本地http://localhost:6006auto_instrument是否自动插桩所有已安装的 OpenInference 库FalsebatchTrue用BatchSpanProcessor生产推荐False用SimpleSpanProcessorFalse见下方说明protocolhttp/protobuf或grpcNone按端点推断headers自定义导出请求头覆盖PHOENIX_CLIENT_HEADERS环境变量api_keyAPI Key自动转为Authorization: Bearer key头环境变量set_global_tracer_provider是否把返回的 TracerProvider 设为全局默认Trueverbose是否在 stdout 打印追踪配置摘要True关于batch默认值的重要更正skill 文档setup-python.md的参数表中写有 “default: True, production-recommended”但当前仓库源码register()的签名是batch: bool Falseotel.py即未显式指定时默认使用SimpleSpanProcessor逐条导出。这与仓库 README 中“生产配置请显式传入batchTrue”的示例一致。生产环境务必显式开启batchTrue并将batch默认值视为文档与实现之间的差异点。端点路径前缀HTTPregister()会在 HTTP 端点后追加/v1/traces同时保留已有路径前缀因此 Phoenix 部署在反向代理之后也能正常工作——endpointhttp://host/prefix实际发送到http://host/prefix/v1/traces若端点已以/v1/traces结尾带或不带尾部斜杠则原样使用、不会重复追加。该逻辑在 otel.py 的_construct_http_endpoint()中实现并由 test_otel.py 的test_construct_http_endpoint参数化验证。对 Phoenix Cloudapp.phoenix.arize.com还会把/s/{space_id}空间路径转换为/s/{space_id}/v1/tracesotel.py。register()源码级解析从 otel.py 可以看到register()内部做了五件事资源与项目名绑定把项目名写入 OTel Resource 的openinference.project.name属性。若用户传入了自定义resource则通过existing_resource.merge(project_resource)合并而不是覆盖otel.py因此service.name等自定义属性得以保留凭证注入api_key参数被转换为headers[authorization] Bearer {api_key}otel.py与PHOENIX_API_KEY环境变量经get_env_phoenix_auth_header()生成的头格式一致SpanProcessor 选择batchTrue时挂载BatchSpanProcessor否则挂载SimpleSpanProcessorotel.py全局默认默认调用trace_api.set_tracer_provider()把 provider 设为 OpenTelemetry 全局默认otel.py框架级 SDK 无需额外绑定即可取用 tracer自动插桩auto_instrumentTrue时调用_auto_instrument_installed_openinference_libraries()otel.py。协议推断逻辑OTLPTransportProtocolotel.pyprotocol未指定时按端点推断——路径为/v1/traces的端点视为 HTTP无路径且端口等于 gRPC 默认端口4317的视为 gRPC其余情况构造为 gRPC 端点hostname:PHOENIX_GRPC_PORT。因此最省事的做法是HTTP 场景显式传endpointhttp://host:6006/v1/traces或protocolhttp/protobufgRPC 场景传endpointhttp://host:4317。自动插桩的发现机制otel.py通过 Python 的importlib.metadata.entry_points(groupopeninference_instrumentor)发现所有已安装的 OpenInference instrumentor逐个实例化并调用instrumentor.instrument(tracer_provider...)。若一个 instrumentor 都没找到会发出 “No OpenInference instrumentors found” 警告并跳过。这就是为什么auto_instrumentTrue的前提是先安装对应的插桩包。自动插桩零代码改动接入主流 LLM 生态安装 instrumentorpip install openinference-instrumentation-openai # OpenAI SDK pip install openinference-instrumentation-langchain # LangChain pip install openinference-instrumentation-llama-index # LlamaIndex # ... 按需安装其他之后启用register(project_namemy-app, auto_instrumentTrue)Phoenix 会自行发现并插桩所有已安装的 OpenInference 包。受支持的 Python 生态包括 LLM SDKOpenAI、Anthropic、Bedrock、Mistral、Vertex AI、Groq、Ollama与框架LangChain、LlamaIndex、DSPy、CrewAI、Instructor、Haystack——完整清单见 instrumentation-auto-python.md。选择性插桩需要显式控制时from phoenix.otel import register from openinference.instrumentation.openai import OpenAIInstrumentor tracer_provider register(project_namemy-app) # 不开 auto_instrument OpenAIInstrumentor().instrument(tracer_providertracer_provider)OTel GenAI 原生插桩Phoenix 在接收 OTLP spans 时会把 OTel GenAI 语义约定gen_ai.*属性自动转换为 OpenInference 格式。这意味着任何发出gen_ai.*属性的 OTel 原生 AI 插桩库如opentelemetry-instrumentation-anthropic、opentelemetry-instrumentation-openai都无需额外安装 OpenInference instrumentor直接可用。消息内容按结构转换而非拼接text、image、blob、reasoning 等消息部分各自成为llm.{input,output}_messages.{i}.message.contents.{j}下的条目模型推理过程reasoning part会保留为独立部分而不会混入回答文本。若 span 同时带有 OpenInference 属性例如双发 instrumentorOpenInference 值优先。局限性自动插桩不捕获自定义业务逻辑与内部函数调用。对于preprocess(query)、postprocess(response)这类自有代码需配合手动插桩如tracer.chain装饰器补齐链路详见 instrumentation-auto-python.md。用 Project 组织追踪数据项目Project是 Phoenix 中追踪数据的顶级分组建议按应用、环境或实验划分。两种设置方式export PHOENIX_PROJECTmy-app-prod # PHOENIX_PROJECT_NAME 是受支持别名from phoenix.otel import register register(project_namemy-app-prod)典型用例包括环境隔离my-app-dev/my-app-staging/my-app-prod、模型 A/B 对比chatbot-gpt4vschatbot-claude与版本追踪my-app-v1/my-app-v2详见 projects-python.md。对于使用 OTel Collector 等配置驱动管道的场景还可以通过 OTLP HTTP 的x-project-name请求头指定项目该头优先级高于openinference.project.name资源属性但仅 HTTP 端点支持gRPC 请使用资源属性。生产实践批处理与数据掩码批处理生产必需BatchSpanProcessor把多个 span 攒批发送显著降低网络开销生产环境必须启用。除register(batchTrue)外可通过 OTel 标准环境变量精细调参export OTEL_BSP_SCHEDULE_DELAY5000 # 每 5 秒批量导出一次毫秒 export OTEL_BSP_MAX_QUEUE_SIZE2048 # 队列最多缓存 2048 个 span export OTEL_BSP_MAX_EXPORT_BATCH_SIZE512 # 每批最多发送 512 个 span这些变量对应BatchSpanProcessor的schedule_delay_millis、max_queue_size、max_export_batch_size构造参数见 otel.py 的类文档也支持在代码中直接传入。批处理意味着 UI 中看到 traces 存在最长一个导出周期的延迟——这是验证环节需要留意的。数据掩码PII 保护若应用中存在敏感输入输出可用 OpenInference 的TraceConfig在导出前隐藏数据详见 production-python.mdfrom phoenix.otel import register from openinference.instrumentation import TraceConfig config TraceConfig( hide_inputsTrue, hide_outputsTrue, hide_input_messagesTrue, hide_llm_toolsTrue, ) register(trace_configconfig)优先级为代码 环境变量 默认值。验证与故障排查验证步骤打开 Phoenix UIhttp://localhost:6006导航到你的项目project运行你的应用检查是否出现 traces会在批量导出延迟内出现。完整可运行示例from phoenix.otel import register from openai import OpenAI # 启用追踪并自动插桩 register(project_namemy-chatbot, auto_instrumentTrue) # OpenAI 客户端自动被插桩 client OpenAI() response client.chat.completions.create( modelgpt-4, messages[{role: user, content: Hello!}] )常见问题没有 traces确认PHOENIX_COLLECTOR_ENDPOINT与 Phoenix 服务端实际监听地址一致本地默认 HTTP 6006 / gRPC 4317使用 Phoenix Cloud 时确认设置了PHOENIX_API_KEY确认对应的 instrumentor 包已安装auto_instrumentTrue只发现已安装的包确认batchTrue时等待时间大于OTEL_BSP_SCHEDULE_DELAY。缺少属性检查 span kind 是否符合预期参见 references 目录 下的 span-*.md 文档核对属性名是否遵循 OpenInference 语义约定fundamentals-required-attributes.md。其他参考为 span 附加 session、user、metadata、tags 等自定义属性参见 metadata-python.mdPython OTEL API 与 Python Client API 的完整参考可在仓库 packages/phoenix-otel 与 packages/phoenix-client 的文档目录中继续查阅相关测试用例可分别参见 test_otel.pyregister行为与 test_settings.py环境变量与.env.phoenix发现。【免费下载链接】phoenixAI Observability Evaluation项目地址: https://gitcode.com/gh_mirrors/phoenix13/phoenix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考