PXFuse Quick Start-PolarDB(PolarDB)-阿里云帮助中心

A quick-start guide from enabling the service to viewing your first data point. This guide helps you integrate with PXFuse and understand the core data model.

Prerequisites

Requirement	Description
Alibaba Cloud account	Used to log on to the Alibaba Cloud PolarDB-X console.
PolarDB-X instance	A PolarDB-X Enterprise Edition instance has been purchased.

Procedure

Follow these 6 steps to enable and connect to PXFuse.

Step 1: Enable the Service

Log on to the Alibaba Cloud PolarDB-X console and click the name of the target PolarDB-X instance in the instance list.
In the left-side navigation pane, choose AI Capability > Agent Observability Service.
Click Create Agent Observability Service.
Wait for the creation to complete (status changes to In Use), click to enter the Whitelist page, and configure the IP address of your current environment.

Step 2: Register or Log In

Access the URL provided in Basic Information in your browser (default port 3000).

Existing account: Enter your email and password to log in.
First-time user: Click Sign up and fill in your name, email, and password to register.
Password requirements: At least 8 characters, combining letters, numbers, and special characters (such as Pxfuse@Test2026!). Otherwise, a strength warning is displayed.

Step 3: Create an Organization and Project

After registration, you are automatically directed to the Setup wizard:

Create Organization: Enter an organization name and click Create.
Create Project: Enter a project name and click Create.

Note

PXFuse uses a hierarchical structure to manage data: Organization > Project > Trace / Observation / Session / Score. All data is isolated by project.

Step 4: Create an API Key

After project creation, you are guided to a setup page. Click Create new API key. The system generates the following keys at once:

Public Key (pk-lf-...): A public identifier that can be written into client configurations.
Secret Key (sk-lf-...): A private credential shown in full only once at creation. Save it immediately.

Note

The page also provides a .env snippet (containing LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, and LANGFUSE_BASE_URL) that you can copy directly into your project configuration.

Step 5: Connect Your Agent

Go to Settings > Integrations and select the integration method that matches your tool.

Tool	Integration Method
Qoder CLI / IDE	Choose Settings > Integrations > Qoder, copy the curl command, and execute it.
Claude Code	Choose Settings > Integrations > Claude Code, copy the command, and execute it.
Custom applications	Use the official Langfuse SDK and point `host` to the PXFuse address.
Existing OpenTelemetry	Report data through the OTLP protocol.
Other languages	Connect through the HTTP Ingestion API.

Step 6: View Data

Within seconds after data is reported, you can view it on the Overview, Agent Trace, and Session Timeline pages.

If no data appears on the page, check the following items:

Verify that the Public Key and Secret Key belong to the current project.
Verify that the reporting endpoint is reachable.
Verify that the time range in the upper-right corner covers the time when data was reported.

Data Model

The core data model of PXFuse includes the following concepts:

Concept	Meaning	Example
Trace	A complete task or conversation. The basic unit of analysis.	A conversation round to add unit tests to the user center.
Observation	A step within a trace, forming a tree-structured call chain.	An LLM inference, a file read, or a Bash command execution.
Session	A session group containing multiple traces.	A continuous coding session with multiple Q&A rounds.
Score	A score assigned to a trace or observation.	Human-annotated quality scores and automated evaluation scores.
User	The user identifier included in data reports.	Employee ID, email, or user ID.

Key Observation Properties

The effectiveness of insight features depends on the quality of these fields:

type: The observation type. Valid values include GENERATION, SPAN, TOOL, AGENT, and CHAIN.
level: The log level. Valid values include DEBUG, DEFAULT, WARNING, and ERROR.
statusMessage: The error message. This is the primary basis for failure clustering.
startTime / endTime: The basis for latency analysis.
input / output: The basis for content auditing and low-output detection.

Integration Recommendations

When integrating, fill in the type, level, statusMessage, sessionId, and userId fields as completely as possible. The effectiveness of Agent Insights features directly depends on the data quality of these fields.