rollbar-reader

Rollbar Reader

Investigate and analyse Rollbar error tracking data using the rollbar CLI (https://github.com/delexw/rollbar-cli).

Inputs

Raw arguments: $ARGUMENTS

Infer from the arguments:

• QUERY: what to investigate. Defaults to last 24 hours if no time range is mentioned.
• SINCE: (optional) UTC ISO8601 start of analysis window. When provided, takes precedence over time derived from QUERY. Convert to epoch seconds for time-based CLI flags: date -d "<SINCE>" +%s (Linux) or date -jf "%Y-%m-%dT%H:%M:%SZ" "<SINCE>" +%s (macOS).
• UNTIL: (optional) UTC ISO8601 end of analysis window. When provided, takes precedence over time derived from QUERY. Convert to epoch seconds the same way.
• TITLE_HINT: (optional) Incident title keywords to use in error item search queries (e.g. the PD incident title).
• OUT_DIR: output directory for temp assets, or .rollbar-reader-tmp/ if not provided
• TZ_DISPLAY: (optional) Timezone abbreviation for report display (e.g. the output of date +"%Z" on the calling machine). When provided, use this for all report timestamps instead of detecting via system clock.

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)

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

Execution

1. Verify Installation & Configuration

Check if the rollbar CLI is installed:

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.

2. Detect Local Timezone

If TZ_DISPLAY was not provided, run the following to get the local timezone from the current machine:

date +"%Z"

Record the output as the display timezone for all report timestamps.

3. Discover Configured Projects & Select Target

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

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:

# 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.

4. Prepare Output Directory

Create the output directory and subdirectories:

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

Where <OUT_DIR> is OUT_DIR.

5. Investigate Using Items & Occurrences

Based on QUERY (which includes the time range), query Rollbar data. Use --format json for all commands to get structured output. Run commands sequentially.

rollbar items — Query Error Items (Readonly)

List items with optional status and level filters:

# 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:

# Get item by numeric ID
rollbar items get --id 123456789

# Get item by UUID
rollbar items get --uuid "abcd1234-ef56-7890-abcd-ef1234567890"

# Get item by project counter (the "#123" number shown in Rollbar UI)
rollbar --project my-app items get --counter 123

rollbar occurrences — Query Occurrences (Readonly)

List all recent occurrences across the project:

# 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):

# Get all occurrences for item 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.):

# 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.

Typical Investigation Workflow

1. List configured projects → rollbar config list
2. List active errors → rollbar --project <name> items list --status active --level error
3. Pick a high-impact item → note the item ID from the list
4. Get item detail → rollbar --project <name> items get --id <item_id>
5. List occurrences for that item → rollbar --project <name> occurrences list-by-item <item_id>
6. Get full occurrence detail → rollbar occurrences get <occurrence_id> (to see stack trace, request data)
7. Repeat for other high-priority items

Time range handling — when QUERY contains a named day ("today", "yesterday") or a calendar range, compute the window using local day boundaries, not UTC calendar days. A user saying "today" means since local midnight, so an event at 11am local is included even if it falls on a different UTC date.

For relative durations ("last 24h"), use --hours 24 where the CLI supports it, or compute as now - N*3600 in epoch seconds.

For named days, compute local day boundaries as epoch seconds:

# Start of local today (Linux / macOS)
date -d "$(date +%Y-%m-%d) 00:00:00" +%s          # Linux
date -jf "%Y-%m-%d %H:%M:%S" "$(date +%Y-%m-%d) 00:00:00" +%s  # macOS
# Start of local yesterday
date -d "$(date -d yesterday +%Y-%m-%d) 00:00:00" +%s          # Linux
date -jf "%Y-%m-%d %H:%M:%S" "$(date -v-1d +%Y-%m-%d) 00:00:00" +%s  # macOS

Use these epoch values in RQL queries: WHERE timestamp > SINCE_EPOCH AND timestamp < UNTIL_EPOCH.

Default: last 24 hours if no time range is mentioned in QUERY.

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

6. Deep-Dive (if needed)

For error investigation, drill into specific items:

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

7. Report

All timestamps in the report must use local timezone, not UTC. Format: 2026-03-20 15:30 <TZ> (with TZ abbreviation from date +"%Z"). Use TZ_DISPLAY if provided, otherwise detect via system clock (date +"%Z"). Do NOT use UTC in user-facing report sections — this includes timestamps that come directly from API responses (e.g. first_occurrence_timestamp, last_occurrence_timestamp, deploy times). Convert every timestamp to local time before writing it to the report.

Critical: When SINCE and UNTIL are provided as UTC ISO8601 (e.g. 2026-03-24T20:00:27Z), the report window header must also convert these boundaries to local time — do NOT copy the UTC hour values and relabel them as local timezone. Use date to convert:

# macOS — convert UTC ISO8601 to local display string
date -jf "%Y-%m-%dT%H:%M:%SZ" "2026-03-24T20:00:27Z" +"%Y-%m-%d %H:%M %Z"

Example: 2026-03-24T20:00:27Z converts to a different hour and possibly a different date in local time — do not copy the UTC hour value and relabel it.

Write a structured analysis to <OUT_DIR>/report.md using the Write tool:

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

Inform the user of the report location: <OUT_DIR>/report.md

Reference Files

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