Skip to main content

Sentry Investigation Skill

This skill provides comprehensive guidance for investigating production issues, errors, and performance metrics across Publica.la's distributed architecture using the Sentry MCP (Model Context Protocol) server.

Architecture Overview​

Publica.la uses a multi-tenant, augmented monolith architecture with the following services:

Core Services​

  • farfalla: Core multi-tenant monolith (Laravel) - Main backend service
  • volpe: Single-page reader (PDF, EPUB, Audiobook) - Frontend web application
  • fenice: Multi-platform reading apps (iOS, Android, macOS, Windows) - Mobile apps
  • castoro: PDF processing and optimization - Worker service
  • coniglio: Event tracking and analytics - Analytics service
  • medusa: Content intake with ONIX distribution - Content ingestion service
  • vito: AI assistant embedded as a plugin in Volpe
  • farfalla-integrations: Custom customer integrations
  • farfalla-https-guard: Certificate validation service

Sentry Organization​

  • Organization: publicala
  • Region: US (https://us.sentry.io)
  • Web URL: https://publicala.sentry.io

MCP Connection and Token Efficiency​

We access Sentry exclusively through the Sentry MCP server. All mcp_Sentry_* tool calls automatically authenticate and route via MCP—no manual tokens or HTTP requests are needed.

Token-Saving Guidelines​

  • Keep limit small (5–20) and narrow queries by project/issue/trace.

  • Prefer issueUrl directly to avoid an extra lookup before get_issue_details.

  • Use search_events for counts/aggregations; use search_issues only for grouped issue lists.

  • Avoid includeExplanation unless debugging query translation—it increases response size.

  • Reuse IDs/URLs from previous results instead of re-querying broadly.

  • When sampling, start with short time ranges; expand only if needed.

  • Lightweight calls (no host language):

    • mcp_Sentry_search_issues with organizationSlug="publicala", regionUrl, scoped query (e.g., "unresolved errors in farfalla last 24h"), limit <= 10.
    • mcp_Sentry_search_events for counts/aggregations (e.g., "error count by project last 24h", limit <= 10).
    • mcp_Sentry_get_issue_details using the issueUrl directly when you already have it.

Quick Start​

1. Identify the User and Organization​

Always start by identifying the authenticated user and organization using:

  • mcp_Sentry_whoami()
  • mcp_Sentry_find_organizations() → expect publicala with regionUrl=https://us.sentry.io

2. Find Projects and Teams​

  • mcp_Sentry_find_projects(organizationSlug="publicala", regionUrl="https://us.sentry.io")
  • mcp_Sentry_find_teams(organizationSlug="publicala", regionUrl="https://us.sentry.io")

3. Search for Issues​

Use search_issues for grouped problems, NOT for counts:

  • mcp_Sentry_search_issues(organizationSlug="publicala", regionUrl="https://us.sentry.io", naturalLanguageQuery="unresolved critical errors in farfalla", limit=20)
  • mcp_Sentry_search_issues(organizationSlug="publicala", naturalLanguageQuery="errors affecting more than 100 users", limit=10)

4. Get Issue Details​

  • mcp_Sentry_get_issue_details(issueUrl="https://publicala.sentry.io/issues/FARFALLA-36N")
  • Or by ID: mcp_Sentry_get_issue_details(organizationSlug="publicala", issueId="FARFALLA-36N", regionUrl="https://us.sentry.io")

5. Search Events (for counts and statistics)​

Use search_events for aggregations, counts, and individual events:

  • mcp_Sentry_search_events(organizationSlug="publicala", naturalLanguageQuery="error count by project in the last 7 days", limit=10)
  • mcp_Sentry_search_events(organizationSlug="publicala", naturalLanguageQuery="error logs from the last hour", limit=20)

Common Investigation Patterns​

Pattern 1: Investigate a Specific Error​

When a user reports a specific error or issue ID:

  1. mcp_Sentry_get_issue_details(issueUrl=...) or by issueId.
  2. Review stack trace and context from the response.
  3. mcp_Sentry_search_events scoped to the issue/trace for related events.
  4. If a trace ID exists, mcp_Sentry_get_trace_details(...).
  5. For AI root cause guidance, mcp_Sentry_analyze_issue_with_seer(issueUrl=...).

Pattern 2: Performance Investigation​

For performance issues, use event searches with aggregations:

  • mcp_Sentry_search_events(organizationSlug="publicala", naturalLanguageQuery="average response time by endpoint in farfalla", limit=20)
  • If you have a trace ID, mcp_Sentry_get_trace_details(organizationSlug="publicala", traceId=..., regionUrl="https://us.sentry.io")

Pattern 3: Service Health Check​

Check overall health of a service:

  • mcp_Sentry_search_events(organizationSlug="publicala", naturalLanguageQuery="error count and failure rate for volpe in the last 24 hours", limit=10)
  • mcp_Sentry_find_releases(organizationSlug="publicala", projectSlug="volpe", regionUrl="https://us.sentry.io", limit=10)

Pattern 4: User Impact Analysis​

Understand how errors affect users:

  • mcp_Sentry_search_issues(organizationSlug="publicala", naturalLanguageQuery="unresolved errors affecting more than 50 users", limit=20)
  • mcp_Sentry_search_events(organizationSlug="publicala", naturalLanguageQuery="error count by user in the last 7 days", limit=50)

Tool Selection Guide​

Use search_issues when:​

  • ✅ You need a list of grouped issues/problems
  • ✅ Filtering by status, assignment, or impact
  • ✅ Finding issues by type or project
  • ❌ DO NOT use for counts or statistics

Use search_events when:​

  • ✅ You need counts, aggregations, or statistics
  • ✅ Finding individual events with timestamps
  • ✅ Performance metrics (p95, averages, sums)
  • ✅ Error logs with specific time ranges

Use get_issue_details when:​

  • ✅ You have a specific issue ID or URL
  • ✅ Need detailed stack traces and context
  • ✅ Analyzing a known problem

Use analyze_issue_with_seer when:​

  • ✅ You need AI-powered root cause analysis
  • ✅ Want specific code fixes and recommendations
  • ✅ Understanding complex production errors

Use get_trace_details when:​

  • ✅ You have a specific trace ID (32-character hex)
  • ✅ Need performance trace analysis
  • ✅ Understanding request flow across services

Important Parameters​

Always Required​

  • organizationSlug: Always use "publicala"
  • regionUrl: Always use "https://us.sentry.io" for US region

Project-Specific Queries​

When querying a specific project, use projectSlug:

  • "farfalla" - Main backend
  • "volpe" - Web reader
  • "fenice" - Mobile apps
  • "castoro" - PDF processing
  • "coniglio" - Analytics
  • "medusa" - Content intake

Natural Language Queries​

The naturalLanguageQuery parameter accepts natural language and is automatically translated to Sentry query syntax. Examples:

  • "unresolved errors in farfalla"
  • "critical bugs from last week"
  • "errors affecting more than 100 users"
  • "error count by project in the last 7 days"
  • "average response time for API endpoints"
  • "database errors with timestamps"

Best Practices​

  1. Start Broad, Then Narrow: Begin with high-level searches, then drill down into specific issues
  2. Use Issue URLs: When users provide Sentry URLs, use them directly with get_issue_details
  3. Combine Tools: Use search_issues to find problems, then get_issue_details for deep dives
  4. Check Recent Releases: Use find_releases to correlate errors with deployments
  5. Use Seer for Complex Issues: For production errors requiring root cause analysis, use analyze_issue_with_seer
  6. Consider Multi-Tenancy: Remember that Publica.la is multi-tenant - errors may be tenant-specific

Common Error Patterns by Service​

Farfalla (Backend)​

  • Laravel exceptions (HttpResponseException, LazyLoadingViolationException)
  • Payment integration errors (Stripe, MercadoPago, PayU)
  • Authentication issues (SAML, OAuth, LTI)
  • Database and query problems

Volpe (Web Reader)​

  • JavaScript TypeErrors (EPUB/PDF rendering)
  • NetworkErrors (API calls)
  • Readium library issues
  • PDF rendering problems

Fenice (Mobile Apps)​

  • File download errors
  • Session limit errors
  • Audio player issues
  • Native module errors

Castoro (PDF Processing)​

  • PDF extraction failures
  • Worker processing errors
  • Text extraction issues

Examples​

Example 1: Investigate High-Impact Error​

  1. mcp_Sentry_search_issues(organizationSlug="publicala", naturalLanguageQuery="unresolved errors affecting more than 100 users", limit=5)
  2. Take the top result URL and call mcp_Sentry_get_issue_details(issueUrl=...).
  3. If needed, mcp_Sentry_analyze_issue_with_seer(issueUrl=...) for AI root cause.

Example 2: Service Health Dashboard​

  • mcp_Sentry_search_events(..., naturalLanguageQuery="error count by project in the last 24 hours", limit=10)
  • mcp_Sentry_search_events(..., naturalLanguageQuery="p95 response time by project", limit=10)
  • mcp_Sentry_find_releases(organizationSlug="publicala", regionUrl="https://us.sentry.io", limit=10)

Example 3: Trace Investigation​

  • mcp_Sentry_get_trace_details(organizationSlug="publicala", traceId="a4d1aae7216b47ff8117cf4e09ce9d0a", regionUrl="https://us.sentry.io")
  • mcp_Sentry_search_events(organizationSlug="publicala", naturalLanguageQuery="events in trace a4d1aae7216b47ff8117cf4e09ce9d0a", limit=50)

Reference​

See ARCHITECTURE.md for detailed architecture information and EXAMPLES.md for more complex investigation scenarios.