Back to Details

arize-trace

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Arize Trace Skill

Arize Trace Skill

Concepts

概念说明

  • Trace = a tree of spans sharing a 
    context.trace_id
    , rooted at a span with 
    parent_id = null
  • Span = a single operation (LLM call, tool call, retriever, chain, agent)
  • Session = a group of traces sharing 
    attributes.session.id
    (e.g., a multi-turn conversation)
Use 
ax spans export
to download trace data. This is the only supported command for retrieving spans.
Exploratory export rule: When exporting spans or traces without a specific 
--trace-id
, 
--span-id
, or 
--session-id
(i.e., browsing/exploring a project), always start with 
-l 50
to pull a small sample first. Summarize what you find, then pull more data only if the user asks or the task requires it. This avoids slow queries and overwhelming output on large projects.
Default output directory: Always use 
--output-dir .arize-tmp-traces
on every 
ax spans export
call. The CLI automatically creates the directory and adds it to 
.gitignore
.
  • Trace = 共享同一个
    context.trace_id
    的span树，根节点是
    parent_id = null
    的span
  • Span = 单个操作（LLM调用、工具调用、检索器、链、Agent）
  • Session = 共享
    attributes.session.id
    的一组traces（例如，多轮对话）
使用
ax spans export
下载追踪数据。这是检索spans的唯一支持命令。
探索性导出规则： 当导出spans或traces但未指定
--trace-id
、
--span-id
或
--session-id
时（即浏览/探索项目），请始终以
-l 50
开头，先拉取小样本数据。总结发现的内容后，仅在用户要求或任务需要时再拉取更多数据。这可以避免在大型项目中出现查询缓慢和输出内容过多的问题。
默认输出目录： 每次调用
ax spans export
时，请始终使用
--output-dir .arize-tmp-traces
。CLI会自动创建该目录并将其添加到
.gitignore
中。

Prerequisites

前置条件

Three things are needed: 
ax
CLI, an API key (env var or profile), and a space ID. A project name is also needed but usually comes from the user's message.
需要三个要素：
ax
CLI、API密钥（环境变量或配置文件）和空间ID。还需要项目名称，通常可从用户的消息中获取。

Install ax

安装ax

Verify 
ax
is installed and working before proceeding:
  1. Check if 
    ax
    is on PATH: 
    command -v ax
    (Unix) or 
    where ax
    (Windows)
  2. If not found, check common install locations:
    • macOS/Linux: 
      test -x ~/.local/bin/ax && export PATH="$HOME/.local/bin:$PATH"
    • Windows: check 
      %APPDATA%\Python\Scripts\ax.exe
      or 
      %LOCALAPPDATA%\Programs\Python\Scripts\ax.exe
  3. If still not found, install it (requires shell access to install packages):
    • Preferred: 
      uv tool install arize-ax-cli
    • Alternative: 
      pipx install arize-ax-cli
    • Fallback: 
      pip install arize-ax-cli
  4. After install, if 
    ax
    is not on PATH:
    • macOS/Linux: 
      export PATH="$HOME/.local/bin:$PATH"
    • Windows (PowerShell): 
      $env:PATH = "$env:APPDATA\Python\Scripts;$env:PATH"
  5. If 
    ax --version
    fails with an SSL/certificate error:
    • macOS: 
      export SSL_CERT_FILE=/etc/ssl/cert.pem
    • Linux: 
      export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
    • Windows (PowerShell): 
      $env:SSL_CERT_FILE = "C:\Program Files\Common Files\SSL\cert.pem"
      (or use 
      python -c "import certifi; print(certifi.where())"
      to find the cert bundle)
  6. ax --version
    must succeed before proceeding. If it doesn't, stop and ask the user for help.
在继续之前，请验证
ax
是否已安装并能正常工作：
  1. 检查
    ax
    是否在PATH中：
    command -v ax
    （Unix系统）或
    where ax
    （Windows系统）
  2. 如果未找到，请检查常见安装位置：
    • macOS/Linux：
      test -x ~/.local/bin/ax && export PATH="$HOME/.local/bin:$PATH"
    • Windows：检查
      %APPDATA%\Python\Scripts\ax.exe
      或
      %LOCALAPPDATA%\Programs\Python\Scripts\ax.exe
  3. 如果仍未找到，请安装它（需要Shell权限来安装包）：
    • 推荐方式：
      uv tool install arize-ax-cli
    • 替代方式：
      pipx install arize-ax-cli
    • 备用方式：
      pip install arize-ax-cli
  4. 安装后，如果
    ax
    不在PATH中：
    • macOS/Linux：
      export PATH="$HOME/.local/bin:$PATH"
    • Windows（PowerShell）：
      $env:PATH = "$env:APPDATA\Python\Scripts;$env:PATH"
  5. 如果
    ax --version
    因SSL/证书错误失败：
    • macOS：
      export SSL_CERT_FILE=/etc/ssl/cert.pem
    • Linux：
      export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
    • Windows（PowerShell）：
      $env:SSL_CERT_FILE = "C:\Program Files\Common Files\SSL\cert.pem"
      （或使用
      python -c "import certifi; print(certifi.where())"
      查找证书包位置）
  6. 在继续之前，
    ax --version
    必须执行成功。如果失败，请停止操作并向用户寻求帮助。

Verify environment

验证环境

Run a quick check for credentials:
macOS/Linux (bash):
bash
ax --version && echo "--- env ---" && echo "ARIZE_API_KEY: ${ARIZE_API_KEY:-(not set)}" && echo "ARIZE_SPACE_ID: ${ARIZE_SPACE_ID:-(not set)}" && echo "--- profiles ---" && ax profiles show 2>&1
Windows (PowerShell):
powershell
ax --version; Write-Host "--- env ---"; Write-Host "ARIZE_API_KEY: $env:ARIZE_API_KEY"; Write-Host "ARIZE_SPACE_ID: $env:ARIZE_SPACE_ID"; Write-Host "--- profiles ---"; ax profiles show 2>&1
Read the output and proceed immediately if either the env var or the profile has an API key. Only ask the user if both are missing. Resolve failures:
  • No API key in env and no profile → AskQuestion: "Arize API key (https://app.arize.com/admin > API Keys)"
  • Space ID unknown → AskQuestion, or run 
    ax projects list -o json --limit 100 --space-id $ARIZE_SPACE_ID
    and present as selectable options
  • Project unclear → ask, or run 
    ax projects list -o json --limit 100
    and search for a match
IMPORTANT: 
--space-id
is required when using a human-readable project name as the 
PROJECT
positional argument. It is not needed when using a base64-encoded project ID.
快速检查凭据：
macOS/Linux（bash）：
bash
ax --version && echo "--- env ---" && echo "ARIZE_API_KEY: ${ARIZE_API_KEY:-(not set)}" && echo "ARIZE_SPACE_ID: ${ARIZE_SPACE_ID:-(not set)}" && echo "--- profiles ---" && ax profiles show 2>&1
Windows（PowerShell）：
powershell
ax --version; Write-Host "--- env ---"; Write-Host "ARIZE_API_KEY: $env:ARIZE_API_KEY"; Write-Host "ARIZE_SPACE_ID: $env:ARIZE_SPACE_ID"; Write-Host "--- profiles ---"; ax profiles show 2>&1
立即读取输出并继续：如果环境变量或配置文件中存在API密钥，即可继续。仅当两者都缺失时，才向用户询问。解决失败情况：
  • 环境变量中无API密钥且无配置文件 → 询问用户："请提供Arize API密钥（获取地址：https://app.arize.com/admin > API Keys）"
  • 未知空间ID → 询问用户，或运行
    ax projects list -o json --limit 100 --space-id $ARIZE_SPACE_ID
    并提供可选列表
  • 项目不明确 → 询问用户，或运行
    ax projects list -o json --limit 100
    并搜索匹配项
重要提示： 当使用人类可读的项目名称作为
PROJECT
位置参数时，
--space-id
是必需的。使用base64编码的项目ID时，则不需要。

Export Spans: 
ax spans export

导出Spans：
ax spans export

The primary command for downloading trace data to a file.
将追踪数据下载到文件的主要命令。

By trace ID

通过Trace ID导出

bash
undefined
bash
undefined

Using project name (requires --space-id)

使用项目名称（需要--space-id）

ax spans export PROJECT_NAME --trace-id TRACE_ID --space-id SPACE_ID --output-dir .arize-tmp-traces
ax spans export PROJECT_NAME --trace-id TRACE_ID --space-id SPACE_ID --output-dir .arize-tmp-traces

Using base64 project ID (no --space-id needed)

使用base64项目ID（无需--space-id）

ax spans export PROJECT_ID --trace-id TRACE_ID --output-dir .arize-tmp-traces
undefined
ax spans export PROJECT_ID --trace-id TRACE_ID --output-dir .arize-tmp-traces
undefined

By span ID

通过Span ID导出

bash
ax spans export PROJECT_NAME --span-id SPAN_ID --space-id SPACE_ID --output-dir .arize-tmp-traces
bash
ax spans export PROJECT_NAME --span-id SPAN_ID --space-id SPACE_ID --output-dir .arize-tmp-traces

By session ID

通过Session ID导出

bash
ax spans export PROJECT_NAME --session-id SESSION_ID --space-id SPACE_ID --output-dir .arize-tmp-traces
bash
ax spans export PROJECT_NAME --session-id SESSION_ID --space-id SPACE_ID --output-dir .arize-tmp-traces

Flags

标志参数

FlagTypeRequiredDescription
--trace-id
stringmutexFilter: 
context.trace_id = 'X'
--span-id
stringmutexFilter: 
context.span_id = 'X'
--session-id
stringmutexFilter: 
attributes.session.id = 'X'
PROJECT
string (positional)yes (or 
$ARIZE_DEFAULT_PROJECT
)		Project name or base64 ID (positional arg, not a flag)
--space-id
stringyes (when 
PROJECT
is a name)		Space ID; required to resolve project names
--days
intnoLookback window (default: 30)
--start-time
stringnoOverride start (ISO 8601)
--end-time
stringnoOverride end (ISO 8601)
--output-dir
stringnoOutput directory (default: 
.arize-tmp-traces
; ensure it is gitignored — see above)
--stdout
boolnoPrint JSON to stdout instead of file
--all
boolnoUse Arrow Flight for bulk export (see below)
Exactly one of 
--trace-id
, 
--span-id
, 
--session-id
is required.
Output is a JSON array of span objects. File naming: 
{type}_{id}_{timestamp}/spans.json
.
标志类型是否必需描述
--trace-id
字符串互斥过滤条件：
context.trace_id = 'X'
--span-id
字符串互斥过滤条件：
context.span_id = 'X'
--session-id
字符串互斥过滤条件：
attributes.session.id = 'X'
PROJECT
字符串（位置参数）是（或使用
$ARIZE_DEFAULT_PROJECT
）		项目名称或base64 ID（位置参数，非标志）
--space-id
字符串是（当
PROJECT
为名称时）		空间ID；解析项目名称时必需
--days
整数否回溯窗口（默认：30）
--start-time
字符串否覆盖开始时间（ISO 8601格式）
--end-time
字符串否覆盖结束时间（ISO 8601格式）
--output-dir
字符串否输出目录（默认：
.arize-tmp-traces
；确保已添加到git忽略列表 — 见上文）
--stdout
布尔值否将JSON打印到标准输出而非文件
--all
布尔值否使用Arrow Flight进行批量导出（见下文）
必须指定
--trace-id
、
--span-id
、
--session-id
中的其中一个。
输出是span对象的JSON数组。文件命名规则：
{type}_{id}_{timestamp}/spans.json
。

Bulk export with 
--all
(Arrow Flight)

使用
--all
进行批量导出（Arrow Flight）

By default, 
ax spans export
uses the REST API which is limited to 500 spans per page and capped by 
--limit
. Pass 
--all
to switch to Arrow Flight for streaming bulk export with no span limit.
bash
ax spans export PROJECT_NAME --space-id SPACE_ID --filter "status_code = 'ERROR'" --all --output-dir .arize-tmp-traces
REST vs Flight trade-offs:
  • REST (default): Lower friction -- no Arrow/Flight dependency needed, uses standard HTTPS ports, works through any corporate proxy or firewall. Limited to 500 spans per page.
  • Flight (
    --all
    ): Required for bulk export beyond 500 spans. Uses gRPC+TLS on a separate host/port which some corporate networks may block.
When to use 
--all
:
  • Exporting more than 500 spans
  • Downloading full traces with many child spans
  • Large time-range exports
Agent auto-escalation rule: If a REST export returns exactly the number of spans requested by 
-l
(or 500 if no limit was set), the result is likely truncated. Increase 
-l
or re-run with 
--all
to get the full dataset — but only when the user asks or the task requires more data.
Requirements for 
--all
:
  • --space-id
    is required (Flight uses 
    space_id
    + 
    project_name
    , not 
    project_id
    )
  • --limit
    is ignored when 
    --all
    is set
Networking notes for 
--all
: Arrow Flight connects to 
flight.arize.com:443
via gRPC+TLS -- this is a different host from the REST API (
api.arize.com
). On internal or private networks, the Flight endpoint may use a different host/port. Configure via:
  • ax profile: 
    flight_host
    , 
    flight_port
    , 
    flight_scheme
  • Environment variables: 
    ARIZE_FLIGHT_HOST
    , 
    ARIZE_FLIGHT_PORT
    , 
    ARIZE_FLIGHT_SCHEME
The 
--all
flag is also available on 
ax traces export
, 
ax datasets export
, and 
ax experiments export
with the same behavior (REST by default, Flight with 
--all
).
默认情况下，
ax spans export
使用REST API，每页最多返回500个spans，并受
--limit
限制。传递
--all
可切换到Arrow Flight进行流式批量导出，无span数量限制。
bash
ax spans export PROJECT_NAME --space-id SPACE_ID --filter "status_code = 'ERROR'" --all --output-dir .arize-tmp-traces
REST与Flight的权衡：
  • REST（默认）：门槛更低 — 无需Arrow/Flight依赖，使用标准HTTPS端口，可通过任何企业代理或防火墙。每页最多500个spans。
  • Flight（
    --all
    ）：导出超过500个spans时必需。使用gRPC+TLS连接到单独的主机/端口，部分企业网络可能会阻止此连接。
何时使用
--all
：
  • 导出超过500个spans
  • 下载包含多个子spans的完整traces
  • 大时间范围导出
Agent自动升级规则： 如果REST导出返回的span数量恰好等于
-l
指定的数量（或未设置限制时为500），结果可能被截断。增加
-l
的值或使用
--all
重新运行以获取完整数据集 — 但仅在用户要求或任务需要更多数据时执行此操作。
--all
的要求：
  • 必需
    --space-id
    （Flight使用
    space_id
    + 
    project_name
    ，而非
    project_id
    ）
  • 设置
    --all
    后，
    --limit
    将被忽略
--all
的网络说明： Arrow Flight通过gRPC+TLS连接到
flight.arize.com:443
— 这与REST API的主机（
api.arize.com
）不同。在内部或专用网络中，Flight端点可能使用不同的主机/端口。可通过以下方式配置：
  • ax配置文件：
    flight_host
    、
    flight_port
    、
    flight_scheme
  • 环境变量：
    ARIZE_FLIGHT_HOST
    、
    ARIZE_FLIGHT_PORT
    、
    ARIZE_FLIGHT_SCHEME
--all
标志也可用于
ax traces export
、
ax datasets export
和
ax experiments export
，行为相同（默认使用REST，设置
--all
后使用Flight）。

Export Traces: 
ax traces export

导出Traces：
ax traces export

Export full traces -- all spans belonging to traces that match a filter. Uses a two-phase approach:
  1. Phase 1: Find spans matching 
    --filter
    (up to 
    --limit
    via REST, or all via Flight with 
    --all
    )
  2. Phase 2: Extract unique trace IDs, then fetch every span for those traces
bash
undefined
导出完整traces — 属于匹配过滤条件的traces的所有spans。采用两阶段方法：
  1. 阶段1： 查找匹配
    --filter
    的spans（通过REST最多返回
    --limit
    个，通过Flight返回所有）
  2. 阶段2： 提取唯一的trace ID，然后获取这些traces的所有spans
bash
undefined

Explore recent traces (start small with -l 50, pull more if needed)

导出最近的traces（从-l 50开始，按需拉取更多）

ax traces export PROJECT_NAME --space-id SPACE_ID -l 50 --output-dir .arize-tmp-traces
ax traces export PROJECT_NAME --space-id SPACE_ID -l 50 --output-dir .arize-tmp-traces

Export traces with error spans (REST, up to 500 spans in phase 1)

导出包含错误spans的traces（REST，阶段1最多500个spans）

ax traces export PROJECT_NAME --space-id SPACE_ID --filter "status_code = 'ERROR'" --stdout
ax traces export PROJECT_NAME --space-id SPACE_ID --filter "status_code = 'ERROR'" --stdout

Export all traces matching a filter via Flight (no limit)

通过Flight导出所有匹配过滤条件的traces（无限制）

ax traces export PROJECT_NAME --space-id SPACE_ID --filter "status_code = 'ERROR'" --all
undefined
ax traces export PROJECT_NAME --space-id SPACE_ID --filter "status_code = 'ERROR'" --all
undefined

Flags

标志参数

FlagTypeDefaultDescription
PROJECT
stringrequiredPositional argument (name or base64 ID)
--filter
stringnoneFilter expression for phase-1 span lookup
--space-id
stringnoneSpace ID; required when PROJECT is a name or when using 
--all
--limit, -l
int50Max number of traces to export
--days
int30Lookback window in days
--start-time
stringnoneOverride start (ISO 8601)
--end-time
stringnoneOverride end (ISO 8601)
--output-dir
string
.
Output directory
--stdout
boolfalsePrint JSON to stdout instead of file
--all
boolfalseUse Arrow Flight for both phases (see spans 
--all
docs above)
-p, --profile
stringdefaultConfiguration profile
标志类型默认值描述
PROJECT
字符串必填位置参数（名称或base64 ID）
--filter
字符串无阶段1查找spans的过滤表达式
--space-id
字符串无空间ID；当PROJECT为名称或使用
--all
时必需
--limit, -l
整数50最多导出的trace数量
--days
整数30回溯窗口（天数）
--start-time
字符串无覆盖开始时间（ISO 8601格式）
--end-time
字符串无覆盖结束时间（ISO 8601格式）
--output-dir
字符串
.
输出目录
--stdout
布尔值false将JSON打印到标准输出而非文件
--all
布尔值false两个阶段均使用Arrow Flight（见上文spans的
--all
文档）
-p, --profile
字符串default配置文件

How it differs from 
ax spans export

与
ax spans export
的区别

  • ax spans export
    exports individual spans matching a filter
  • ax traces export
    exports complete traces -- it finds spans matching the filter, then pulls ALL spans for those traces (including siblings and children that may not match the filter)
  • ax spans export
    导出匹配过滤条件的单个spans
  • ax traces export
    导出完整traces — 先找到匹配过滤条件的spans，然后拉取这些traces的所有spans（包括可能不匹配过滤条件的兄弟和子spans）

Filter Syntax Reference

过滤语法参考

SQL-like expressions passed to 
--filter
.
传递给
--filter
的类SQL表达式。

Common filterable columns

常见可过滤列

ColumnTypeDescriptionExample Values
name
stringSpan name
'ChatCompletion'
, 
'retrieve_docs'
status_code
stringStatus
'OK'
, 
'ERROR'
, 
'UNSET'
latency_ms
numberDuration in ms
100
, 
5000
parent_id
stringParent span IDnull for root spans
context.trace_id
stringTrace ID
context.span_id
stringSpan ID
attributes.session.id
stringSession ID
attributes.openinference.span.kind
stringSpan kind
'LLM'
, 
'CHAIN'
, 
'TOOL'
, 
'AGENT'
, 
'RETRIEVER'
, 
'RERANKER'
, 
'EMBEDDING'
, 
'GUARDRAIL'
, 
'EVALUATOR'
attributes.llm.model_name
stringLLM model
'gpt-4o'
, 
'claude-3'
attributes.input.value
stringSpan input
attributes.output.value
stringSpan output
attributes.error.type
stringError type
'ValueError'
, 
'TimeoutError'
attributes.error.message
stringError message
event.attributes
stringError tracebacksUse CONTAINS (not exact match)
列类型描述示例值
name
字符串Span名称
'ChatCompletion'
, 
'retrieve_docs'
status_code
字符串状态
'OK'
, 
'ERROR'
, 
'UNSET'
latency_ms
数字耗时（毫秒）
100
, 
5000
parent_id
字符串父span ID根spans为null
context.trace_id
字符串Trace ID
context.span_id
字符串Span ID
attributes.session.id
字符串Session ID
attributes.openinference.span.kind
字符串Span类型
'LLM'
, 
'CHAIN'
, 
'TOOL'
, 
'AGENT'
, 
'RETRIEVER'
, 
'RERANKER'
, 
'EMBEDDING'
, 
'GUARDRAIL'
, 
'EVALUATOR'
attributes.llm.model_name
字符串LLM模型
'gpt-4o'
, 
'claude-3'
attributes.input.value
字符串Span输入
attributes.output.value
字符串Span输出
attributes.error.type
字符串错误类型
'ValueError'
, 
'TimeoutError'
attributes.error.message
字符串错误消息
event.attributes
字符串错误回溯使用CONTAINS（不使用精确匹配）

Operators

操作符

=
, 
!=
, 
<
, 
<=
, 
>
, 
>=
, 
AND
, 
OR
, 
IN
, 
CONTAINS
, 
LIKE
, 
IS NULL
, 
IS NOT NULL
=
, 
!=
, 
<
, 
<=
, 
>
, 
>=
, 
AND
, 
OR
, 
IN
, 
CONTAINS
, 
LIKE
, 
IS NULL
, 
IS NOT NULL

Examples

示例

status_code = 'ERROR'
latency_ms > 5000
name = 'ChatCompletion' AND status_code = 'ERROR'
attributes.llm.model_name = 'gpt-4o'
attributes.openinference.span.kind IN ('LLM', 'AGENT')
attributes.error.type LIKE '%Transport%'
event.attributes CONTAINS 'TimeoutError'
status_code = 'ERROR'
latency_ms > 5000
name = 'ChatCompletion' AND status_code = 'ERROR'
attributes.llm.model_name = 'gpt-4o'
attributes.openinference.span.kind IN ('LLM', 'AGENT')
attributes.error.type LIKE '%Transport%'
event.attributes CONTAINS 'TimeoutError'

Tips

提示

  • Prefer 
    IN
    over multiple 
    OR
    conditions: 
    name IN ('a', 'b', 'c')
    not 
    name = 'a' OR name = 'b' OR name = 'c'
  • Start broad with 
    LIKE
    , then switch to 
    =
    or 
    IN
    once you know exact values
  • Use 
    CONTAINS
    for 
    event.attributes
    (error tracebacks) -- exact match is unreliable on complex text
  • Always wrap string values in single quotes
  • 优先使用
    IN
    而非多个
    OR
    条件：
    name IN ('a', 'b', 'c')
    而非 
    name = 'a' OR name = 'b' OR name = 'c'
  • 先用
    LIKE
    进行宽泛搜索，确定精确值后再切换为
    =
    或
    IN
  • 对
    event.attributes
    （错误回溯）使用
    CONTAINS
    — 复杂文本的精确匹配不可靠
  • 字符串值始终用单引号包裹

Workflows

工作流

Debug a failing trace

调试失败的Trace

  1. ax traces export PROJECT --space-id SPACE_ID --filter "status_code = 'ERROR'" -l 50 --output-dir .arize-tmp-traces
  2. Read the output file, look for spans with 
    status_code: ERROR
  3. Check 
    attributes.error.type
    and 
    attributes.error.message
    on error spans
  1. ax traces export PROJECT --space-id SPACE_ID --filter "status_code = 'ERROR'" -l 50 --output-dir .arize-tmp-traces
  2. 读取输出文件，查找
    status_code: ERROR
    的spans
  3. 检查错误spans的
    attributes.error.type
    和
    attributes.error.message

Download a conversation session

下载对话Session

  1. ax spans export PROJECT --session-id SESSION_ID --space-id SPACE_ID --output-dir .arize-tmp-traces
  2. Spans are ordered by 
    start_time
    , grouped by 
    context.trace_id
  3. If you only have a trace_id, export that trace first, then look for 
    attributes.session.id
    in the output to get the session ID
  1. ax spans export PROJECT --session-id SESSION_ID --space-id SPACE_ID --output-dir .arize-tmp-traces
  2. Spans按
    start_time
    排序，按
    context.trace_id
    分组
  3. 如果只有trace_id，先导出该trace，然后在输出中查找
    attributes.session.id
    以获取session ID

Export for offline analysis

导出用于离线分析

bash
ax spans export PROJECT --trace-id TRACE_ID --space-id SPACE_ID --output-dir .arize-tmp-traces --stdout | jq '.[]'
bash
ax spans export PROJECT --trace-id TRACE_ID --space-id SPACE_ID --output-dir .arize-tmp-traces --stdout | jq '.[]'

Span Column Reference (OpenInference Semantic Conventions)

Span列参考（OpenInference语义约定）

Core Identity and Timing

核心标识与计时

ColumnDescription
name
Span operation name (e.g., 
ChatCompletion
, 
retrieve_docs
)
context.trace_id
Trace ID -- all spans in a trace share this
context.span_id
Unique span ID
parent_id
Parent span ID. 
null
for root spans (= traces)
start_time
When the span started (ISO 8601)
end_time
When the span ended
latency_ms
Duration in milliseconds
status_code
OK
, 
ERROR
, 
UNSET
status_message
Optional message (usually set on errors)
attributes.openinference.span.kind
LLM
, 
CHAIN
, 
TOOL
, 
AGENT
, 
RETRIEVER
, 
RERANKER
, 
EMBEDDING
, 
GUARDRAIL
, 
EVALUATOR
列描述
name
Span操作名称（例如，
ChatCompletion
, 
retrieve_docs
）
context.trace_id
Trace ID — 同一个trace中的所有spans共享此ID
context.span_id
唯一的Span ID
parent_id
父Span ID。根spans（即traces）为
null
start_time
Span开始时间（ISO 8601格式）
end_time
Span结束时间
latency_ms
耗时（毫秒）
status_code
OK
, 
ERROR
, 
UNSET
status_message
可选消息（通常在错误时设置）
attributes.openinference.span.kind
LLM
, 
CHAIN
, 
TOOL
, 
AGENT
, 
RETRIEVER
, 
RERANKER
, 
EMBEDDING
, 
GUARDRAIL
, 
EVALUATOR

Where to Find Prompts and LLM I/O

提示词与LLM输入输出的位置

Generic input/output (all span kinds):
ColumnWhat it contains
attributes.input.value
The input to the operation. For LLM spans, often the full prompt or serialized messages JSON. For chain/agent spans, the user's question.
attributes.input.mime_type
Format hint: 
text/plain
or 
application/json
attributes.output.value
The output. For LLM spans, the model's response. For chain/agent spans, the final answer.
attributes.output.mime_type
Format hint for output
LLM-specific message arrays (structured chat format):
ColumnWhat it contains
attributes.llm.input_messages
Structured input messages array (system, user, assistant, tool). Where chat prompts live in role-based format.
attributes.llm.input_messages.roles
Array of roles: 
system
, 
user
, 
assistant
, 
tool
attributes.llm.input_messages.contents
Array of message content strings
attributes.llm.output_messages
Structured output messages from the model
attributes.llm.output_messages.contents
Model response content
attributes.llm.output_messages.tool_calls.function.names
Tool calls the model wants to make
attributes.llm.output_messages.tool_calls.function.arguments
Arguments for those tool calls
Prompt templates:
ColumnWhat it contains
attributes.llm.prompt_template.template
The prompt template with variable placeholders (e.g., 
"Answer {question} using {context}"
)
attributes.llm.prompt_template.variables
Template variable values (JSON object)
Finding prompts by span kind:
  • LLM span: Check 
    attributes.llm.input_messages
    for structured chat messages, OR 
    attributes.input.value
    for serialized prompt. Check 
    attributes.llm.prompt_template.template
    for the template.
  • Chain/Agent span: Check 
    attributes.input.value
    for the user's question. Actual LLM prompts are on child LLM spans.
  • Tool span: Check 
    attributes.input.value
    for tool input, 
    attributes.output.value
    for tool result.
通用输入/输出（所有Span类型）：
列包含内容
attributes.input.value
操作的输入。对于LLM spans，通常是完整提示词或序列化消息JSON。对于链/Agent spans，是用户的问题。
attributes.input.mime_type
格式提示：
text/plain
或
application/json
attributes.output.value
操作的输出。对于LLM spans，是模型的响应。对于链/Agent spans，是最终答案。
attributes.output.mime_type
输出格式提示
LLM特定消息数组（结构化聊天格式）：
列包含内容
attributes.llm.input_messages
结构化输入消息数组（系统、用户、助手、工具）。基于角色的格式中聊天提示词的存储位置。
attributes.llm.input_messages.roles
角色数组：
system
, 
user
, 
assistant
, 
tool
attributes.llm.input_messages.contents
消息内容字符串数组
attributes.llm.output_messages
模型输出的结构化消息
attributes.llm.output_messages.contents
模型响应内容
attributes.llm.output_messages.tool_calls.function.names
模型想要调用的工具名称
attributes.llm.output_messages.tool_calls.function.arguments
这些工具调用的参数
提示词模板：
列包含内容
attributes.llm.prompt_template.template
带有变量占位符的提示词模板（例如，
"使用{context}回答{question}"
）
attributes.llm.prompt_template.variables
模板变量值（JSON对象）
按Span类型查找提示词：
  • LLM span：检查
    attributes.llm.input_messages
    获取结构化聊天消息，或检查
    attributes.input.value
    获取序列化提示词。检查
    attributes.llm.prompt_template.template
    获取模板。
  • 链/Agent span：检查
    attributes.input.value
    获取用户的问题。实际LLM提示词在子LLM spans中。
  • 工具span：检查
    attributes.input.value
    获取工具输入，
    attributes.output.value
    获取工具结果。

LLM Model and Cost

LLM模型与成本

ColumnDescription
attributes.llm.model_name
Model identifier (e.g., 
gpt-4o
, 
claude-3-opus-20240229
)
attributes.llm.invocation_parameters
Model parameters JSON (temperature, max_tokens, top_p, etc.)
attributes.llm.token_count.prompt
Input token count
attributes.llm.token_count.completion
Output token count
attributes.llm.token_count.total
Total tokens
attributes.llm.cost.prompt
Input cost in USD
attributes.llm.cost.completion
Output cost in USD
attributes.llm.cost.total
Total cost in USD
列描述
attributes.llm.model_name
模型标识符（例如，
gpt-4o
, 
claude-3-opus-20240229
）
attributes.llm.invocation_parameters
模型参数JSON（temperature、max_tokens、top_p等）
attributes.llm.token_count.prompt
输入token数量
attributes.llm.token_count.completion
输出token数量
attributes.llm.token_count.total
总token数量
attributes.llm.cost.prompt
输入成本（美元）
attributes.llm.cost.completion
输出成本（美元）
attributes.llm.cost.total
总成本（美元）

Tool Spans

工具Spans

ColumnDescription
attributes.tool.name
Tool/function name
attributes.tool.description
Tool description
attributes.tool.parameters
Tool parameter schema (JSON)
列描述
attributes.tool.name
工具/函数名称
attributes.tool.description
工具描述
attributes.tool.parameters
工具参数 schema（JSON）

Retriever Spans

检索器Spans

ColumnDescription
attributes.retrieval.documents
Retrieved documents array
attributes.retrieval.documents.ids
Document IDs
attributes.retrieval.documents.scores
Relevance scores
attributes.retrieval.documents.contents
Document text content
attributes.retrieval.documents.metadatas
Document metadata
列描述
attributes.retrieval.documents
检索到的文档数组
attributes.retrieval.documents.ids
文档ID
attributes.retrieval.documents.scores
相关性分数
attributes.retrieval.documents.contents
文档文本内容
attributes.retrieval.documents.metadatas
文档元数据

Reranker Spans

重排序器Spans

ColumnDescription
attributes.reranker.query
The query being reranked
attributes.reranker.model_name
Reranker model
attributes.reranker.top_k
Number of results
attributes.reranker.input_documents.*
Input documents (ids, scores, contents, metadatas)
attributes.reranker.output_documents.*
Reranked output documents
列描述
attributes.reranker.query
正在重排序的查询
attributes.reranker.model_name
重排序器模型
attributes.reranker.top_k
结果数量
attributes.reranker.input_documents.*
输入文档（ID、分数、内容、元数据）
attributes.reranker.output_documents.*
重排序后的输出文档

Session, User, and Custom Metadata

Session、用户与自定义元数据

ColumnDescription
attributes.session.id
Session/conversation ID -- groups traces into multi-turn sessions
attributes.user.id
End-user identifier
attributes.metadata.*
Custom key-value metadata. Any key under this prefix is user-defined (e.g., 
attributes.metadata.user_email
). Filterable.
列描述
attributes.session.id
Session/对话ID — 将traces分组为多轮会话
attributes.user.id
终端用户标识符
attributes.metadata.*
自定义键值元数据。此前缀下的任何键均为用户定义（例如，
attributes.metadata.user_email
）。可过滤。

Errors and Exceptions

错误与异常

ColumnDescription
attributes.exception.type
Exception class name (e.g., 
ValueError
, 
TimeoutError
)
attributes.exception.message
Exception message text
event.attributes
Error tracebacks and detailed event data. Use 
CONTAINS
for filtering.
列描述
attributes.exception.type
异常类名称（例如，
ValueError
, 
TimeoutError
）
attributes.exception.message
异常消息文本
event.attributes
错误回溯和详细事件数据。过滤时使用
CONTAINS
。

Evaluations and Annotations

评估与标注

ColumnDescription
annotation.<name>.label
Human or auto-eval label (e.g., 
correct
, 
incorrect
)
annotation.<name>.score
Numeric score (e.g., 
0.95
)
annotation.<name>.text
Freeform annotation text
列描述
annotation.<name>.label
人工或自动评估标签（例如，
correct
, 
incorrect
）
annotation.<name>.score
数值分数（例如，
0.95
）
annotation.<name>.text
自由格式标注文本

Embeddings

嵌入

ColumnDescription
attributes.embedding.model_name
Embedding model name
attributes.embedding.texts
Text chunks that were embedded
列描述
attributes.embedding.model_name
嵌入模型名称
attributes.embedding.texts
被嵌入的文本块

Troubleshooting

故障排除

ProblemSolution
ax: command not found
Check 
~/.local/bin/ax
; if missing: 
uv tool install arize-ax-cli
(requires shell access to install packages). Then 
export PATH="$HOME/.local/bin:$PATH"
SSL: CERTIFICATE_VERIFY_FAILED
macOS: 
export SSL_CERT_FILE=/etc/ssl/cert.pem
. Linux: 
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
. Windows: 
$env:SSL_CERT_FILE = (python -c "import certifi; print(certifi.where())")
No such command
on a subcommand that should exist		The installed 
ax
is outdated. Reinstall from the local workspace: 
uv tool install --force --reinstall /path/to/arize/sdk/python/arize-ax-cli
(requires shell access to install packages)
No profile found
Follow "Resolve credentials" in Prerequisites to auto-discover or prompt for the API key
401 Unauthorized
with valid API key		You are likely using a project name (e.g., 
my-project
) without 
--space-id
. Add 
--space-id SPACE_ID
or use the base64 project ID instead
No spans found
Expand 
--days
(default 30), verify project ID
Filter error
Check column name spelling, wrap string values in single quotes
Timeout on large export
Use 
--days 7
to narrow the time range
问题解决方案
ax: command not found
检查
~/.local/bin/ax
；如果缺失：
uv tool install arize-ax-cli
（需要Shell权限安装包）。然后执行
export PATH="$HOME/.local/bin:$PATH"
SSL: CERTIFICATE_VERIFY_FAILED
macOS：
export SSL_CERT_FILE=/etc/ssl/cert.pem
。Linux：
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
。Windows：
$env:SSL_CERT_FILE = (python -c "import certifi; print(certifi.where())")
子命令存在但提示
No such command
安装的
ax
版本过时。从本地工作区重新安装：
uv tool install --force --reinstall /path/to/arize/sdk/python/arize-ax-cli
（需要Shell权限安装包）
No profile found
按照前置条件中的“解决凭据问题”步骤自动发现或提示用户提供API密钥
使用有效API密钥但提示
401 Unauthorized
您可能在使用项目名称（例如，
my-project
）时未指定
--space-id
。添加
--space-id SPACE_ID
或使用base64编码的项目ID
No spans found
扩大
--days
范围（默认30天），验证项目ID
Filter error
检查列名拼写，字符串值用单引号包裹
大型导出时超时使用
--days 7
缩小时间范围

Save Credentials

保存凭据

At session end, if the user manually provided an API key, space ID, or project name (not loaded from an existing profile), offer to save them to 
~/.arize/config.toml
. Use AskQuestion with "Yes, save them" / "No thanks". Skip if all values were already in the profile.
Read the existing file (or create it), add/update only the new fields, and write it back:
toml
[auth]
api_key = "THE_API_KEY"

[defaults]
space_id = "THE_SPACE_ID"
project = "THE_PROJECT_NAME"
会话结束时，如果用户手动提供了API密钥、空间ID或项目名称（并非从现有配置文件加载），请提供将其保存到
~/.arize/config.toml
的选项。使用询问用户功能，提供“是，保存”/“不用了，谢谢”选项。如果所有值已在配置文件中存在，则跳过此步骤。
读取现有文件（或创建新文件），仅添加/更新新字段，然后写回：
toml
[auth]
api_key = "THE_API_KEY"

[defaults]
space_id = "THE_SPACE_ID"
project = "THE_PROJECT_NAME"