SIFEN - Monitoreo y Observabilidad

Diagrama de Arquitectura de Monitoreo

Este diagrama muestra la arquitectura completa de observabilidad del sistema SIFEN con recolección, almacenamiento y visualización de métricas, logs y trazas.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e3f2fd',
    'primaryTextColor': '#0277bd',
    'primaryBorderColor': '#03a9f4',
    'lineColor': '#0288d1',
    'secondaryColor': '#f3e5f5',
    'tertiaryColor': '#e8f5e8',
    'background': '#ffffff'
  }
}}%%
graph TD
    subgraph "🚀 Aplicación SIFEN"
        APP["🎯 SIFEN API<br/><small>Aplicación principal</small>"]
        METRICS["📊 Metrics Endpoint<br/><small>/metrics</small>"]
        HEALTH["❤️ Health Endpoint<br/><small>/health</small>"]
        LOGS["📄 Structured Logs<br/><small>JSON format</small>"]
        TRACES["🔍 Distributed Tracing<br/><small>Request tracing</small>"]
    end
    
    subgraph "📊 Recolectores de Datos"
        PROM["🔥 Prometheus<br/><small>Métricas</small>"]
        LOKI["📄 Loki<br/><small>Logs</small>"]
        TEMPO["🔍 Tempo<br/><small>Traces</small>"]
        JAEGER["🔎 Jaeger<br/><small>Tracing UI</small>"]
    end
    
    subgraph "🗄️ Almacenamiento"
        TSDB[("📊 Time Series DB<br/><small>Métricas históricas</small>")]
        LOGDB[("📄 Log Storage<br/><small>Elasticsearch</small>")]
        TRACEDB[("🔍 Trace Storage<br/><small>Cassandra/S3</small>")]
    end
    
    subgraph "📈 Visualización y Alertas"
        GRAF["📈 Grafana<br/><small>Dashboards</small>"]
        ALERT["🔔 Alert Manager<br/><small>Gestión de alertas</small>"]
        KIBANA["🔍 Kibana<br/><small>Log analytics</small>"]
    end
    
    subgraph "📢 Canales de Notificación"
        EMAIL["📧 Email<br/><small>Alertas críticas</small>"]
        SLACK["💬 Slack<br/><small>Canal de desarrollo</small>"]
        SMS["📱 SMS<br/><small>Alertas urgentes</small>"]
        WEBHOOK["🌐 Webhooks<br/><small>Integraciones</small>"]
    end
    
    %% Conexiones de la aplicación
    APP --> METRICS
    APP --> HEALTH
    APP --> LOGS
    APP --> TRACES
    
    %% Recolectores
    METRICS --> PROM
    LOGS --> LOKI
    TRACES --> TEMPO
    TRACES --> JAEGER
    
    %% Almacenamiento
    PROM --> TSDB
    LOKI --> LOGDB
    TEMPO --> TRACEDB
    
    %% Visualización
    TSDB --> GRAF
    LOGDB --> GRAF
    TRACEDB --> GRAF
    LOGDB --> KIBANA
    JAEGER --> TRACEDB
    
    %% Alertas
    GRAF --> ALERT
    PROM --> ALERT
    
    %% Notificaciones
    ALERT --> EMAIL
    ALERT --> SLACK
    ALERT --> SMS
    ALERT --> WEBHOOK
    
    classDef appStyle fill:#e3f2fd,stroke:#2196f3,stroke-width:2px,color:#0d47a1
    classDef collectStyle fill:#e8f5e8,stroke:#4caf50,stroke-width:2px,color:#1b5e20
    classDef storageStyle fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#e65100
    classDef visualStyle fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#4a148c
    classDef notifyStyle fill:#fce4ec,stroke:#e91e63,stroke-width:2px,color:#880e4f
    
    class APP,METRICS,HEALTH,LOGS,TRACES appStyle
    class PROM,LOKI,TEMPO,JAEGER collectStyle
    class TSDB,LOGDB,TRACEDB storageStyle
    class GRAF,ALERT,KIBANA visualStyle
    class EMAIL,SLACK,SMS,WEBHOOK notifyStyle

Los Tres Pilares de la Observabilidad

📊 Métricas (Metrics)

Propósito: Datos cuantitativos agregados sobre el rendimiento del sistema.

Tipos de Métricas

1. Business Metrics:

   • Facturas procesadas por minuto
   • Tiempo promedio de procesamiento
   • Tasa de aprobación SIFEN
   • Documentos en contingencia

2. Application Metrics:

   • Request rate (req/s)
   • Response time (latencia)
   • Error rate (%)
   • Throughput

3. Infrastructure Metrics:

   • CPU utilization
   • Memory usage
   • Disk I/O
   • Network traffic

Prometheus Metrics Examples

// Custom metrics en la aplicación
private static readonly Counter ProcessedDocuments = Metrics
    .CreateCounter("sifen_documents_processed_total", 
    "Total number of processed documents", 
    new[] { "document_type", "status" });

private static readonly Histogram ProcessingDuration = Metrics
    .CreateHistogram("sifen_processing_duration_seconds",
    "Duration of document processing",
    new[] { "operation" });

private static readonly Gauge ContingencyQueueSize = Metrics
    .CreateGauge("sifen_contingency_queue_size",
    "Number of documents in contingency queue");

📄 Logs (Logging)

Propósito: Registros detallados de eventos específicos del sistema.

Structured Logging

{
  "timestamp": "2024-01-15T10:30:15.123Z",
  "level": "INFO",
  "logger": "SIFEN.API.Controllers.FacturaController",
  "message": "Document processed successfully",
  "properties": {
    "documentId": "550e8400-e29b-41d4-a716-446655440000",
    "contributorRuc": "80123456-7",
    "processingTimeMs": 1250,
    "sifenResponse": "APPROVED"
  },
  "traceId": "abc123def456",
  "spanId": "def456ghi789"
}

Log Levels y Propósito

• TRACE: Información muy detallada (debugging)
• DEBUG: Información de debugging para desarrollo
• INFO: Información general de operaciones
• WARN: Situaciones inesperadas pero recuperables
• ERROR: Errores que afectan funcionalidad
• FATAL: Errores críticos que pueden terminar la aplicación

🔍 Trazas (Distributed Tracing)

Propósito: Seguimiento de requests a través de múltiples servicios.

Trace Structure

Trace: Invoice Creation (trace-id: abc123)
├─ Span: API Request (span-id: def456)
│  ├─ Span: Validate Input (span-id: ghi789)
│  ├─ Span: Database Query (span-id: jkl012)
│  ├─ Span: Generate XML (span-id: mno345)
│  ├─ Span: Sign Document (span-id: pqr678)
│  └─ Span: Send to SIFEN (span-id: stu901)

Stack de Herramientas

🔥 Prometheus

Propósito: Recolección y almacenamiento de métricas.

Configuración

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'sifen-api'
    static_configs:
      - targets: ['sifen-api:8080']
    metrics_path: '/metrics'
    scrape_interval: 5s

Alerting Rules

groups:
- name: sifen-alerts
  rules:
  - alert: HighErrorRate
    expr: rate(sifen_requests_total{status=~"5.."}[5m]) > 0.1
    for: 2m
    labels:
      severity: critical
    annotations:
      summary: "High error rate detected"
      
  - alert: SIFENDown
    expr: up{job="sifen-api"} == 0
    for: 1m
    labels:
      severity: critical

📄 Grafana Loki

Propósito: Almacenamiento y consulta de logs.

Configuración de Ingesta

clients:
  - url: http://loki:3100/loki/api/v1/push
    external_labels:
      service: sifen-api
      environment: production

LogQL Queries Examples

# Errores en la última hora
{service="sifen-api"} |= "ERROR" | json | __error__ = ""

# Latencia alta en procesamiento de documentos
{service="sifen-api"} | json | processingTimeMs > 5000

# Documentos rechazados por SIFEN
{service="sifen-api"} | json | sifenResponse = "REJECTED"

🔍 Tempo & Jaeger

Propósito: Distributed tracing para seguimiento de requests.

Instrumentación en Código

using System.Diagnostics;
using OpenTelemetry.Trace;

public class FacturaService
{
    private static readonly ActivitySource ActivitySource = new("SIFEN.API");
    
    public async Task ProcessInvoice(CreateFacturaCommand command)
    {
        using var activity = ActivitySource.StartActivity("ProcessInvoice");
        activity?.SetTag("document.type", "invoice");
        activity?.SetTag("contributor.ruc", command.ContributorRuc);
        
        try
        {
            await ProcessDocument(command);
            activity?.SetStatus(ActivityStatusCode.Ok);
        }
        catch (Exception ex)
        {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            throw;
        }
    }
}

Dashboards de Grafana

📈 Business Dashboard

Métricas de Negocio:

• Facturas procesadas por hora/día
• Tiempo promedio de procesamiento
• Tasa de aprobación vs rechazo
• Documentos en cola de contingencia
• Revenue impact metrics

⚡ Technical Dashboard

Métricas Técnicas:

• Request rate y latencia
• Error rate por endpoint
• CPU/Memory utilization
• Database connection pool
• Redis cache hit rate

🏛️ SIFEN Integration Dashboard

Integración con SIFEN:

• SIFEN response times
• Success/error rates por tipo de documento
• Batch processing metrics
• Certificate expiration warnings
• Contingency mode activations

🚨 SLA Dashboard

Service Level Agreements:

• Uptime percentage
• P95/P99 response times
• Error budget consumption
• Apdex score
• MTTR (Mean Time To Recovery)

Configuración de Alertas

🔴 Alertas Críticas (P0)

• API Down: Servicio completamente caído
• Database Unavailable: BD principal inaccesible
• SIFEN Integration Failed: Falla total comunicación SIFEN
• High Error Rate: > 10% error rate por 5 minutos
• Certificate Expiring: Certificados digitales por vencer

🟠 Alertas Importantes (P1)

• High Latency: P95 > 5 segundos
• Contingency Mode: Activación modo contingencia
• Queue Backing Up: > 100 documentos en cola
• Memory Usage High: > 85% memory utilization
• Disk Space Low: < 15% disk space disponible

🟡 Alertas de Warning (P2)

• Unusual Traffic: Tráfico atípico detectado
• Cache Miss Rate High: Redis cache miss > 20%
• Background Job Delays: Jobs atrasados > 10 minutos
• Performance Degradation: Degradación gradual

Escalation Policy

escalation_policies:
  - name: "SIFEN Critical"
    escalation_rules:
      - escalation_delay_in_minutes: 0
        targets:
          - type: "user"
            id: "oncall-engineer"
      - escalation_delay_in_minutes: 5
        targets:
          - type: "user" 
            id: "team-lead"
      - escalation_delay_in_minutes: 15
        targets:
          - type: "user"
            id: "engineering-manager"

Canales de Notificación

📧 Email

Uso: Alertas críticas y reportes diarios Template:

<h2>🚨 SIFEN Alert: {{.GroupLabels.alertname}}</h2>
<p><strong>Severity:</strong> {{.CommonLabels.severity}}</p>
<p><strong>Description:</strong> {{.CommonAnnotations.summary}}</p>
<p><strong>Time:</strong> {{.CommonLabels.timestamp}}</p>
<a href="{{.CommonAnnotations.runbook_url}}">Runbook</a>

💬 Slack

Uso: Notificaciones en tiempo real al equipo Integration:

{
  "channel": "#sifen-alerts",
  "username": "Grafana",
  "title": "{{.GroupLabels.alertname}}",
  "text": "{{.CommonAnnotations.summary}}",
  "color": "{{if eq .Status \"firing\"}}danger{{else}}good{{end}}"
}

📱 SMS/Webhook

Uso: Alertas críticas fuera de horario Escalation: Solo para P0 y P1 después de horarios laborales

Métricas SLI/SLO

🎯 Service Level Indicators (SLI)

1. Availability: Uptime del servicio
2. Latency: P95 response time < 2 segundos
3. Throughput: Documentos procesados por minuto
4. Error Rate: < 1% de requests fallando

📊 Service Level Objectives (SLO)

slos:
  - name: "API Availability"
    target: 99.9%
    window: "30d"
    
  - name: "Response Latency"
    target: 95% # of requests < 2s
    window: "7d"
    
  - name: "Document Processing"
    target: 99.5% # success rate
    window: "24h"

💰 Error Budget

• Monthly Budget: 0.1% (43.8 minutos de downtime)
• Budget Burn Rate: Monitoreo continuo
• Policy: Freeze releases si budget < 10%

Runbooks y Procedimientos

📖 Common Runbooks

1. API Down: Pasos para diagnosticar y resolver
2. High Latency: Checklist de performance tuning
3. SIFEN Integration Issues: Troubleshooting comunicación
4. Database Problems: Recovery procedures
5. Certificate Renewal: Proceso de renovación

🔍 Incident Response

1. Detection: Alerta automática o reporte manual
2. Assessment: Determinar severity y impact
3. Response: Ejecutar runbook correspondiente
4. Communication: Notificar stakeholders
5. Resolution: Resolver y documentar
6. Post-mortem: Análisis y mejoras

Retención y Archivado

📊 Métricas

• High resolution (15s): 15 días
• Medium resolution (5m): 90 días
• Low resolution (1h): 1 año

📄 Logs

• Application logs: 30 días en hot storage
• Audit logs: 7 años (compliance fiscal)
• Debug logs: 7 días
• Archive: S3 Glacier para long-term storage

🔍 Traces

• Detailed traces: 7 días
• Sampled traces: 30 días
• Error traces: 90 días