Sentry Error Monitoring Skill

Created by Return Zero Inc.

Comprehensive Sentry integration for Claude Code providing issue retrieval, event analysis, error tracking, and project health monitoring capabilities.

Features

1. Issue Management

List issues by project or organization
Retrieve issue details (title, first/last seen, event count)
Filter by status (unresolved, resolved, ignored)
Search issues by query
Update issue status

2. Event Analysis

List events for specific issues
Retrieve event details with stack traces
Debug source map issues
Analyze error patterns

3. Project Monitoring

List organization projects
Get project health statistics
View error trends
Monitor release health

4. Tag Analysis

View tag distributions
Analyze error patterns by tag
Filter issues by tag values

Automatic Features

Rate Limiting: Respects Sentry API rate limits
Retry Logic: Automatic retry on transient errors
Environment Detection: Flexible environment variable pattern matching
Result Formatting: Markdown tables, JSON, or summary text
Error Handling: Clear, actionable error messages

Environment Variables

This skill uses environment variables managed by

jelly-dotenv

. See

skills/jelly-dotenv/SKILL.md

for configuration details.

Required variables:

```
SENTRY_AUTH_TOKEN
```
- Your Sentry authentication token (org or personal)
```
SENTRY_ORG
```
or
```
SENTRY_ORGANIZATION
```
- Organization slug

Optional variables:

```
SENTRY_PROJECT
```
- Default project slug
```
SENTRY_REGION
```
- API region: us (default), de
```
SENTRY_TIMEOUT
```
- Request timeout in ms (default: 30000)

Variables can be configured in either:

```
skills/jelly-dotenv/.env
```
(skill-common, highest priority)
Project root
```
/.env
```
(project-specific, fallback)

Configuration

Environment Variables

The skill automatically detects Sentry credentials using flexible pattern matching:

bash

# ✅ Standard naming (recommended)
SENTRY_AUTH_TOKEN=sntrys_your_token_here
SENTRY_ORG=my-organization
SENTRY_PROJECT=my-project

# ✅ Alternative naming
SENTRY_ORGANIZATION=my-organization
SENTRY_TOKEN=sntrys_your_token_here

# ✅ Wildcard patterns (auto-detected)
PROD_SENTRY_TOKEN=sntrys_your_token_here
PROD_SENTRY_ORG=my-organization

# ✅ Optional settings
SENTRY_REGION=us          # us (default), de
SENTRY_TIMEOUT=30000      # Request timeout in ms

Regional Endpoints

Supports US and EU (Germany) regions:

bash

# US (default)
SENTRY_REGION=us
# Base URL: https://sentry.io/api/0/

# Germany/EU
SENTRY_REGION=de
# Base URL: https://de.sentry.io/api/0/

API Endpoints Reference

Organizations

```
GET /api/0/organizations/
```
- List organizations
```
GET /api/0/organizations/{org}/
```
- Get organization details

GET /api/0/organizations/{org}/projects/

- List projects

Issues

```
GET /api/0/organizations/{org}/issues/
```
- List organization issues

GET /api/0/projects/{org}/{project}/issues/

- List project issues (deprecated)

GET /api/0/organizations/{org}/issues/{issue_id}/

- Get issue details

PUT /api/0/organizations/{org}/issues/{issue_id}/

- Update issue

DELETE /api/0/organizations/{org}/issues/{issue_id}/

- Delete issue

Events

GET /api/0/organizations/{org}/issues/{issue_id}/events/

- List issue events

GET /api/0/projects/{org}/{project}/events/

- List project error events

GET /api/0/projects/{org}/{project}/events/{event_id}/

- Get event details

Usage Scenarios

Scenario 1: List Unresolved Issues

User Request: "Show me all unresolved Sentry issues"

Skill Actions:

bash

# Load environment variables
source skills/jelly-dotenv/load-env.sh

# Build API URL
SENTRY_BASE_URL="${SENTRY_REGION:-us}"
if [ "$SENTRY_BASE_URL" = "de" ]; then
    SENTRY_BASE_URL="https://de.sentry.io"
else
    SENTRY_BASE_URL="https://sentry.io"
fi

# List unresolved issues
curl -s \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
  "${SENTRY_BASE_URL}/api/0/organizations/${SENTRY_ORG}/issues/?query=is:unresolved" | jq .

Scenario 2: Get Issue Details

User Request: "Show me details for issue 123456"

Skill Actions:

bash

curl -s \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
  "${SENTRY_BASE_URL}/api/0/organizations/${SENTRY_ORG}/issues/123456/" | jq .

Scenario 3: List Recent Events for an Issue

User Request: "Show me the last 10 events for issue 123456"

Skill Actions:

bash

curl -s \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
  "${SENTRY_BASE_URL}/api/0/organizations/${SENTRY_ORG}/issues/123456/events/?limit=10" | jq .

Scenario 4: Search Issues by Query

User Request: "Find all issues containing 'NullPointerException'"

Skill Actions:

bash

curl -s \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
  "${SENTRY_BASE_URL}/api/0/organizations/${SENTRY_ORG}/issues/?query=NullPointerException" | jq .

Scenario 5: List Project Error Events

User Request: "Show recent errors for my-project"

Skill Actions:

bash

curl -s \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
  "${SENTRY_BASE_URL}/api/0/projects/${SENTRY_ORG}/my-project/events/" | jq .

Scenario 6: Resolve an Issue

User Request: "Resolve issue 123456"

Skill Actions:

bash

curl -s -X PUT \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}' \
  "${SENTRY_BASE_URL}/api/0/organizations/${SENTRY_ORG}/issues/123456/" | jq .

Scenario 7: List Projects in Organization

User Request: "Show me all Sentry projects"

Skill Actions:

bash

curl -s \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
  "${SENTRY_BASE_URL}/api/0/organizations/${SENTRY_ORG}/projects/" | jq .

Security Policy

Authentication

Bearer Token: Authorization header with auth token
Credentials: Loaded from environment variables only
Logging: Tokens automatically redacted in logs

Permissions

Org Tokens: Recommended for CI/CD and automation
Personal Tokens: Bound to user permissions
Scopes: Configure minimal required scopes

Data Access

Read Operations: Primary focus (GET requests)
Write Operations: Status updates allowed
Destructive Operations: Issue deletion requires explicit confirmation

Error Handling

The skill provides comprehensive error handling with actionable messages:

Connection Errors

Network issues
Unreachable API
Action: Check internet connection and Sentry service status

Authentication Errors (401)

Invalid or expired token
Action: Verify SENTRY_AUTH_TOKEN is correct and not expired

Permission Errors (403)

Insufficient scope or access
Action: Check token scopes and organization membership

Not Found Errors (404)

Invalid organization, project, or issue ID
Action: Verify resource identifiers

Rate Limit Errors (429)

Too many requests
Action: Wait and retry (automatic backoff)

Output Formats

Markdown (Default)

Formatted tables with issue details
Key metrics summary
Status highlights

JSON

Raw API response
Programmatic access
Full data structure

Summary

Text overview
Critical issues only
Quick scan format

Bash Helper Functions

For command-line usage with jelly-dotenv:

bash

# Load environment variables from jelly-dotenv (with fallback to project root)
source skills/jelly-dotenv/load-env.sh

# Determine base URL
if [ "${SENTRY_REGION:-us}" = "de" ]; then
    SENTRY_BASE_URL="https://de.sentry.io"
else
    SENTRY_BASE_URL="https://sentry.io"
fi

# Sentry API curl helper
sentry-curl() {
    local endpoint="$1"
    shift
    curl -s \
        -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}" \
        -H "Content-Type: application/json" \
        "$@" \
        "${SENTRY_BASE_URL}/api/0${endpoint}" | jq .
}

# List unresolved issues
sentry-issues() {
    local query="${1:-is:unresolved}"
    sentry-curl "/organizations/${SENTRY_ORG}/issues/?query=${query}"
}

# Get issue details
sentry-issue() {
    local issue_id="$1"
    sentry-curl "/organizations/${SENTRY_ORG}/issues/${issue_id}/"
}

# List issue events
sentry-events() {
    local issue_id="$1"
    local limit="${2:-10}"
    sentry-curl "/organizations/${SENTRY_ORG}/issues/${issue_id}/events/?limit=${limit}"
}

# List projects
sentry-projects() {
    sentry-curl "/organizations/${SENTRY_ORG}/projects/"
}

# Resolve issue
sentry-resolve() {
    local issue_id="$1"
    sentry-curl "/organizations/${SENTRY_ORG}/issues/${issue_id}/" \
        -X PUT -d '{"status": "resolved"}'
}

# Ignore issue
sentry-ignore() {
    local issue_id="$1"
    sentry-curl "/organizations/${SENTRY_ORG}/issues/${issue_id}/" \
        -X PUT -d '{"status": "ignored"}'
}

Quick Aliases

Add to your

~/.bashrc

~/.zshrc

bash

# Sentry quick commands
alias sentry-unresolved='sentry-issues "is:unresolved"'
alias sentry-new='sentry-issues "is:unresolved firstSeen:-24h"'
alias sentry-critical='sentry-issues "is:unresolved level:fatal"'

Usage:

bash

# List unresolved issues
sentry-issues

# Get specific issue
sentry-issue 123456

# List events for issue
sentry-events 123456 20

# List projects
sentry-projects

# Resolve an issue
sentry-resolve 123456

# Search for specific errors
sentry-issues "TypeError is:unresolved"

Query Syntax

Sentry supports a powerful search syntax:

Status Filters

```
is:unresolved
```
- Unresolved issues
```
is:resolved
```
- Resolved issues
```
is:ignored
```
- Ignored issues

Time Filters

```
firstSeen:-24h
```
- First seen in last 24 hours
```
lastSeen:-1w
```
- Last seen in past week
```
age:-30d
```
- Created in last 30 days

Level Filters

```
level:error
```
- Error level issues
```
level:fatal
```
- Fatal/crash level
```
level:warning
```
- Warning level

Assignment

```
is:assigned
```
- Assigned to someone
```
is:unassigned
```
- Not assigned
```
assigned:me
```
- Assigned to current user

Combine Filters

bash

# Critical unresolved issues from today
sentry-issues "is:unresolved level:fatal firstSeen:-24h"

# Unassigned errors from past week
sentry-issues "is:unresolved is:unassigned lastSeen:-1w"

Integration with Claude Code

This skill activates automatically when users mention:

"sentry"
"error tracking"
"issues"
"exceptions"
"crashes"
"error monitoring"

The skill will:

Load Sentry credentials from .env
Execute the requested query
Format results as Markdown tables
Provide actionable error messages if something fails

Limitations

API Rate Limits: Subject to Sentry's rate limiting
Token Expiry: Personal tokens don't expire, org tokens may
Data Retention: Limited by Sentry plan retention period
Project Scope: Single organization per configuration

Troubleshooting

"Configuration error: SENTRY_AUTH_TOKEN is required"

Solution: Add auth token to .env file:

bash

SENTRY_AUTH_TOKEN=sntrys_your_token_here
SENTRY_ORG=my-organization

"Authentication failed (401)"

Solution:

Verify token is correct
Check token hasn't been revoked
Ensure token has required scopes

"Organization not found (404)"

Solution: Verify SENTRY_ORG matches your organization slug (not display name)

"Permission denied (403)"

Solution:

Check token scopes include required permissions
Verify user has access to the organization/project

Creating Auth Tokens

Organization Auth Token (Recommended)

Go to Settings > Developer Settings > Internal Integrations
Create a new Internal Integration
Configure required permissions:
- Project: Read
- Issue & Event: Read (or Admin for updates)
- Organization: Read
Copy the token

Personal Auth Token

Go to Account > API > Auth Tokens
Click "Create New Token"
Select required scopes
Copy the token

sentry

NPX Install

Tags

SKILL.md Content

Sentry Error Monitoring Skill

Features

1. Issue Management

2. Event Analysis

3. Project Monitoring

4. Tag Analysis

Automatic Features

Environment Variables

Configuration

Environment Variables

Regional Endpoints

API Endpoints Reference

Organizations

Issues

Events

Tags

Usage Scenarios

Scenario 1: List Unresolved Issues

Scenario 2: Get Issue Details

Scenario 3: List Recent Events for an Issue

Scenario 4: Search Issues by Query

Scenario 5: List Project Error Events

Scenario 6: Resolve an Issue

Scenario 7: List Projects in Organization

Security Policy

Authentication

Permissions

Data Access

Error Handling

Connection Errors

Authentication Errors (401)

Permission Errors (403)

Not Found Errors (404)

Rate Limit Errors (429)

Output Formats

Markdown (Default)

JSON

Summary

Bash Helper Functions

Quick Aliases

Query Syntax

Status Filters

Time Filters

Level Filters

Assignment

Combine Filters

Integration with Claude Code

Limitations

Troubleshooting

"Configuration error: SENTRY_AUTH_TOKEN is required"

"Authentication failed (401)"

"Organization not found (404)"

"Permission denied (403)"

Creating Auth Tokens

Organization Auth Token (Recommended)

Personal Auth Token

References