playbooks

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

sentry-monitoring skill

/.claude/skills/sentry-monitoring

This skill helps you monitor errors, performance, and releases with Sentry, providing contextual insights and actionable guidance for faster resolutions.

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 (11)
SKILL.md
6.8 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
---

**Mode: Cognitive/Prompt-Driven** — No standalone utility script; use via agent context.

# 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 Sentry error tracking and performance monitoring for real-time visibility into application errors, performance issues, and release health. It reduces the need for raw API calls by exposing focused tools for errors, transactions, releases, and project configuration. Use it to triage incidents, investigate performance regressions, and manage releases with confirmation for destructive actions.

How this skill works

The skill maps common Sentry API operations into compact tools that list issues, fetch issue details, manage issue state, and surface performance transactions and slow queries. It supports release workflows like creating releases and associating commits, plus project-level queries for settings and alerts. Destructive operations require explicit confirmation and the skill relies on environment variables for authentication and scope management.

When to use it

  • Triage production errors and assign or resolve issues during an incident
  • Investigate slow endpoints or database bottlenecks after a performance regression
  • Create and associate a release when deploying a new version
  • Audit project settings and alert rules during on-call rotations
  • Quickly list projects or recent releases to verify deployment status

Best practices

  • Set SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_PROJECT as environment variables; never hardcode tokens
  • Confirm destructive actions (resolve, ignore, create release, set commits) to avoid accidental changes
  • Ensure the token has project:read, project:write, and event:read scopes
  • Use progressive queries (list then details) to minimize API usage and stay within rate limits
  • Validate organization and project slugs if you encounter 404 or permission errors

Example use cases

  • Run list-issues during an alert to surface the most recent unresolved errors
  • Open issue-details for stack traces and affected users, then resolve-issue after patch deploy
  • Use list-transactions and transaction-summary to find slow requests before a load test
  • Create-release and set-commits as part of a CI/CD pipeline to track release health
  • List-projects and list-alerts when onboarding a new monitoring environment

FAQ

What environment variables are required?

Only SENTRY_AUTH_TOKEN is needed for authenticated API calls; SENTRY_ORG and SENTRY_PROJECT default to the first org/project if not set.

What scopes does the token need?

Grant project:read, project:write, and event:read to cover listing, reading events, and making changes like resolving issues or creating releases.