# Sentry

> Sentry error monitoring and issue tracking skill for retrieving issues, events, and project health data. Use when working with error tracking, exceptions, crashes, debugging production issues, or analyzing error patterns.

- Skill: `jakenuts/sentry` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jakenuts/sentry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jakenuts/sentry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jakenuts (https://skillmd.com/u/jakenuts)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jakenuts/sentry

---


# Sentry Error Monitoring Skill

**Created by [Return Zero Inc.](https://github.com/rtzr)**

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

### Tags
- `GET /api/0/organizations/{org}/issues/{issue_id}/tags/` - List issue tags
- `GET /api/0/organizations/{org}/issues/{issue_id}/tags/{tag}/values/` - Get tag values

## 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` or `~/.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:
1. Load Sentry credentials from .env
2. Execute the requested query
3. Format results as Markdown tables
4. 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**:
1. Verify token is correct
2. Check token hasn't been revoked
3. Ensure token has required scopes

### "Organization not found (404)"
**Solution**: Verify SENTRY_ORG matches your organization slug (not display name)

### "Permission denied (403)"
**Solution**:
1. Check token scopes include required permissions
2. Verify user has access to the organization/project

## Creating Auth Tokens

### Organization Auth Token (Recommended)
1. Go to Settings > Developer Settings > Internal Integrations
2. Create a new Internal Integration
3. Configure required permissions:
   - Project: Read
   - Issue & Event: Read (or Admin for updates)
   - Organization: Read
4. Copy the token

### Personal Auth Token
1. Go to Account > API > Auth Tokens
2. Click "Create New Token"
3. Select required scopes
4. Copy the token

## References

- [Sentry API Documentation](https://docs.sentry.io/api/)
- [Events & Issues API](https://docs.sentry.io/api/events/)
- [Authentication](https://docs.sentry.io/api/auth/)
- [Auth Tokens](https://docs.sentry.io/account/auth-tokens/)
- [Create Auth Token Tutorial](https://docs.sentry.io/api/guides/create-auth-token/)