从开启服务到查看第一条数据的快速上手指南，帮助您快速接入Agent观测服务（PXFuse）并理解核心数据模型。
准备工作
条件 | 说明 |
阿里云账号 | 用于登录阿里云 PolarDB-X 控制台。 |
PolarDB-X 实例 | 已购买PolarDB-X企业版实例。 |
快速开始
按照以下六个步骤，即可完成PXFuse的开通与接入。
第一步：开启服务
登录 阿里云 PolarDB-X 控制台，在实例列表中点击目标 PolarDB-X 实例名称。
在左侧导航栏选择 AI能力 > Agent观测服务。
单击创建Agent观测服务。
等待创建完成（状态变为使用中），单击进入白名单页面并配置您当前所属环境IP地址。
第二步：注册或登录
在浏览器中访问基本信息中提供的地址（默认端口3000）。
已有账号：输入邮箱和密码登录。
首次使用：单击Sign up，填写姓名、邮箱和密码进行注册。
密码要求：至少8位，且需组合字母、数字与特殊字符（如
Pxfuse@Test2026!），否则会提示强度不足。
第三步：创建组织与项目
首次注册后自动进入Setup向导：
Create Organization（创建组织）：填写组织名称，单击Create。
Create Project（创建项目）：填写项目名称，单击Create。
PXFuse采用层级结构管理数据：组织（Organization）> 项目（Project）> Trace / Observation / Session / Score。所有数据按项目隔离。
第四步：创建API Key
项目创建后进入引导页，单击Create new API key，系统将一次性生成以下密钥：
Public Key（
pk-lf-...）：公开标识，可写入客户端配置。Secret Key（
sk-lf-...）：私密凭证，仅创建时完整显示一次，请立即保存。
页面同时给出.env片段（含LANGFUSE_SECRET_KEY、LANGFUSE_PUBLIC_KEY、LANGFUSE_BASE_URL），可直接复制到项目配置中使用。
第五步：接入您的Agent
进入设置 > 集成，根据您使用的工具选择对应的接入方式。
使用的工具 | 接入方式 |
Qoder CLI / IDE | 选择设置 > 集成 > Qoder，复制命令并执行。 |
Claude Code | 选择设置 > 集成 > Claude Code，复制命令并执行。 |
自研应用 | 使用Langfuse官方SDK，将 |
已有OpenTelemetry | 通过OTLP协议上报数据。 |
其他语言 | 通过HTTP Ingestion API接入。 |
第6步：查看数据
数据上报后几秒内即可在总览、Agent Trace、会话时间线页面查看数据。
如果页面无数据显示，请依次检查以下项：
Public Key和Secret Key是否属于当前项目。
上报地址是否可达。
右上角时间范围是否覆盖了数据上报的时间。
数据模型
PXFuse的核心数据模型包含以下概念：
概念 | 含义 | 举例 |
Trace | 一次完整任务或对话，是分析的基本单位。 | 给“用户中心补充单元测试”这一轮对话。 |
Observation | Trace内部的一个步骤，构成树状调用链。 | 一次LLM推理、一次读文件、一次Bash命令执行。 |
Session | 多个Trace的会话分组。 | 一次包含多轮问答的连续编码会话。 |
Score | 对Trace或Observation的打分。 | 人工标注的质量分、自动评估分。 |
User | 上报时携带的使用者标识。 | 工号、邮箱、用户ID。 |
Observation关键属性
洞察类功能的效果取决于这些字段的质量：
type：观测类型，取值包括GENERATION、SPAN、TOOL、AGENT、CHAIN等。level：日志级别，取值包括DEBUG、DEFAULT、WARNING、ERROR。statusMessage：错误信息，是失败聚类的主要依据。startTime/endTime：耗时分析依据。input/output：内容审计与低产出检测依据。
接入建议
接入时请尽量完整填写type、level、statusMessage、sessionId、userId等字段。Agent洞察类功能的效果直接取决于这些字段的数据质量。