playbooks

home / skills / oimiragieo / agent-studio / sentry-monitoring

sentry-monitoring skill

/.claude/skills/sentry-monitoring

This skill helps you monitor errors, performance, and releases in Sentry with context-rich insights for faster triage and healthier deployments.

npx playbooks add skill oimiragieo/agent-studio --skill sentry-monitoring

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
6.7 KB
---
name: sentry-monitoring
description: Sentry error tracking and performance monitoring for real-time visibility into application errors, performance issues, and release health
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Bash, Read, WebFetch]
best_practices:
  - Never expose auth tokens in output
  - Require confirmation for destructive operations
  - Use environment variables for credentials
error_handling: graceful
streaming: supported
---

# Sentry Monitoring Skill

## Overview

Provides 90%+ context savings vs raw Sentry API calls. Progressive disclosure by feature category: error tracking, performance monitoring, release management, and project configuration.

## Requirements

- Sentry account with project configured
- `SENTRY_AUTH_TOKEN` environment variable (optional, for authenticated API calls)
- `SENTRY_ORG` environment variable (optional, defaults to first organization)
- `SENTRY_PROJECT` environment variable (optional, defaults to first project)

## Tools (Progressive Disclosure)

### Error Tracking

| Tool          | Description               | Confirmation |
| ------------- | ------------------------- | ------------ |
| list-issues   | List recent issues/errors | No           |
| issue-details | Get detailed issue info   | No           |
| resolve-issue | Mark issue as resolved    | Yes          |
| ignore-issue  | Ignore/snooze issue       | Yes          |

### Performance Monitoring

| Tool                | Description                       | Confirmation |
| ------------------- | --------------------------------- | ------------ |
| list-transactions   | List performance transactions     | No           |
| transaction-summary | Get transaction performance stats | No           |
| slow-queries        | Identify slow database queries    | No           |

### Release Management

| Tool           | Description                    | Confirmation |
| -------------- | ------------------------------ | ------------ |
| list-releases  | List releases                  | No           |
| create-release | Create new release             | Yes          |
| set-commits    | Associate commits with release | Yes          |

### Project Configuration

| Tool             | Description           | Confirmation |
| ---------------- | --------------------- | ------------ |
| list-projects    | List Sentry projects  | No           |
| project-settings | View project settings | No           |
| list-alerts      | List alert rules      | No           |

## Quick Reference

```bash
# List recent issues
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$SENTRY_ORG/$SENTRY_PROJECT/issues/?query=is:unresolved"

# Get issue details
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/issues/{issue_id}/"

# Resolve issue
curl -X PUT -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/issues/{issue_id}/" \
  -d '{"status": "resolved"}'

# List transactions
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/events/?field=transaction"

# Create release
curl -X POST -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/releases/" \
  -d '{"version": "1.0.0", "projects": ["project-slug"]}'

# List projects
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/projects/"
```

## Configuration

### Environment Variables

| Variable            | Required | Description                                  |
| ------------------- | -------- | -------------------------------------------- |
| `SENTRY_AUTH_TOKEN` | Optional | Sentry authentication token for API calls    |
| `SENTRY_ORG`        | Optional | Organization slug (defaults to first org)    |
| `SENTRY_PROJECT`    | Optional | Project slug (defaults to first project)     |
| `SENTRY_DSN`        | No       | For SDK integration (not used by this skill) |

### Getting Auth Token

1. Navigate to Sentry Settings → Account → API → Auth Tokens
2. Create new token with scopes: `project:read`, `project:write`, `event:read`
3. Set as environment variable: `export SENTRY_AUTH_TOKEN=your_token_here`

## Security

⚠️ **Never expose auth tokens in output**
⚠️ **Destructive operations (resolve-issue, ignore-issue, create-release, set-commits) require confirmation**
⚠️ **Use environment variables for credentials, never hardcode**

## Agent Integration

- **devops** (primary): Production monitoring, incident response
- **incident-responder** (primary): Error triage, issue resolution
- **developer** (secondary): Debugging, performance optimization
- **qa** (secondary): Test environment monitoring

## Error Handling

If tool execution fails:

1. Verify `SENTRY_AUTH_TOKEN` is set: `echo $SENTRY_AUTH_TOKEN`
2. Check token permissions include required scopes
3. Verify organization and project slugs are correct
4. Review Sentry API rate limits (default: 3000 requests/minute)

## Common Workflows

### Incident Response

1. `list-issues` - Get recent unresolved errors
2. `issue-details` - Investigate specific issue
3. `resolve-issue` - Mark as resolved after fix deployed

### Performance Optimization

1. `list-transactions` - Identify slow endpoints
2. `transaction-summary` - Analyze performance patterns
3. `slow-queries` - Find database bottlenecks

### Release Management

1. `create-release` - Create new release version
2. `set-commits` - Associate commits with release
3. `list-releases` - Track release health

## Troubleshooting

| Issue               | Solution                                                                   |
| ------------------- | -------------------------------------------------------------------------- |
| 401 Unauthorized    | Check `SENTRY_AUTH_TOKEN` is valid and not expired                         |
| 403 Forbidden       | Verify token has required scopes (project:read, project:write, event:read) |
| 404 Not Found       | Verify `SENTRY_ORG` and `SENTRY_PROJECT` are correct slugs                 |
| Rate limit exceeded | Wait 1 minute, reduce request frequency                                    |

## Related

- Sentry API Documentation: https://docs.sentry.io/api/
- Sentry Error Tracking: https://docs.sentry.io/product/issues/
- Sentry Performance: https://docs.sentry.io/product/performance/
- Sentry Releases: https://docs.sentry.io/product/releases/

## Memory Protocol (MANDATORY)

**Before starting:**
Read `.claude/context/memory/learnings.md`

**After completing:**

- New pattern -> `.claude/context/memory/learnings.md`
- Issue found -> `.claude/context/memory/issues.md`
- Decision made -> `.claude/context/memory/decisions.md`

> ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

Overview

This skill provides a compact Sentry monitoring interface that surfaces error tracking, performance metrics, release management, and project configuration with 90%+ context savings compared to raw API calls. It is designed to give real-time visibility into application errors, slow transactions, and release health. The skill centralizes common Sentry workflows for incident response, performance optimization, and release verification.

How this skill works

The skill invokes Sentry API endpoints using an optional SENTRY_AUTH_TOKEN and environment defaults for organization and project slugs. It groups capabilities into feature categories (error tracking, performance, releases, project settings) and exposes non-destructive queries by default while requiring explicit confirmation for destructive operations. Responses are summarized and prioritized to show actionable context: unresolved issues, transaction hotspots, recent releases, and alert rules.

When to use it

  • Triage and resolve production errors quickly after alerts
  • Investigate slow endpoints and database query bottlenecks
  • Create and associate commits with a new release before deployment
  • Audit project configuration or list active alert rules
  • Pull quick summaries of recent issues or transaction trends

Best practices

  • Set SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_PROJECT as environment variables; avoid hardcoding tokens
  • Restrict token scopes to needed permissions (project:read, project:write, event:read)
  • Use non-destructive list and summary tools for routine checks; confirm before running resolve/ignore/create operations
  • Rate-limit polling to avoid hitting Sentry API limits (default 3000 requests/minute)
  • Verify org/project slugs if you see 404 or unexpected empty results

Example use cases

  • Run list-issues to get recent unresolved errors and then issue-details to inspect stack traces for a hot error
  • Execute list-transactions and transaction-summary to find a slow endpoint, then run slow-queries to identify DB hotspots
  • Create-release and set-commits during the CI pipeline to link deployment versions to events
  • List-projects and project-settings to audit environment-specific SDK configuration
  • List-alerts to confirm which rules will trigger on new regressions before a release

FAQ

Do I need an auth token to use the skill?

You can run unauthenticated read-only queries if allowed, but provide SENTRY_AUTH_TOKEN for authenticated API access and write operations.

Which destructive actions require confirmation?

Actions like resolve-issue, ignore-issue, create-release, and set-commits require explicit confirmation before execution.