Sentry Debugger

Sentry Debugger for {{PROJECT_NAME}}

When to Use Sentry vs LangSmith

Rule of thumb:

• Sentry = crashing problems (exceptions, failures)
• LangSmith = thinking problems (wrong output, bad reasoning)

Quick Start

• SENTRY_AUTH_TOKEN=... SENTRY_QUERY="is:unresolved environment:production" \ python .claude/skills/sentry-debugger/scripts/query_sentry_issues.py
• SENTRY_AUTH_TOKEN=... SENTRY_ISSUE_ID=... \ python .claude/skills/sentry-debugger/scripts/get_sentry_issue.py

Bundled Resources

References

• references/production-errors.md: production env vars + query examples.

Scripts

• scripts/query_sentry_issues.py: list recent issues via SENTRY_* env vars.
• scripts/get_sentry_issue.py: fetch a single issue (optional latest event).

Quick Start for Agents

Where to Find Auth Token (Local Development)

Location: backend/.env (in project root)

Required variables:

SENTRY_AUTH_TOKEN=sntryu_...   # API query token (REQUIRED for this skill)
SENTRY_DSN=https://...         # Error reporting DSN (different purpose)

How to check if token exists:

grep "SENTRY_AUTH_TOKEN" backend/.env

Quick Test (Verify Skill Works)

Run this to test the skill immediately:

# From project root
cd /path/to/Mission-Inbox

# Extract token and run test
SENTRY_AUTH_TOKEN=$(grep "^SENTRY_AUTH_TOKEN=" backend/.env | cut -d'=' -f2) \
./backend/venv/bin/python3 << 'EOF'
import os
import requests

token = os.environ.get("SENTRY_AUTH_TOKEN")
headers = {"Authorization": f"Bearer {token}"}
url = "https://sentry.io/api/0/projects/zappian-media/python-serverless/issues/"

response = requests.get(url, headers=headers, params={"query": "is:unresolved", "limit": 3})
print(f"Status: {response.status_code}")
if response.status_code == 200:
    issues = response.json()
    print(f"✅ Found {len(issues)} issues")
    for issue in issues:
        print(f"  • {issue['title'][:60]}")
else:
    print(f"❌ Error: {response.text[:200]}")
EOF

Expected output: Status: 200 with list of recent issues

Common Issues When Testing

Environment Variables (Railway)

SENTRY_AUTH_TOKEN=<set in Railway>
SENTRY_ORG=zappian-media
SENTRY_PROJECT=python-serverless
SENTRY_DSN=<set in Railway - used for sending errors>

Agent Architecture Context

Errors may originate from any node in the pipeline:

memory_hydrate_node → orchestrator_node → analyst_node → response

Common error sources:

• memory_hydrate_node: ChromaDB connection, collection not found
• orchestrator_node: LLM timeout, JSON parse errors
• analyst_node: PostgreSQL queries, tool failures, LLM errors

Troubleshooting Decision Tree

Start Here: What's the symptom?

Symptom                          → Sentry Search
─────────────────────────────────────────────────────────────
"App crashed"                    → is:unresolved level:fatal
"Something silently failed"      → is:unresolved level:error
"Intermittent issues"            → Sort by count, look for spikes
"Slow responses"                 → Search: timeout OR slow
"Database problems"              → Search: postgresql OR database

By Error Type: Where to Look

Database Errors (PostgreSQL)

Files to check: backend/app/database/connections.py, backend/app/analytics/tools/

LLM Errors (OpenAI/Anthropic/OpenRouter)

Files to check: backend/app/core/llm_clients.py

ChromaDB Errors

Files to check: backend/app/core/memory.py

JSON/Parsing Errors

Files to check: backend/app/agents/*/langgraph_node.py

By Agent: Common Errors

memory_hydrate_node

orchestrator_node

analyst_node

Error Severity Guide

🔴 FATAL (level:fatal)
   → App crashed, user got no response
   → Action: Fix immediately
   
🟠 ERROR (level:error)  
   → Something failed but app recovered
   → Action: Fix soon, check frequency
   
🟡 WARNING (level:warning)
   → Degraded experience, fallback used
   → Action: Monitor, fix if frequent
   
⚪ INFO (level:info)
   → Logged for debugging
   → Action: Ignore unless investigating

SDK Setup

import requests
import os

SENTRY_AUTH_TOKEN = os.environ["SENTRY_AUTH_TOKEN"]
SENTRY_ORG = os.environ.get("SENTRY_ORG", "zappian-media")
SENTRY_PROJECT = os.environ.get("SENTRY_PROJECT", "python-serverless")

headers = {"Authorization": f"Bearer {SENTRY_AUTH_TOKEN}"}
base_url = f"https://sentry.io/api/0"

Common Queries

List Recent Issues

# Get latest issues (errors grouped by type)
url = f"{base_url}/projects/{SENTRY_ORG}/{SENTRY_PROJECT}/issues/"
params = {"query": "is:unresolved", "limit": 10}

response = requests.get(url, headers=headers, params=params)
issues = response.json()

for issue in issues:
    print(f"{issue['title'][:60]}")
    print(f"  Count: {issue['count']} | First: {issue['firstSeen'][:10]}")
    print(f"  Link: {issue['permalink']}")

Get Recent Events (Individual Errors)

# Get actual error events (not grouped)
url = f"{base_url}/projects/{SENTRY_ORG}/{SENTRY_PROJECT}/events/"
params = {"limit": 20}

response = requests.get(url, headers=headers, params=params)
events = response.json()

for event in events:
    print(f"{event['title'][:50]} | {event['dateCreated'][:16]}")

Search by Error Type

# Find specific exception types
queries = {
    "database": "is:unresolved postgresql OR database OR sqlalchemy",
    "llm": "is:unresolved timeout OR openai OR anthropic OR LLM",
    "chromadb": "is:unresolved chromadb OR collection OR embedding",
    "json": "is:unresolved JSONDecodeError OR parse OR json",
}

query_type = "llm"  # change as needed
url = f"{base_url}/projects/{SENTRY_ORG}/{SENTRY_PROJECT}/issues/"
params = {"query": queries[query_type], "limit": 10}

response = requests.get(url, headers=headers, params=params)

Get Error Details

# Get full details for a specific issue
issue_id = "<issue-id-here>"
url = f"{base_url}/issues/{issue_id}/"

response = requests.get(url, headers=headers)
issue = response.json()

print(f"Title: {issue['title']}")
print(f"Count: {issue['count']}")
print(f"Users affected: {issue['userCount']}")

# Get latest event for this issue (with full stacktrace)
url = f"{base_url}/issues/{issue_id}/events/latest/"
response = requests.get(url, headers=headers)
event = response.json()

# Stacktrace
for entry in event.get("entries", []):
    if entry["type"] == "exception":
        for exc in entry["data"]["values"]:
            print(f"\nException: {exc['type']}: {exc['value']}")
            for frame in exc.get("stacktrace", {}).get("frames", [])[-5:]:
                print(f"  {frame.get('filename')}:{frame.get('lineNo')} in {frame.get('function')}")

Error Frequency Over Time

# Get error stats for last 24 hours
url = f"{base_url}/projects/{SENTRY_ORG}/{SENTRY_PROJECT}/stats/"
params = {"stat": "received", "resolution": "1h"}

response = requests.get(url, headers=headers, params=params)
stats = response.json()

print("Errors per hour (last 24h):")
for timestamp, count in stats[-24:]:
    print(f"  {timestamp}: {count}")

Debugging Scenarios

"What's crashing in production right now?"

# Unresolved issues, sorted by last seen
url = f"{base_url}/projects/{SENTRY_ORG}/{SENTRY_PROJECT}/issues/"
params = {
    "query": "is:unresolved",
    "sort": "date",
    "limit": 5
}
response = requests.get(url, headers=headers, params=params)

for issue in response.json():
    print(f"🔴 {issue['title'][:50]}")
    print(f"   Last seen: {issue['lastSeen']}")
    print(f"   Events: {issue['count']}")

"Are LLM calls timing out?"

url = f"{base_url}/projects/{SENTRY_ORG}/{SENTRY_PROJECT}/issues/"
params = {
    "query": "is:unresolved timeout OR TimeoutError OR ReadTimeout",
    "limit": 10
}
response = requests.get(url, headers=headers, params=params)

timeouts = response.json()
if timeouts:
    print(f"⚠️ Found {len(timeouts)} timeout-related issues")
else:
    print("✅ No timeout issues found")

"What errors happened during a specific query?"

# Search by custom tag (if you tag with session_id)
session_id = "abc123"
url = f"{base_url}/projects/{SENTRY_ORG}/{SENTRY_PROJECT}/issues/"
params = {"query": f"session_id:{session_id}"}

response = requests.get(url, headers=headers, params=params)

"Compare error rates: this week vs last week"

from datetime import datetime, timedelta

# This week
url = f"{base_url}/projects/{SENTRY_ORG}/{SENTRY_PROJECT}/stats/"
params = {"stat": "received", "resolution": "1d"}
response = requests.get(url, headers=headers, params=params)
stats = response.json()

this_week = sum(count for _, count in stats[-7:])
last_week = sum(count for _, count in stats[-14:-7])

print(f"This week: {this_week} errors")
print(f"Last week: {last_week} errors")
print(f"Change: {((this_week - last_week) / max(last_week, 1)) * 100:+.1f}%")

Query Syntax Reference

Adding Context to Your Code

To make Sentry errors more debuggable, add context in your agent nodes:

import sentry_sdk

# In analyst_node or orchestrator_node
sentry_sdk.set_context("agent", {
    "name": "analyst",
    "session_id": state.get("session_id"),
    "query": state.get("query")[:100],
})

sentry_sdk.set_tag("agent_type", "analyst")
sentry_sdk.set_tag("session_id", state.get("session_id"))

This allows filtering errors by agent type and session in Sentry.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.