sentry

name	sentry
description	Investigate Sentry errors using NEW-FIRST methodology. USE WHEN finding new/trending errors, exception details, or error frequency during incidents.
metadata	{"triggers":["sentry","errors","exceptions","stack trace","new errors"],"provides":["error-search","exception-detail","frequency-analysis"],"requires":["mcp:sentry"],"auto_load":false}

Sentry Error Investigation

Analyze Sentry errors using the NEW-FIRST methodology.

🚨 CRITICAL: SENTRY TOOLS ARE AVAILABLE

Auth: $SENTRY_ACCESS_TOKEN (⛔ NOT SENTRY_AUTH_TOKEN). Token confirmed = EXECUTE THE QUERY.

Do NOT pre-check credentials. Just run the curl command. Only treat auth as a blocker after an actual 401/403 response.

⛔ PROHIBITED Behaviors

❌ WRONG	✅ CORRECT
"Sentry API access requires manual query"	Execute curl command
"additional configuration beyond current environment"	Token is set - use it
"If Sentry were accessible, we would expect..."	Query Sentry, get actual data
Writing expected findings without querying	Query first, document results
Creating phase5-sentry.md with hypotheticals	Run the actual API call

Verification Before Phase 5

# Step 1: Verify token exists
[ -n "$SENTRY_ACCESS_TOKEN" ] && echo "✅ Token set" || echo "❌ Token missing"

# Step 2: Execute query (DO NOT SKIP)
curl -s -H "Authorization: Bearer $SENTRY_ACCESS_TOKEN" \
  "https://github.sentry.io/api/0/projects/github/<project>/issues/?query=is:unresolved&start=<ISO8601>&end=<ISO8601>&limit=50&sort=new"

Why This Matters

Agents have incorrectly skipped Phase 5 (Sentry Errors) by:

• Confirming token is available
• Then claiming "requires manual query"
• Writing speculation instead of actual data

This is a critical failure. Sentry errors provide stack traces that identify exact code paths.

---

Available Execution Methods

# ✅ CORRECT - Execute this directly
curl -s -H "Authorization: Bearer $SENTRY_ACCESS_TOKEN" \
  "https://github.sentry.io/api/0/projects/github/gh-exception/issues/?query=is:unresolved&statsPeriod=24h"

---

Available Workflows

| Workflow | Team | Purpose | |----------|------|---------|| | /sentry:new-first | — | Investigate using NEW-FIRST methodology | | /sentry:shared-project | — | Query shared gh.exception project |

Team Workflows

Team-specific workflows use naming convention <team>-<workflow>.md with team: frontmatter.

Adding team workflows:

1. Create workflows/<team>-<name>.md
2. Add team: <team> to YAML frontmatter
3. Update this table

---

⛔ Step 0: Identify Sentry Projects via Service Context

Before querying Sentry, run services-context lookup "$SERVICE" to get the Sentry project names.

# Get sentry projects for the service
services-context info "$SERVICE" observability | jq '.sentry_projects'

This returns the exact catalog_name values to use as Sentry project slugs. For logical services (like actions), multiple sub-service projects are returned (e.g., actions-broker-worker, actions-results, actions-run-service).

If the service has sentry projects, query each one:

for proj in $(services-context info "$SERVICE" observability | jq -r '.sentry_projects[].catalog_name'); do
  echo "=== $proj ==="
  curl -s -H "Authorization: Bearer $SENTRY_ACCESS_TOKEN" \
    "https://github.sentry.io/api/0/projects/github/$proj/issues/?query=is:unresolved&start=$START&end=$END&limit=25&sort=new"
done

If no sentry projects found, fall back to the shared gh-exception project with catalog_service tag filtering.

---

⛔ CRITICAL: SEARCH BEYOND PRE-FILTERED LINKS

Monitor alerts often include links scoped to a specific project. These are useful starting points but may miss errors in other projects:

• Service-specific projects (from services-context info <svc> observability)
• github project (main application)
• gh-exception (shared exception project)

Recommended Search Strategy

Step	Purpose
0. Service context	services-context info <svc> observability → get project names
1. Service-specific projects	Query each sentry_projects[].catalog_name from Step 0
2. Check pre-filtered link	Quick look at what monitor flagged
3. Org-wide search	organizations/github/issues/?query=<service>+is:unresolved
4. Main github project	projects/github/github/issues/
5. Shared gh-exception	gh.exception.catalog_service:<service>

Use pre-filtered links as a starting point, but always verify with broader search.

---

Actor Concentration Check

After finding errors, check user distribution:

curl -s -H "Authorization: Bearer $SENTRY_ACCESS_TOKEN" \
  "https://github.sentry.io/api/0/organizations/github/issues/<issue_id>/tags/user/"

Distribution	Interpretation	Action
>50% single user	Actor-triggered bug	MUST identify actor by name
20-50% single user	Possible pattern	Investigate both user and service
<20% per user	Service-wide issue	Focus on service code/infra

⚠️ ACTOR IDENTIFICATION REQUIREMENT

If >50% concentration detected, you MUST name the actor before proceeding.

The /tags/user/ response contains user identities. Extract and report:

• topValues[0].value = actor username/ID
• topValues[0].count = number of events from that actor

FORBIDDEN: Saying "single actor pattern detected" without naming the actor.

Example compliant output:

"Actor: (83% of errors, 142 events)"

Example NON-compliant output (FORBIDDEN):

"Single user responsible for majority of errors"

---

NEW-FIRST Methodology

Priority order:

1. First Seen in incident window (NEW errors)
2. Trending up (significant increase)
3. High volume (existing patterns - lowest priority)

⚠️ Existing high-volume errors are usually NOT the root cause.

---

Troubleshooting Empty Results

When Sentry returns no results:

1. Check project spelling — use exact project names (see service context for list)
2. Search both is:unresolved AND is:resolved — recent fixes may match
3. Expand time window — error may have been batched or delayed
4. Check for rate limiting — high-volume errors get sampled
5. Use Datadog spans as fallback — errors appear in trace error tags

---

Shared Project (gh.exception)

For catalog services, use the shared project:

# Filter by catalog_service tag
curl -s -H "Authorization: Bearer $SENTRY_ACCESS_TOKEN" \
  "https://sentry.io/api/0/projects/github/gh-exception/issues/?query=gh.exception.catalog_service:<service>"

Tag: gh.exception.catalog_service (NOT catalog_service)

---

Completion Gate

• NEW errors in window checked
• Trending errors analyzed
• Stack traces reviewed
• Linked to investigation