Nexus - AI Task Orchestrator

80-sentry-error-review
Procedimiento: Revisi├│n y Resoluci├│n de Errores en Sentry

Monitorizacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
17202 caracteres
# Procedimiento: Revisi├│n y Resoluci├│n de Errores en Sentry

## Metadata
- **ID**: PROC-80
- **Frecuencia**: Diario (errores cr├¡ticos), Post-deploy, Semanal (revisi├│n completa)
- **Duraci├│n estimada**: 15-45 min seg├║n volumen
- **Requiere**: sentry-cli instalado y configurado, O acceso a Sentry MCP
- **Dependencias**: Ninguna
- **Bloquea**: Deploy a producci├│n si hay errores 500 cr├¡ticos sin resolver

## Objetivo

Gestionar errores de producci├│n de forma sistem├ítica, asegurando que cada incidencia tenga clasificaci├│n, responsable y plan de acci├│n documentado.

## Prerrequisitos: Configurar sentry-cli

### Instalaci├│n
```bash
# macOS
brew install getsentry/tools/sentry-cli

# Linux (script oficial)
curl -sL https://sentry.io/get-cli/ | bash

# npm (alternativa)
npm install -g @sentry/cli

# Verificar instalaci├│n
sentry-cli --version
```

### Autenticaci├│n
```bash
# Opci├│n 1: Login interactivo (genera token autom├íticamente)
sentry-cli login

# Opci├│n 2: Token manual (desde https://sentry.io/settings/auth-tokens/)
export SENTRY_AUTH_TOKEN="tu-token-aqu├¡"

# Opci├│n 3: Archivo .sentryclirc en home o proyecto
cat > ~/.sentryclirc << EOF
[auth]
token=tu-token-aqu├¡

[defaults]
org=dmi-hl
project=bigcommerce-api
EOF
```

### Verificar acceso
```bash
# Listar organizaciones accesibles
sentry-cli organizations list

# Listar proyectos
sentry-cli projects list --org dmi-hl
```

## Proyectos Sentry

| Proyecto | Aplicaci├│n | Org |
|----------|------------|-----|
| `apibigcommerce-mcp` | BigCommerceApi (MCP Server) | `dmi-hl` |
| `suppliercatalog-sync` | SupplierCatalog.Sync (Runners) | `dmi-hl` |

## Checklist Ejecutable

### 1. Obtener estado actual de errores

**Opci├│n A: Usando sentry-cli**
```bash
# Issues no resueltos, ordenados por eventos
sentry-cli issues list \
  --org dmi-hl \
  --project apibigcommerce-mcp \
  --status unresolved \
  --query "level:error" \
  --sort-by events

# Solo ├║ltimas 24h
sentry-cli issues list \
  --org dmi-hl \
  --project apibigcommerce-mcp \
  --status unresolved \
  --query "level:error firstSeen:-24h"

# Errores 500 espec├¡ficamente
sentry-cli issues list \
  --org dmi-hl \
  --project apibigcommerce-mcp \
  --query "http.status_code:500 is:unresolved"
```

**Opci├│n B: Usando Sentry MCP (conversacional)**
```
Buscar issues no resueltos en el proyecto bigcommerce-api
de la organizaci├│n dmi-hl, ├║ltimas 24 horas, nivel error
```

- [ ] Ejecutado: Lista de issues obtenida
- [ ] N├║mero de issues nuevos: ___
- [ ] N├║mero de errores 500: ___

### 2. Priorizar por severidad

| Prioridad | Criterio | SLA |
|-----------|----------|-----|
| **P0 - Cr├¡tico** | Error 500 en flujo de pedidos/facturaci├│n, >10 ocurrencias/hora | Fix en <4h |
| **P1 - Alto** | Error 500 en cualquier tool MCP, >50 usuarios afectados | Fix en <24h |
| **P2 - Medio** | Error 400 recurrente, degradaci├│n de funcionalidad | Fix en sprint actual |
| **P3 - Bajo** | Warnings, errores edge case, <5 ocurrencias | Backlog |

- [ ] Clasificados todos los issues nuevos por prioridad

### 3. Analizar cada issue P0/P1

**Opci├│n A: sentry-cli**
```bash
# Ver detalle de un issue espec├¡fico
sentry-cli issues show ISSUE-ID --org dmi-hl

# Ver eventos del issue
sentry-cli issues events ISSUE-ID --org dmi-hl
```

**Opci├│n B: Sentry MCP con Seer (an├ílisis IA)**
```
Analizar el issue BIGCOMMERCE-API-XXX con Seer para obtener
root cause analysis y sugerencias de fix
```

Documentar para cada issue P0/P1:
- [ ] **Issue ID**: ___
- [ ] **T├¡tulo**: ___
- [ ] **Root cause identificado**: S├¡ / No / Necesita investigaci├│n
- [ ] **Usuarios afectados**: ___
- [ ] **Primera ocurrencia**: ___
- [ ] **An├ílisis Seer**: [resumen]

### 4. Decidir acci├│n por issue

| Diagn├│stico | Acci├│n | Siguiente paso |
|-------------|--------|----------------|
| Bug reproducible en c├│digo propio | Fix en c├│digo | Crear branch `fix/sentry-ISSUE-ID` |
| Error en API externa (Amara, Icecat) | A├▒adir retry/fallback | Documentar, crear ticket |
| Error de datos/configuraci├│n | Corregir datos | Fix manual + hardening |
| False positive / ruido | Ignorar | `sentry-cli issues ignore ISSUE-ID` |
| No reproducible | Monitorear | A├▒adir breadcrumbs, esperar |

- [ ] Cada issue P0/P1 tiene acci├│n decidida

### 5. Aplicar fixes

Para cada issue que requiere fix de c├│digo:
```bash
# Crear branch
git checkout -b fix/sentry-ISSUE-ID

# Aplicar fix seg├║n an├ílisis
# ... cambios ...

# Verificar
dotnet build
dotnet test

# Commit con referencia a Sentry
git commit -m "fix: [descripci├│n corta]

Root cause: [explicaci├│n]
Sentry: ISSUE-ID

PROC-80"
```

- [ ] Branch creado para cada fix
- [ ] Tests pasan
- [ ] PR abierto

### 6. Cerrar issues resueltos

Para cada issue con fix aplicado y deployado:

**Paso 1: A├▒adir comentario con resoluci├│n**

sentry-cli no tiene comando para comentarios, usar Sentry MCP o API:
```
A├▒adir comentario al issue BIGCOMMERCE-API-XXX:

"Fix aplicado en commit abc123.
Root cause: [descripci├│n breve]
PR: [URL del PR]
Verificado en producci├│n: [fecha/hora]

PROC-80"
```

O via API REST:
```bash
curl -X POST "https://sentry.io/api/0/issues/ISSUE-ID/comments/" \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Fix aplicado en commit abc123.\nRoot cause: [descripci├│n]\nPR: [URL]\n\nPROC-80"
  }'
```

**Paso 2: Asignar a responsable**
```bash
# Nota: usar ID num├®rico (ej: 85189210), no short ID (ej: APIBIGCOMMERCE-MCP-Z)
sentry-cli issues assign --org dmi-hl --id NUMERIC_ID --user ramac21@gmail.com
```

**Paso 3: Resolver el issue**
```bash
# Nota: usar ID num├®rico de la columna "Issue ID" en sentry-cli issues list
sentry-cli issues resolve --org dmi-hl --id NUMERIC_ID
```

**Flujo completo en un script:**
```bash
#!/bin/bash
# close-sentry-issue.sh
ISSUE_ID=$1
COMMIT=$2
PR_URL=$3
ROOT_CAUSE=$4

# Comentario via API
curl -s -X POST "https://sentry.io/api/0/issues/${ISSUE_ID}/comments/" \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"Fix aplicado en commit ${COMMIT}.\nRoot cause: ${ROOT_CAUSE}\nPR: ${PR_URL}\n\nPROC-80\"}"

# Asignar a ramac21@gmail.com
sentry-cli issues assign $ISSUE_ID --org dmi-hl --user ramac21@gmail.com

# Resolver
sentry-cli issues resolve $ISSUE_ID --org dmi-hl

echo "Issue $ISSUE_ID cerrado y asignado a ramac21@gmail.com"
```

Uso:
```bash
./close-sentry-issue.sh BIGCOMMERCE-API-123 abc123def "https://gitlab.com/.../mr/45" "Race condition en transacci├│n SQL"
```

- [ ] Comentario a├▒adido con detalles del fix
- [ ] Issue asignado a ramac21@gmail.com
- [ ] Issue marcado como resolved

### 7. Gestionar issues no corregibles

Para issues que no se pueden/deben corregir:

**False positive:**
```bash
# Ignorar con raz├│n documentada primero via API/MCP
curl -X POST "https://sentry.io/api/0/issues/ISSUE-ID/comments/" \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "False positive: [raz├│n detallada]\n\nPROC-80"}'

# Asignar y marcar como ignorado
sentry-cli issues assign ISSUE-ID --org dmi-hl --user ramac21@gmail.com
sentry-cli issues ignore ISSUE-ID --org dmi-hl
```

**Error externo (no controlable):**
```bash
# Documentar que es externo y qu├® mitigaci├│n se aplic├│
curl -X POST "https://sentry.io/api/0/issues/ISSUE-ID/comments/" \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Error externo (API Icecat timeout).\nMitigaci├│n: retry con backoff a├▒adido.\nTicket seguimiento: JIRA-XXX\n\nPROC-80"}'

sentry-cli issues assign ISSUE-ID --org dmi-hl --user ramac21@gmail.com
sentry-cli issues resolve ISSUE-ID --org dmi-hl
```

### 8. Verificaci├│n post-fix (despu├®s de deploy)
```bash
# Ver si hay eventos nuevos del issue en ├║ltimas 2h
sentry-cli issues list \
  --org dmi-hl \
  --project apibigcommerce-mcp \
  --query "issue.id:ISSUE-ID firstSeen:-2h"
```

O via Sentry MCP:
```
Verificar si el issue BIGCOMMERCE-API-XXX ha tenido nuevas
ocurrencias en las ├║ltimas 2 horas
```

- [ ] 0 ocurrencias nuevas ÔåÆ Confirmar cierre exitoso
- [ ] Sigue ocurriendo ÔåÆ Reabrir investigaci├│n, a├▒adir comentario

## Comandos sentry-cli ├Ütiles
```bash
# Estad├¡sticas del proyecto
sentry-cli issues stats --org dmi-hl --project apibigcommerce-mcp

# Exportar a JSON para an├ílisis
sentry-cli issues list --org dmi-hl --project apibigcommerce-mcp --format json > issues.json

# Ver releases recientes
sentry-cli releases list --org dmi-hl --project apibigcommerce-mcp

# Crear release (para CI/CD)
sentry-cli releases new v1.2.3 --org dmi-hl --project apibigcommerce-mcp

# Asociar commits a release
sentry-cli releases set-commits v1.2.3 --auto --org dmi-hl
```

## Queries ├Ütiles

| Objetivo | Query para `--query` |
|----------|----------------------|
| Errores 500 ├║ltimas 24h | `is:unresolved level:error http.status_code:500 firstSeen:-24h` |
| Por tool MCP | `is:unresolved tags[tool_name]:orders_create` |
| Usuario espec├¡fico | `is:unresolved user.email:cliente@example.com` |
| Post-deploy | `is:unresolved firstSeen:-2h release:latest` |
| Muy recurrentes | `is:unresolved times_seen:>10` |

## Troubleshooting

| S├¡ntoma | Causa probable | Acci├│n |
|---------|----------------|--------|
| `error: Authentication required` | Token expirado/inv├ílido | Ejecutar `sentry-cli login` de nuevo |
| `error: project not found` | Nombre incorrecto o sin acceso | Verificar con `sentry-cli projects list` |
| `error: user not found` | Email no existe en org | Verificar email en Sentry ÔåÆ Settings ÔåÆ Members |
| Mismo error reaparece tras fix | Fix incompleto | Revisar todos los stacktraces |
| Error sin stacktrace ├║til | Excepci├│n re-lanzada sin contexto | A├▒adir m├ís info en catch |

## M├®tricas a Monitorear

| M├®trica | Umbral OK | Umbral Alerta |
|---------|-----------|---------------|
| Errores 500/d├¡a | <10 | >50 |
| Issues P0 abiertos | 0 | >0 |
| Issues P1 abiertos >24h | 0 | >2 |

## Resultado

- **├ëxito**:
  - 0 issues P0 abiertos
  - Todos los P1 tienen responsable y plan
  - Issues cerrados tienen comentario con resoluci├│n
  - Todos asignados a ramac21@gmail.com

- **Parcial**:
  - P0 resueltos pero quedan P1 en progreso

- **Fallo**:
  - Issues P0 sin resolver ÔåÆ Escalar inmediatamente
  - sentry-cli no funciona ÔåÆ Verificar instalaci├│n y token

## Escalaci├│n

| Situaci├│n | Escalar a | C├│mo |
|-----------|-----------|------|
| Error 500 en pedidos >1h sin resolver | Lead t├®cnico | Directo + llamada |
| Sospecha de brecha seguridad | Seguridad | Inmediato |
| Error afecta >100 usuarios/hora | Product Owner | Notificar impacto |

## Mensaje de Finalizaci├│n

**IMPORTANTE - ACCI├ôN REQUERIDA AL FINALIZAR:**

Cuando hayas completado todos los pasos de este procedimiento, DEBES:

### Paso 1: Log de finalizaci├│n
```bash
echo "====== PROCESO TERMINADO [$(date +%H%M%S)] ======" && echo "RESULTADO: X issues Sentry revisados, 0 P0, 0 P1, Y cerrados"
```
Sustituye X e Y por los n├║meros reales.

### Paso 2: Enviar email de notificaci├│n via Zapier MCP

**Prerrequisito:** ZapierProxy debe estar corriendo en `http://localhost:5050`

**2.1 Obtener token de Zapier:**
```bash
curl -s http://localhost:5050/token
```
Si devuelve error 401, el usuario debe autenticar visitando http://localhost:5050/auth/start

**2.2 Crear archivo JSON con el reporte:**
```bash
# Crear el archivo de request (sustituir valores reales)
cat > /tmp/sentry_report_email.json << 'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "gmail_send_email",
    "arguments": {
      "instructions": "Send Sentry review report email",
      "to": ["ramac21@gmail.com"],
      "subject": "[PROC-80] Sentry Review Completed - {FECHA}",
      "body": "<h2>Reporte PROC-80: Revision de Errores Sentry</h2><p><b>Fecha:</b> {FECHA}</p><p><b>Proyecto:</b> {PROYECTO}</p><hr><h3>Resumen</h3><ul><li><b>Issues revisados:</b> {TOTAL}</li><li><b>P0 (Criticos):</b> {P0}</li><li><b>P1 (Altos):</b> {P1}</li><li><b>Cerrados/Resueltos:</b> {CERRADOS}</li><li><b>Ignorados:</b> {IGNORADOS}</li></ul><h3>Detalle de Acciones</h3><p>{DETALLE_ACCIONES}</p><hr><p><i>Generado automaticamente por PROC-80</i></p>",
      "body_type": "html"
    }
  }
}
EOF
```

**2.3 Enviar el email:**
```bash
TOKEN=$(curl -s http://localhost:5050/token | grep -o '"accessToken":"[^"]*"' | cut -d'"' -f4)
curl -s -X POST "https://mcp.zapier.com/api/mcp/a/23329892/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d @/tmp/sentry_report_email.json
```

**Verificar respuesta:** Debe contener `"status":"SUCCESS"` en el resultado.

### Plantilla de Email Completa

Sustituir los placeholders en el JSON:

| Placeholder | Descripci├│n | Ejemplo |
|-------------|-------------|---------|
| `{FECHA}` | Fecha de ejecuci├│n | `2026-01-06` |
| `{PROYECTO}` | Proyecto Sentry revisado | `agent-platform` |
| `{TOTAL}` | Total issues revisados | `9` |
| `{P0}` | Issues P0 encontrados | `0` |
| `{P1}` | Issues P1 encontrados | `2` |
| `{CERRADOS}` | Issues cerrados/resueltos | `5` |
| `{IGNORADOS}` | Issues ignorados | `4` |
| `{DETALLE_ACCIONES}` | Resumen de acciones tomadas | `Fixed Claude model issue, Fixed JSON parse error...` |

### Ejemplo Completo de Env├¡o

```bash
# 1. Verificar ZapierProxy est├í corriendo
curl -s http://localhost:5050/ | grep -q '"authenticated":true' || echo "ERROR: ZapierProxy no autenticado"

# 2. Obtener token
TOKEN=$(curl -s http://localhost:5050/token | grep -o '"accessToken":"[^"]*"' | cut -d'"' -f4)

# 3. Enviar email con datos reales
curl -s -X POST "https://mcp.zapier.com/api/mcp/a/23329892/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "gmail_send_email",
      "arguments": {
        "instructions": "Send Sentry review report",
        "to": ["ramac21@gmail.com"],
        "subject": "[PROC-80] Sentry Review - 2026-01-06 - agent-platform",
        "body": "<h2>PROC-80: Revision Sentry Completada</h2><p><b>Fecha:</b> 2026-01-06</p><p><b>Proyecto:</b> agent-platform</p><hr><h3>Resumen</h3><ul><li>Issues revisados: 9</li><li>P0: 0</li><li>P1: 2</li><li>Cerrados: 5</li><li>Ignorados: 4</li></ul><h3>Acciones</h3><p>- Fixed Claude model claude-3-5-haiku-20241022 to claude-3-5-haiku-latest<br>- Fixed JSON parse error in TaskContentGenerator<br>- Ignored 4 RabbitMQ startup issues (expected behavior)</p><hr><p><i>PROC-80 completado</i></p>",
        "body_type": "html"
      }
    }
  }'
```

### Troubleshooting Email

| Problema | Causa | Soluci├│n |
|----------|-------|----------|
| `401 Not authenticated` | ZapierProxy sin token | Visitar http://localhost:5050/auth/start |
| `Connection refused` | ZapierProxy no corriendo | Iniciar ZapierProxy.exe |
| `gmail_send_email not found` | Gmail no configurado en Zapier | Configurar Gmail en Zapier MCP dashboard |
| `Request body size mismatch` | JSON malformado | Usar archivo temporal con `-d @file.json` |


---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-80 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "issues_found": 9, "issues_resolved": 5,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-80"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- issues_found, p0_count, p1_count, issues_resolved, ignored_count

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar

## Historial de Ejecuciones

| Fecha | Ejecutor | Issues Revisados | P0 | P1 | Cerrados | Resultado |
|-------|----------|------------------|----|----|----------|-----------|
| | | | | | | |