Nexus - AI Task Orchestrator

81-log-anomaly-detection
Procedimiento: Log Anomaly Detection

Monitorizacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
10561 caracteres
# Procedimiento: Log Anomaly Detection

## Metadata
- **ID**: PROC-81
- **Frecuencia**: Diario
- **Duraci├│n estimada**: 15-25 min
- **Requiere**: Acceso a sistema de logs (Sentry, Application Insights, ELK, etc.)
- **Dependencias**: PROC-80 (Sentry Error Review)
- **Bloquea**: Ninguno
- **Agentes**: devops-engineer

---

## Objetivo

Detectar patrones an├│malos en logs:
1. Picos inusuales de errores
2. Patrones de error nuevos
3. Degradaci├│n de rendimiento
4. Comportamiento sospechoso (seguridad)

---

## Tipos de Anomal├¡as

| Tipo | Descripci├│n | Ejemplo |
|------|-------------|---------|
| Volume spike | Aumento repentino de logs | 10x errores normales |
| New error | Error nunca visto | Nueva excepci├│n |
| Pattern change | Cambio en distribuci├│n | M├ís 500 que 400 |
| Latency | Aumento de tiempos | P95 duplicado |
| Security | Comportamiento sospechoso | M├║ltiples 401/403 |

---

## Umbrales Base

| M├®trica | Normal | Warning | Critical |
|---------|--------|---------|----------|
| Errores/hora | <50 | 50-200 | >200 |
| Error rate % | <1% | 1-5% | >5% |
| P95 latency | <500ms | 500-1000ms | >1000ms |
| 401/403 por IP | <10 | 10-50 | >50 |

*Nota: Ajustar seg├║n baseline del proyecto*

---

## Checklist Ejecutable

### 1. Recopilar M├®tricas de ├Ültimas 24h

#### Sentry

```bash
# Usando Sentry API
SENTRY_AUTH_TOKEN="${SENTRY_AUTH_TOKEN}"
ORG="org-slug"
PROJECT="project-slug"

# Eventos de las ├║ltimas 24h
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$ORG/$PROJECT/stats/?stat=received&resolution=1h&since=$(date -d '24 hours ago' +%s)" | \
  jq '.[] | {time: .[0], count: .[1]}'

# Issues nuevos
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$ORG/$PROJECT/issues/?query=is:unresolved+firstSeen:-24h" | \
  jq 'length'
```

#### Application Insights (Azure)

```bash
# Usando Azure CLI
az monitor app-insights query --app $APP_ID --analytics-query "
  exceptions
  | where timestamp > ago(24h)
  | summarize count() by bin(timestamp, 1h)
"
```

#### ELK / Elasticsearch

```bash
# Errores por hora
curl -s -X GET "$ELASTIC_URL/logs-*/_search" -H 'Content-Type: application/json' -d '{
  "query": {
    "bool": {
      "filter": [
        {"range": {"@timestamp": {"gte": "now-24h"}}},
        {"term": {"level": "error"}}
      ]
    }
  },
  "aggs": {
    "per_hour": {
      "date_histogram": {"field": "@timestamp", "interval": "hour"}
    }
  },
  "size": 0
}'
```

- [ ] M├®tricas recopiladas
- [ ] Errores ├║ltimas 24h: ___

### 2. Detectar Picos de Volumen

```bash
# Calcular baseline y detectar picos
# Ejemplo con jq

# Promedio normal
avg=$(cat errors_per_hour.json | jq 'add / length')

# Horas con >2x promedio
cat errors_per_hour.json | jq --arg avg "$avg" '
  to_entries |
  map(select(.value > ($avg | tonumber) * 2)) |
  .[] | {hour: .key, count: .value, spike: "2x+"}'
```

**Picos detectados:**

| Hora | Errores | vs Baseline | Anomal├¡a |
|------|---------|-------------|----------|
| ___ | ___ | ___x | S├¡/No |

- [ ] Picos identificados

### 3. Identificar Errores Nuevos

```bash
# Sentry - Issues nuevos en 24h
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$ORG/$PROJECT/issues/?query=is:unresolved+firstSeen:-24h" | \
  jq '.[] | {title: .title, count: .count, firstSeen: .firstSeen}'

# Comparar con lista conocida
# (mantener archivo de errores conocidos)
```

**Errores nuevos:**

| Error | Ocurrencias | Primera vez | Severidad |
|-------|-------------|-------------|-----------|
| ___ | ___ | ___ | ___ |

- [ ] Errores nuevos listados

### 4. Analizar Distribuci├│n de C├│digos HTTP

```bash
# Distribuci├│n de status codes
curl -s -X GET "$ELASTIC_URL/logs-*/_search" -H 'Content-Type: application/json' -d '{
  "query": {"range": {"@timestamp": {"gte": "now-24h"}}},
  "aggs": {
    "status_codes": {
      "terms": {"field": "response.status_code"}
    }
  },
  "size": 0
}'
```

**Distribuci├│n actual vs baseline:**

| Status | Actual | Baseline | Cambio |
|--------|--------|----------|--------|
| 200 | ___% | ___% | ___ |
| 400 | ___% | ___% | ___ |
| 401 | ___% | ___% | ___ |
| 500 | ___% | ___% | ___ |

- [ ] Distribuci├│n analizada
- [ ] Cambios significativos identificados

### 5. Verificar Latencia

```bash
# P50, P95, P99 de response time
curl -s -X GET "$ELASTIC_URL/logs-*/_search" -H 'Content-Type: application/json' -d '{
  "query": {"range": {"@timestamp": {"gte": "now-24h"}}},
  "aggs": {
    "latency_percentiles": {
      "percentiles": {"field": "response.time", "percents": [50, 95, 99]}
    }
  },
  "size": 0
}'

# Application Insights
az monitor app-insights query --app $APP_ID --analytics-query "
  requests
  | where timestamp > ago(24h)
  | summarize
      p50 = percentile(duration, 50),
      p95 = percentile(duration, 95),
      p99 = percentile(duration, 99)
"
```

| Percentil | Actual | Baseline | Cambio | Estado |
|-----------|--------|----------|--------|--------|
| P50 | ___ ms | ___ ms | ___% | Ô£à/ÔÜá´©Å/ÔØî |
| P95 | ___ ms | ___ ms | ___% | Ô£à/ÔÜá´©Å/ÔØî |
| P99 | ___ ms | ___ ms | ___% | Ô£à/ÔÜá´©Å/ÔØî |

- [ ] Latencia verificada

### 6. Detectar Patrones de Seguridad

```bash
# IPs con muchos 401/403
curl -s -X GET "$ELASTIC_URL/logs-*/_search" -H 'Content-Type: application/json' -d '{
  "query": {
    "bool": {
      "filter": [
        {"range": {"@timestamp": {"gte": "now-24h"}}},
        {"terms": {"response.status_code": [401, 403]}}
      ]
    }
  },
  "aggs": {
    "by_ip": {
      "terms": {"field": "client.ip", "size": 20, "min_doc_count": 10}
    }
  },
  "size": 0
}'

# Endpoints m├ís atacados
curl -s -X GET "$ELASTIC_URL/logs-*/_search" -H 'Content-Type: application/json' -d '{
  "query": {
    "bool": {
      "filter": [
        {"range": {"@timestamp": {"gte": "now-24h"}}},
        {"terms": {"response.status_code": [401, 403]}}
      ]
    }
  },
  "aggs": {
    "by_endpoint": {
      "terms": {"field": "request.path.keyword", "size": 10}
    }
  },
  "size": 0
}'
```

**Actividad sospechosa:**

| IP/User | 401s | 403s | Patr├│n | Acci├│n |
|---------|------|------|--------|--------|
| ___ | ___ | ___ | ___ | ___ |

- [ ] Patrones de seguridad revisados

### 7. Correlacionar con Deploys

```bash
# Verificar si hubo deploys recientes
git log --oneline --since="24 hours ago" --all | head -5

# Correlacionar picos con tiempo de deploy
# Si errores empezaron justo despu├®s de deploy, probable regresi├│n
```

| Deploy | Hora | Errores Despu├®s | Correlaci├│n |
|--------|------|-----------------|-------------|
| ___ | ___ | ___ | Alta/Media/Baja |

- [ ] Correlaci├│n con deploys verificada

### 8. Generar Alertas

```bash
# Script de alertas
if [ $errors_24h -gt $threshold_critical ]; then
  echo "CRITICAL: $errors_24h errores en 24h"
  # Enviar notificaci├│n
elif [ $errors_24h -gt $threshold_warning ]; then
  echo "WARNING: $errors_24h errores en 24h"
fi
```

- [ ] Alertas generadas si aplica

---

## Output Esperado

```
====== PROC-81 COMPLETADO [TIMESTAMP] ======
Proyecto: [nombre]
Per├¡odo: ├║ltimas 24h

RESUMEN:
- Total eventos: X
- Errores: Y (Z%)
- Estado: Ô£à Normal / ÔÜá´©Å Anomal├¡as / ÔØî Cr├¡tico

VOLUMEN:
- Errores/hora promedio: X
- M├íximo: Y (hora HH:00)
- Picos detectados: Z

PICOS DE VOLUMEN:
| Hora | Errores | vs Normal | Causa Posible |
|------|---------|-----------|---------------|
| 14:00 | 500 | 5x | Deploy 13:55 |

ERRORES NUEVOS: X
| Error | Ocurrencias | Impacto |
|-------|-------------|---------|
| NullRef en PaymentService | 45 | Alto |

LATENCIA:
| P95 | Actual | Baseline | Estado |
|-----|--------|----------|--------|
|  | 450ms | 400ms | Ô£à OK |

SEGURIDAD:
- IPs con >50 401/403: X
- Patr├│n sospechoso: S├¡/No

CORRELACIONES:
- Deploy a las 13:55 ÔåÆ Pico a las 14:00 ÔÜá´©Å

ALERTAS GENERADAS:
- [lista si hay]

ACCIONES RECOMENDADAS:
1. Investigar error NullRef en PaymentService
2. Revisar deploy de las 13:55
```

---

## Criterios de ├ëxito

- [ ] Error rate < 1%
- [ ] Sin picos > 3x baseline
- [ ] Sin errores nuevos cr├¡ticos sin triaje
- [ ] Latencia dentro de SLA

---

## Alertas y Escalaci├│n

| Severidad | Condici├│n | Acci├│n |
|-----------|-----------|--------|
| CRITICAL | Error rate > 5% | WhatsApp inmediato |
| CRITICAL | Pico > 10x baseline | Investigar urgente |
| WARNING | Error rate > 1% | Revisar antes de fin de d├¡a |
| WARNING | Error nuevo con >100 ocurrencias | Crear issue |
| INFO | Anomal├¡a menor | Documentar y monitorear |

---

## Automatizaci├│n

En ejecuci├│n no-interactiva:
1. Consultar APIs de logging
2. Calcular m├®tricas
3. Comparar con baselines
4. Detectar anomal├¡as
5. Correlacionar eventos
6. Generar alertas

---


---

## 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-81 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-81"]
    }
  ],
  "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:**
- logs_analyzed, anomalies_found, patterns_identified

**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 | Proyecto | Errores 24h | Picos | Nuevos | Alertas |
|-------|----------|-------------|-------|--------|---------|
| | | | | | |