rollbar-reader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rollbar Reader

Rollbar 阅读器

Investigate and analyse Rollbar error tracking data using the

rollbar

CLI (https://github.com/delexw/rollbar-cli).

使用

rollbar

CLI（https://github.com/delexw/rollbar-cli）调查分析Rollbar错误追踪数据。

Arguments

参数

```
$ARGUMENTS[0]
```
— What to investigate (e.g.
```
"active errors last 24h"
```
,
```
"top items production"
```
,
```
"item 12345"
```
,
```
"deploys this week"
```
). Include the time range in the sentence (e.g.
```
"last 24h"
```
,
```
"yesterday"
```
,
```
"2026-03-01 to 2026-03-05"
```
). Use current agent's local timezone (detect via system clock) for any time-based queries, not UTC. Defaults to last 24 hours if no time range is mentioned.
```
$ARGUMENTS[1]
```
— (optional) Base directory for all temp assets. Defaults to
```
.rollbar-reader-tmp/
```
.

```
$ARGUMENTS[0]
```
— 要调查的内容（例如
```
"active errors last 24h"
```
、
```
"top items production"
```
、
```
"item 12345"
```
、
```
"deploys this week"
```
）。请在查询语句中包含时间范围（例如
```
"last 24h"
```
、
```
"yesterday"
```
、
```
"2026-03-01 to 2026-03-05"
```
）。所有基于时间的查询请使用当前Agent的本地时区（通过系统时钟检测），而非UTC。如果未提及时间范围，默认查询过去24小时的数据。
```
$ARGUMENTS[1]
```
— （可选）所有临时资源的根目录，默认为
```
.rollbar-reader-tmp/
```
。

System Requirements

系统要求

```
rollbar
```
CLI installed —
```
npm install -g @delexw/rollbar-cli
```
(see https://github.com/delexw/rollbar-cli)
A project access token configured via
```
rollbar config set-token <project> <token>
```
and
```
rollbar config set-default <project>
```
. Important: When checking configuration, verify at least 2 times before concluding it is not configured. Never expose token values — use existence checks only.
For account-level commands (teams, users, projects): account token configured via
```
rollbar config set-account-token <token>
```
(optional, only needed for account-level queries)

已安装
```
rollbar
```
CLI —
```
npm install -g @delexw/rollbar-cli
```
（参考https://github.com/delexw/rollbar-cli）
已通过
```
rollbar config set-token <project> <token>
```
和
```
rollbar config set-default <project>
```
配置项目访问令牌。重要提示： 检查配置时，至少验证2次再判定配置未完成。绝对不要泄露令牌值 — 仅检查是否存在即可。
如需执行账号级命令（团队、用户、项目相关）：需通过
```
rollbar config set-account-token <token>
```
配置账号令牌（可选，仅账号级查询需要）

Output Directory

输出目录

All intermediate JSON and the final report are saved to the output directory (default

.rollbar-reader-tmp/

.rollbar-reader-tmp/
├── items.json                  # Error items list
├── occurrences/
│   └── <ITEM_ID>.json          # Occurrences per item
├── deploys.json                # Deploy history
├── rql-results.json            # RQL query results (if used)
├── reports/
│   ├── top-active.json         # Top active items report
│   └── occurrence-counts.json  # Occurrence count data
└── report.md                   # Final analysis report

所有中间JSON文件和最终报告都会保存到输出目录（默认

.rollbar-reader-tmp/

）：

.rollbar-reader-tmp/
├── items.json                  # 错误条目列表
├── occurrences/
│   └── <ITEM_ID>.json          # 每条错误对应的事件记录
├── deploys.json                # 部署历史
├── rql-results.json            # RQL查询结果（如果使用）
├── reports/
│   ├── top-active.json         # 高活跃条目报告
│   └── occurrence-counts.json  # 事件计数数据
└── report.md                   # 最终分析报告

Execution

执行步骤

1. Verify Installation & Configuration

1. 验证安装与配置

Check if the

rollbar

CLI is installed:

bash

which rollbar

If not found, install it automatically:

npm install -g @delexw/rollbar-cli

. See references/setup-guide.md for full setup details.

If no projects are configured, guide the user through token setup using references/setup-guide.md. Never expose token values — use existence checks only.

Do NOT continue until both installation and configuration are verified.

检查

rollbar

CLI是否已安装：

bash

which rollbar

如果未找到，自动安装：

npm install -g @delexw/rollbar-cli

。完整安装详情请参考references/setup-guide.md。

如果未配置任何项目，请通过references/setup-guide.md引导用户完成令牌设置。绝对不要泄露令牌值 — 仅检查是否存在即可。

在安装和配置都验证通过前，请勿继续后续步骤。

2. Discover Configured Projects & Select Target

2. 发现已配置项目并选择目标

Always start by listing configured projects to know which projects are available:

bash

rollbar config list

This returns all configured project names. Use this to:

Show the user which projects are available to query
Infer the correct
--project
flag from the user's request context (e.g. if they mention "storefront errors", match to a project name like
```
elements-storefront
```
)
If only one project is configured, use it automatically
If multiple projects match the context, ask the user which one to query

The

--project <name>

global flag selects which project to query. It must match a name from

rollbar config list

. Examples:

bash

undefined

请始终首先列出已配置的项目 以了解可用的项目：

bash

rollbar config list

该命令会返回所有已配置的项目名称，你可以用它来：

向用户展示可查询的项目列表
根据用户的请求上下文推断正确的
--project
参数（例如如果用户提到"storefront errors"，匹配到类似
```
elements-storefront
```
的项目名）
如果仅配置了一个项目，自动使用该项目
如果有多个项目匹配上下文，询问用户要查询哪个项目

全局参数

--project <name>

用于选择要查询的项目，必须与

rollbar config list

返回的名称一致。示例：

bash

undefined

Query items for a specific project

查询指定项目的条目

rollbar --project elements-storefront items list --status active

Query occurrences for a specific project

查询指定项目的事件记录

rollbar --project elements-backend occurrences list


If the user does not specify a project and the default project (from `rollbar config show`) is appropriate, you can omit `--project` to use the default.

rollbar --project elements-backend occurrences list


如果用户未指定项目，且默认项目（通过`rollbar config show`获取）符合需求，可以省略`--project`参数使用默认项目。

3. Prepare Output Directory

3. 准备输出目录

Create the output directory and subdirectories:

bash

mkdir -p <OUT_DIR>/occurrences <OUT_DIR>/reports

Where

<OUT_DIR>

$ARGUMENTS[1]

.rollbar-reader-tmp/

if not provided.

bash

mkdir -p <OUT_DIR>/occurrences <OUT_DIR>/reports

其中

<OUT_DIR>

为

$ARGUMENTS[1]

的值，未提供则默认为

.rollbar-reader-tmp/

。

4. Investigate Using Items & Occurrences

4. 利用条目和发生事件开展调查

Based on

$ARGUMENTS[0]

(which includes the time range), query Rollbar data. Use

--format json

for all commands to get structured output. Run commands sequentially.

基于

$ARGUMENTS[0]

（包含时间范围）查询Rollbar数据。所有命令都使用

--format json

参数获取结构化输出，按顺序执行命令。

rollbar items

— Query Error Items (Readonly)

rollbar items

— 查询错误条目（只读）

List items with optional status and level filters:

bash

undefined

列出条目，支持按状态和级别筛选：

bash

undefined

List all active items (default project)

列出所有活跃条目（默认项目）

rollbar items list --status active

List active critical items for a specific project

列出指定项目的活跃严重级别条目

rollbar --project my-app items list --status active --level critical

List active errors (not warnings/info)

列出活跃错误（不包含警告/提示信息）

rollbar --project my-app items list --status active --level error

List resolved items

列出已解决的条目

rollbar --project my-app items list --status resolved

List muted items

列出已静音的条目

rollbar items list --status muted

Paginate through results

分页获取结果

rollbar --project my-app items list --status active --page 2


Available `--status` values: `active`, `resolved`, `muted`, etc.
Available `--level` values: `critical`, `error`, `warning`, `info`, `debug`.

**Get a single item** by ID, UUID, or project counter:

```bash

rollbar --project my-app items list --status active --page 2


可用的`--status`值：`active`、`resolved`、`muted`等。
可用的`--level`值：`critical`、`error`、`warning`、`info`、`debug`。

**通过ID、UUID或项目计数器获取单个条目**：

```bash

Get item by numeric ID

通过数字ID获取条目

rollbar items get --id 123456789

Get item by UUID

通过UUID获取条目

rollbar items get --uuid "abcd1234-ef56-7890-abcd-ef1234567890"

Get item by project counter (the "#123" number shown in Rollbar UI)

通过项目计数器获取条目（Rollbar UI中展示的"#123"编号）

rollbar --project my-app items get --counter 123

undefined

rollbar --project my-app items get --counter 123

undefined

rollbar occurrences

— Query Occurrences (Readonly)

rollbar occurrences

— 查询事件记录（只读）

List all recent occurrences across the project:

bash

undefined

列出项目下所有最近的事件记录：

bash

undefined

List recent occurrences (default project)

列出最近的事件记录（默认项目）

rollbar occurrences list

List occurrences for a specific project

列出指定项目的事件记录

rollbar --project my-app occurrences list

Paginate

分页获取

rollbar --project my-app occurrences list --page 2


**List occurrences for a specific item** (requires the item ID from `items list` or `items get`):

```bash

rollbar --project my-app occurrences list --page 2


**列出指定条目的事件记录**（需要从`items list`或`items get`获取的条目ID）：

```bash

Get all occurrences for item ID 123456789

获取条目ID 123456789的所有事件记录

rollbar --project my-app occurrences list-by-item 123456789

Paginate through occurrences

分页获取事件记录

rollbar --project my-app occurrences list-by-item 123456789 --page 2


**Get a single occurrence** by occurrence ID (for full detail including stack trace, request data, etc.):

```bash

rollbar --project my-app occurrences list-by-item 123456789 --page 2


**通过事件ID获取单条事件的完整详情**（包含堆栈跟踪、请求数据等完整信息）：

```bash

Get full occurrence detail

获取事件完整详情

rollbar occurrences get 987654321


This returns the complete occurrence payload — stack trace, request params, person data, server info, custom data, etc.

rollbar occurrences get 987654321


该命令返回完整的事件载荷 — 堆栈跟踪、请求参数、用户数据、服务器信息、自定义数据等。

Typical Investigation Workflow

典型调查工作流

List configured projects →
```
rollbar config list
```

List active errors →

rollbar --project <name> items list --status active --level error

Pick a high-impact item → note the item ID from the list

Get item detail →

rollbar --project <name> items get --id <item_id>

List occurrences for that item →

rollbar --project <name> occurrences list-by-item <item_id>

Get full occurrence detail →
```
rollbar occurrences get <occurrence_id>
```
(to see stack trace, request data)
Repeat for other high-priority items

Time range handling:

Extract time range from

$ARGUMENTS[0]

(e.g.

"last 24h"

"yesterday"

"2026-03-01 to 2026-03-05"

)

Convert to appropriate
```
--hours
```
flags for report commands or date ranges for RQL queries
Default: last 24 hours if no time range is mentioned in
```
$ARGUMENTS[0]
```

Save intermediate results as JSON to the output directory for reference.

列出已配置项目 →
```
rollbar config list
```

列出活跃错误 →

rollbar --project <name> items list --status active --level error

选择高影响条目 → 记录列表中的条目ID

获取条目详情 →

rollbar --project <name> items get --id <item_id>

列出该条目的事件记录 →

rollbar --project <name> occurrences list-by-item <item_id>

获取事件完整详情 →
```
rollbar occurrences get <occurrence_id>
```
（查看堆栈跟踪、请求数据）
对其他高优先级条目重复上述步骤

时间范围处理：

从

$ARGUMENTS[0]

中提取时间范围（例如

"last 24h"

、

"yesterday"

、

"2026-03-01 to 2026-03-05"

）

转换为报告命令对应的
```
--hours
```
参数，或RQL查询对应的日期范围
默认规则：如果
```
$ARGUMENTS[0]
```
中未提及时间范围，默认查询过去24小时的数据

将中间结果以JSON格式保存到输出目录供后续参考。

5. Deep-Dive (if needed)

5. 深度排查（如需要）

For error investigation, drill into specific items:

List active error/critical items
For each high-priority item, fetch recent occurrences
Get the full occurrence detail for the most recent occurrence to understand the error context (stack trace, request data, etc.)
Check deploys around the time errors started to correlate with releases

针对错误调查，深入分析特定条目：

列出活跃的错误/严重级别条目
对每个高优先级条目，拉取最近的事件记录
获取最新事件的完整详情，了解错误上下文（堆栈跟踪、请求数据等）
检查错误开始时间前后的部署记录，关联版本发布情况

6. Report

6. 生成报告

All timestamps in the report must use current agent's local timezone (detect via system clock), not UTC.

Write a structured analysis to

<OUT_DIR>/report.md

using the Write tool:

Summary — Overall error health and key findings
Top Items — Highest impact error items with occurrence counts, levels, and first/last seen
Error Details — Breakdown of investigated items: stack traces, affected environments, occurrence patterns
Deploy Correlation — Recent deploys and any correlation with error spikes
Trends — Occurrence count trends over the time range
Recommendations — Suggested follow-up actions (items to resolve, investigate further, etc.)

Inform the user of the report location:

<OUT_DIR>/report.md

报告中的所有时间戳必须使用当前Agent的本地时区（通过系统时钟检测），而非UTC。

使用写入工具将结构化分析结果写入

<OUT_DIR>/report.md

：

摘要 — 整体错误健康度和核心发现
Top条目 — 影响最高的错误条目，包含事件计数、级别、首次/末次出现时间
错误详情 — 已调查条目的细分信息：堆栈跟踪、受影响环境、事件发生规律
部署关联 — 最近部署记录及其与错误峰值的关联情况
趋势 — 选定时间范围内的事件计数趋势
建议 — 后续跟进动作建议（需解决的条目、需进一步调查的内容等）

告知用户报告的存放位置：

<OUT_DIR>/report.md

Reference Files

参考文件

Name	When to Read
references/setup-guide.md	Installation and configuration guide

<tags> <mode>think</mode> <custom>yes</custom> </tags>

名称	适用场景
references/setup-guide.md	安装和配置指南

<tags> <mode>think</mode> <custom>yes</custom> </tags>