performance-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xano Performance Analysis

Xano性能分析

Requires: A State Change subscription, the State Change browser extension installed in Chrome, and the

sc-xano

CLI to be authenticated (see the

sc-xano

skill).

所需条件： 订阅State Change服务、在Chrome中安装State Change浏览器扩展，并且完成

sc-xano

CLI的身份验证（可参考

sc-xano

技能说明）。

Workflow: "Why is my workspace slow?"

工作流："为什么我的工作区运行缓慢？"

Start broad, then drill into specifics.

先从宽泛排查入手，再深入定位具体问题。

Step 1: Identify the hottest endpoints

步骤1：识别最热端点

bash

npx @statechange/xano-cli performance top-endpoints --lookback 24 --format yaml

Returns all endpoints, tasks, triggers, and MCP tools ranked by total duration. Look at:

Total duration — which objects consume the most aggregate server time
Avg duration — which individual calls are slowest
Request count — high-frequency low-duration items may still matter

bash

npx @statechange/xano-cli performance top-endpoints --lookback 24 --format yaml

返回按总时长排序的所有端点、任务、触发器和MCP工具。需要查看的指标：

总时长 — 哪些对象累计消耗的服务器时间最多
平均时长 — 哪些单次调用的速度最慢
请求数 — 高频低耗时的项仍可能有优化价值

Step 2: Trace the worst offender

步骤2：追踪性能最差的项

bash

npx @statechange/xano-cli performance trace endpoint <query-id> --samples 10 --format yaml
npx @statechange/xano-cli performance trace task <task-id> --samples 10 --format yaml
npx @statechange/xano-cli performance trace trigger <trigger-id> --samples 10 --format yaml

Note: Task history items don't include stack traces (Xano API limitation). Trace will show duration percentiles but no step breakdown for tasks.

The trace output shows:

Duration percentiles (avg, p50, p95, p99) across samples
Step breakdown aggregated by
```
_xsid
```
— which steps consume the most time across all executions
Functions called — which custom functions are invoked and how often
Steps with high
```
occurrences
```
relative to
```
samples
```
indicate they run inside loops

bash

npx @statechange/xano-cli performance trace endpoint <query-id> --samples 10 --format yaml
npx @statechange/xano-cli performance trace task <task-id> --samples 10 --format yaml
npx @statechange/xano-cli performance trace trigger <trigger-id> --samples 10 --format yaml

注意： 任务历史项不包含堆栈追踪（Xano API限制）。追踪功能会显示任务的时长百分位，但不会提供步骤拆分。

追踪输出包含：

时长百分位（平均值、p50、p95、p99）：所有样本的耗时分布
步骤拆分：按
```
_xsid
```
聚合，展示所有执行中耗时最多的步骤
调用的函数：调用了哪些自定义函数以及调用频次
相对于样本量，
```
occurrences
```
（出现次数）较高的步骤说明它们运行在循环内部

Step 3: Deep-dive a single request

步骤3：深入分析单个请求

bash

npx @statechange/xano-cli performance deep-dive <request-id> --format yaml

This shows:

Recursive stack tree with direct vs rollup timing at each step
pct_of_total / pct_of_parent — percentage breakdowns
iterations — how many times loop bodies executed
Warnings for slow steps inside loops (DB queries, lambdas, external API calls)
functions_called summary with call counts and total time
stack_truncated: true means Xano capped the stack — see "Handling truncated stacks" below

bash

npx @statechange/xano-cli performance deep-dive <request-id> --format yaml

输出包含：

递归堆栈树：展示每个步骤的直接耗时和累计耗时
pct_of_total / pct_of_parent：耗时占比拆分
iterations：循环体执行的次数
循环内部慢步骤的警告（数据库查询、lambda、外部API调用）
functions_called 汇总，包含调用次数和总耗时
stack_truncated: true 表示Xano对堆栈做了截断，可参考下文"处理截断的堆栈"部分

Step 4: X-Ray the hot function

步骤4：X-Ray扫描热点函数

bash

npx @statechange/xano-cli xray function --id <function-id> --format yaml

Static analysis of the function's step hierarchy — warnings about nested slow steps, dependencies on other functions.

bash

npx @statechange/xano-cli xray function --id <function-id> --format yaml

对函数的步骤层级做静态分析，给出嵌套慢步骤、依赖其他函数等相关警告。

Step 5: Read the source

步骤5：查看源代码

bash

npx @statechange/xano-cli xanoscript generate function <function-id>

Generate XanoScript source to understand what the function does and recommend fixes.

bash

npx @statechange/xano-cli xanoscript generate function <function-id>

生成XanoScript源代码，了解函数逻辑并给出修复建议。

Workflow: "Why do I get errors?"

工作流："为什么我会遇到报错？"

bash

undefined

bash

undefined

1. Find requests with error status codes

1. 查找返回错误状态码的请求

npx @statechange/xano-cli history requests --format yaml

2. Deep-dive the error request to see which step failed

2. 深入分析错误请求，定位失败的步骤

npx @statechange/xano-cli performance deep-dive <error-request-id> --format yaml

3. X-Ray the failing function for structural issues

3. X-Ray扫描失败的函数，排查结构问题

npx @statechange/xano-cli xray function --id <failing-function-id> --format yaml

undefined

npx @statechange/xano-cli xray function --id <failing-function-id> --format yaml

undefined

Workflow: "Which functions should I optimize first?"

工作流："我应该优先优化哪些函数？"

bash

undefined

bash

undefined

1. Get endpoint ranking

1. 获取端点排名

npx @statechange/xano-cli performance top-endpoints --lookback 24 --format yaml

2. Trace the top 3-5 endpoints

2. 追踪排名前3-5的端点

npx @statechange/xano-cli performance trace endpoint <id1> --format yaml npx @statechange/xano-cli performance trace endpoint <id2> --format yaml npx @statechange/xano-cli performance trace endpoint <id3> --format yaml

3. Look at functions_called across all traces

3. 查看所有追踪结果中的functions_called

Rank by: avg_seconds_per_call x total_calls x number_of_callers

排序规则：单次调用平均耗时 × 总调用次数 × 调用方数量

This gives "optimization ROI" — fixing one function improves many endpoints

该值代表"优化投资回报率"：修复一个函数即可优化多个端点的性能

undefined

undefined

Handling truncated stacks

处理截断的堆栈

When

stack_truncated: true

appears in a deep-dive, Xano capped the stack at the endpoint's retention limit. Large

direct_seconds

on a function step with truncation means the real bottleneck is hidden.

bash

undefined

当深度分析结果中出现

stack_truncated: true

时，说明Xano将堆栈截断到了端点的保留限制。出现截断的函数步骤如果

direct_seconds

值很高，说明真正的瓶颈被隐藏了。

bash

undefined

1. Check current retention settings

1. 检查当前保留设置

npx @statechange/xano-cli logs show endpoint <id>

2. Set to unlimited to capture full stacks

2. 设置为无限制以捕获完整堆栈

npx @statechange/xano-cli logs set endpoint <id> --limit -1

3. Watch for new executions

3. 监听新的执行

npx @statechange/xano-cli logs watch endpoint <id>

4. Deep-dive the new (untruncated) execution

4. 深入分析新的（未截断的）执行

npx @statechange/xano-cli performance deep-dive <new-request-id> --format yaml

5. Restore the default limit when done

5. 操作完成后恢复默认限制

npx @statechange/xano-cli logs set endpoint <id> --limit 100

undefined

npx @statechange/xano-cli logs set endpoint <id> --limit 100

undefined

Interpreting Results

结果解读

High
direct_seconds
with no children — the step itself is slow (external API call, lambda, complex query)
Low
direct_seconds
but high
rollup_seconds
— children are slow, drill deeper
Same
_xsid
with high
occurrences
in trace — step runs inside a loop. Multiply
```
avg_rollup_seconds
```
by occurrences/samples to get per-request impact
DB queries inside loops (warnings) — classic N+1 problem. Move the query outside the loop or use a batch query
Lambda steps with high timing — interpreted code blocks are slower than native Xano steps

无下级步骤且
```
direct_seconds
```
值高 — 步骤本身运行缓慢（外部API调用、lambda、复杂查询）
```
direct_seconds
```
值低但
```
rollup_seconds
```
值高 — 下级步骤运行缓慢，需要进一步深入排查
追踪结果中相同
```
_xsid
```
的
```
occurrences
```
值高 — 步骤运行在循环内部。将
```
avg_rollup_seconds
```
乘以出现次数/样本量，即可得到对单次请求的影响
循环内部的数据库查询（警告） — 典型的N+1问题。将查询移到循环外部或者使用批量查询
Lambda步骤耗时高 — 解释执行的代码块比原生Xano步骤慢

History retention values

历史保留值说明

```
limit: 100
```
(default) — keeps top 100 stack steps, may truncate deep stacks
```
limit: -1
```
— unlimited, captures full stack (use for debugging)
```
limit: 0
```
— disabled, no history retained
```
inherit: true
```
— inherits from the parent API app settings
```
enabled: false
```
— history recording is off entirely

```
limit: 100
```
（默认） — 保留前100个堆栈步骤，深度较深的堆栈可能被截断
```
limit: -1
```
— 无限制，捕获完整堆栈（调试时使用）
```
limit: 0
```
— 禁用，不保留任何历史
```
inherit: true
```
— 继承父级API应用的设置
```
enabled: false
```
— 完全关闭历史记录功能