Guía ITSM — CreaRack Network Sentinel

IT Service Management integrado en CNS para gestión profesional de incidentes de red. Versión: v1.0.43 (17-03-2026) Ubicación: Observatory → pestaña ITSM (accesible desde Wireless y UPS via “ITSM Settings”)

Índice

1. Visión General
2. Acceder a ITSM
3. Fase 1: SLA Policies
4. Fase 2: Notification Channels
5. Fase 3: Escalation Policies
6. Fase 4: Incident Correlation
7. Fase 5: Maintenance Windows
8. Fase 6: Analytics Dashboard
9. Fase 7: Known Issues
10. Fase 8: Post-Incident Reports
11. Fase 9: Insight Links
12. Fase 10: Runbooks
13. Fase 11: Recurring Patterns
14. Tareas en Background (Huey)
15. API Endpoints
16. Probando el Sistema
17. Django Admin
18. Modelos de Datos

1. Visión General

El módulo ITSM extiende CreaRack Network Sentinel (CNS) con capacidades de gestión de servicios IT:

Flujo automático: Cuando el Agent detecta una anomalía y envía un insight al SaaS:

1. Se verifica si hay una maintenance window activa → si sí, el insight se suprime
2. Se calculan los SLA deadlines (ack + resolve) según el risk_level
3. Se busca si coincide con un known issue → si sí, se enlaza
4. Se busca un runbook aplicable → si sí, se sugiere
5. Se ejecuta la correlation → si hay insights similares recientes, se agrupan
6. Se envían notificaciones a los canales configurados para ese risk_level
7. Tareas periódicas de Huey verifican SLA breaches, escalation y patterns

2. Acceder a ITSM

1. Navegar a Network Observatory (/monitoring/observatory/)
2. Hacer clic en la pestaña ITSM (última pestaña a la derecha)
3. La pestaña muestra:
   • Metrics bar: MTTA, MTTR, SLA Compliance, Active Escalations, Active Maintenance, Patterns Detected
   • Charts: Gráfica de tendencia MTTA/MTTR (30 días) y gráfica de distribución de riesgo
   • Secciones colapsables: Una por cada fase del sistema

Para expandir/colapsar una sección, hacer clic en su header (ej: “SLA Policies”, “Notification Channels”, etc.).

3. Fase 1: SLA Policies

Qué es

Define cuánto tiempo tiene el equipo para:

• Acknowledge (MTTA): Reconocer que se ha visto el insight
• Resolve (MTTR): Resolver o cerrar el insight

Cada nivel de riesgo (HIGH, MEDIUM, LOW) tiene sus propios timers.

Inicialización

La primera vez que se accede a ITSM, no existen SLA policies. Para crearlas:

Desde la UI: En la sección “SLA Policies” de la pestaña ITSM, hacer clic en el botón “Initialize Default Policies”. Esto crea automáticamente las 3 políticas por defecto:

Via API:

POST /api/sentinel/itsm/sla/initialize

Si ya existen policies, el endpoint retorna las existentes sin crear duplicados.

Configuración

Una vez inicializadas, en la sección “SLA Policies” de la pestaña ITSM:

1. Se muestran 3 filas: HIGH, MEDIUM, LOW
2. Cada fila tiene:
   • Ack (min): Minutos para acknowledge
   • Resolve (min): Minutos para resolver
   • Enabled: Checkbox para activar/desactivar
3. Hacer clic en Save para guardar cambios

Nota: Solo existen 3 policies (una por risk level). No se pueden crear más porque corresponden directamente a los 3 niveles de riesgo de los insights.

Cómo funciona

• Cuando se crea un insight, el sistema calcula sla_ack_deadline y sla_resolve_deadline basado en la policy del risk_level correspondiente
• Una tarea Huey cada 1 minuto verifica si algún deadline se ha excedido
• Si se incumple, el campo sla_ack_breached o sla_resolve_breached se marca True y se dispara una notificación

API

4. Fase 2: Notification Channels

Qué es

Canales de notificación que reciben alertas cuando ocurren eventos ITSM (insight creado, SLA breached, escalation).

Tipos soportados

Configuración (Panel UI)

El panel de Notification Channels permite al usuario configurar canales sin necesidad de acceder a Django Admin ni a la API directamente.

1. Ir a Observatory → ITSM → Notification Channels
2. Hacer clic en New Channel (botón azul en el header de la sección)
3. En el modal, rellenar:
   • Name: Nombre descriptivo (ej: “Slack NOC”, “Email Admins”)
   • Type: Seleccionar el tipo — los campos de configuración se adaptan automáticamente:
     • Email: Textarea para direcciones de email (una por línea)
     • Webhook: Campo URL + campo opcional de headers JSON custom
     • Slack: Campo para la URL del Incoming Webhook
     • Teams: Campo para la URL del Incoming Webhook
   • Risk Levels: Checkboxes HIGH / MEDIUM / LOW (dejar todos sin marcar = recibir todos los niveles)
   • Enabled: Toggle para activar/desactivar el canal
4. Hacer clic en Save

Operaciones disponibles en cada canal:

• Edit: Abre el modal con los datos actuales para modificar
• Test: Envía una notificación de prueba al canal
• Delete: Elimina el canal (con confirmación)

Cada tarjeta de canal muestra: nombre, tipo (badge), estado (Active/Disabled), risk levels, y un resumen de la configuración (emails destinatarios o URL truncada).

Requisitos por tipo

Email — Requiere SMTP configurado en producción:

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=tu-email@gmail.com
EMAIL_HOST_PASSWORD=app-password
DEFAULT_FROM_EMAIL=noreply@crearack.com

Slack — Crear webhook en: Slack > Apps > Incoming Webhooks

Teams — Crear webhook en: Teams > Canal > Connectors > Incoming Webhook

Webhook — Cualquier URL que acepte POST con JSON. Headers opcionales para autenticación.

Notification Log

El sistema mantiene un log de todas las notificaciones enviadas (sección “Notification Log” en ITSM). Cada entrada muestra: canal, evento, estado (sent/failed), código HTTP de respuesta, y timestamp.

API

5. Fase 3: Escalation Policies

Qué es

Políticas de escalamiento multinivel. Si un insight no se atiende dentro del tiempo configurado, se notifica a un canal de nivel superior.

Ejemplo

Política "HIGH Critical Path":
  Nivel 1: después de 15 min → notificar a "Slack NOC"
  Nivel 2: después de 30 min → notificar a "Email Manager"
  Nivel 3: después de 60 min → notificar a "Teams Director"

Configuración

1. En la sección “Escalation Policies”, hacer clic en Add Policy
2. Rellenar:
   • Name: Nombre de la política
   • Risk Level: HIGH, MEDIUM o LOW
   • Levels: Lista de escalamientos con:
     • Level: Número de nivel (1, 2, 3…)
     • Delay (min): Minutos desde la creación del insight para escalar
     • Channel: Canal de notificación a usar
3. El sistema verifica cada 2 minutos si algún insight pendiente requiere escalamiento

Cómo funciona

• Una tarea Huey cada 2 minutos busca insights con status=pending y escalation_level < max_level
• Calcula el tiempo transcurrido desde la creación
• Si el tiempo excede el delay_minutes del siguiente nivel, escala: envía notificación y actualiza escalation_level
• El campo escalation_level se muestra en el InsightDetailModal como badge

API

6. Fase 4: Incident Correlation

Qué es

Agrupación automática de insights relacionados. Cuando múltiples insights comparten el mismo root cause o afectan al mismo target en una ventana temporal corta, se agrupan en un Incident Group.

Reglas de correlación

Se aplican 3 reglas al crear cada nuevo insight:

1. Same target + same trigger (ventana 1 hora): Si ya existe un insight pendiente del mismo target con el mismo anomaly_trigger, se agrupan
2. Same trigger across targets (ventana 30 min): Si el mismo tipo de anomalía aparece en múltiples targets en 30 minutos, sugiere un problema de red generalizado
3. Same target rapid-fire (ventana 15 min): Si un target genera 3+ insights en 15 minutos, se agrupan como posible flapping

Gestión

En la sección “Incident Groups”:

• Ver grupos abiertos con su conteo de insights y targets afectados
• Resolve: Marcar un grupo como resuelto
• Acknowledge All: Hacer acknowledge de todos los insights pendientes del grupo de una vez

API

7. Fase 5: Maintenance Windows

Qué es

Ventanas de mantenimiento planificado que suprimen la creación de insights y/o notificaciones durante periodos específicos.

Configuración

1. En la sección “Maintenance Windows”, hacer clic en Add Window
2. Rellenar:
   • Title: Descripción del mantenimiento (ej: “Firmware upgrade switches planta 2”)
   • Start: Fecha/hora de inicio (formato ISO: 2026-03-15T02:00:00)
   • End: Fecha/hora de fin
   • Targets: IDs de targets afectados (vacío = todos los targets)
   • Suppress Insights: Si está activado, no se crean insights durante la ventana
   • Suppress Notifications: Si está activado, no se envían notificaciones
   • Notes: Notas adicionales
3. El campo Active indica si la ventana está activa en este momento

Cómo funciona

• Antes de crear un insight, el sistema verifica is_in_maintenance_window(target_id)
• Si hay una ventana activa con suppress_insights=True que incluye ese target (o todos), el insight NO se crea
• Si hay una ventana activa con suppress_notifications=True, las notificaciones se suprimen pero el insight sí se crea

API

8. Fase 6: Analytics Dashboard

Qué es

Dashboard de métricas ITSM con gráficas y KPIs.

Métricas disponibles

Gráficas

1. MTTA / MTTR Trend (30d): Línea temporal con la evolución de los tiempos de respuesta
2. Risk Distribution: Gráfico de torta con distribución HIGH/MEDIUM/LOW

API

El endpoint devuelve: mtta_minutes, mttr_minutes, sla_compliance, mtta_trend, mttr_trend, risk_distribution, top_devices, resolution_rate, provider_usage.

9. Fase 7: Known Issues

Qué es

Base de datos de problemas conocidos con resoluciones documentadas. Cuando un nuevo insight coincide con un known issue (por keywords), se enlaza automáticamente.

Configuración

1. En la sección “Known Issues”, hacer clic en Add Known Issue
2. Rellenar:
   • Title: Título descriptivo (ej: “CRC errors en interfaces GigabitEthernet Catalyst 9300”)
   • Description: Descripción detallada del problema
   • Resolution: Pasos para resolver (ej: “Reemplazar cable, verificar SFP, ejecutar clear counters”)
   • Match Keywords: Lista de palabras clave para auto-match (ej: ["crc", "errors", "catalyst"])
   • Risk Level: Nivel de riesgo asociado (opcional)
3. También se puede crear desde un insight existente: Create from Insight pre-rellena con los datos del insight

Auto-matching

Cuando se crea un nuevo insight, el sistema busca known issues cuyas match_keywords aparezcan en el anomaly_trigger o summary del insight. Si hay coincidencia:

• Se enlaza el known issue al insight (insight.known_issue = ki)
• Se incrementa occurrence_count
• Se actualiza last_seen
• En el InsightDetailModal aparece un badge con el título del known issue

API

10. Fase 8: Post-Incident Reports

Qué es

Informes post-incidente completos para cada insight. Incluyen toda la información del caso: diagnóstico, revisiones, recomendaciones, ejecución, acknowledge, conversaciones, SLA, known issue y runbook.

Uso

Los reportes se generan bajo demanda:

• JSON: GET /api/sentinel/itsm/reports/{insight_id} — datos estructurados
• Markdown: GET /api/sentinel/itsm/reports/{insight_id}/markdown — descarga archivo .md

Contenido del reporte

# Post-Incident Report — CNS-000042

## Target
- Name, IP, device type

## Diagnosis
- Summary, root cause, risk level, confidence, OSI layer

## Revision (si existe)
- Revised summary, root cause, confidence, rationale

## Recommendation
- Action label, commands, rollback commands

## Execution (si se aplicó)
- Status, applied by, applied at, result output

## Acknowledgement (si existe)
- Acknowledged by, when, notes

## Timeline
- Audit log completo (created, applied, acknowledged, rollback, etc.)

## Conversations
- Historial completo de preguntas/respuestas del Explain

## SLA
- Deadlines, breached status

## Known Issue (si existe)
- Title, description, resolution

## Runbook (si existe)
- Title, steps

API

11. Fase 9: Insight Links

Qué es

Enlaces manuales entre insights relacionados. Permite al operador conectar insights que tienen relación causal o temporal.

Tipos de enlace

Uso

Desde el InsightDetailModal o via API:

POST /api/sentinel/itsm/links
{
    "source_id": 42,
    "target_id": 45,
    "link_type": "related"
}

Los enlaces se muestran en ambas direcciones (source → target y target ← source).

API

12. Fase 10: Runbooks

Qué es

Biblioteca de procedimientos de remediación reutilizables. Cada runbook documenta pasos específicos para resolver un tipo de problema, con comandos asociados y vendor específico.

Configuración

1. En la sección “Runbooks”, hacer clic en Add Runbook
2. Rellenar:
   • Title: Nombre del procedimiento (ej: “Clear CRC errors — Cisco IOS”)
   • Description: Descripción del cuándo y por qué usar este runbook
   • Steps: Lista de pasos en formato JSON:

     [
         {"step": 1, "action": "Verify interface errors", "commands": ["show interface gi0/1"]},
         {"step": 2, "action": "Clear counters", "commands": ["clear counters gi0/1"]},
         {"step": 3, "action": "Monitor 5 minutes", "commands": ["show interface gi0/1 | include CRC"]}
     ]

   • Applicable Triggers: Keywords que disparan el auto-match (ej: ["crc", "errors", "interface"])
   • Vendor: Vendor específico (ej: cisco_ios, juniper_junos, vacío = genérico)

Auto-matching

Cuando se crea un nuevo insight, el sistema busca runbooks cuyas applicable_triggers coincidan con el anomaly_trigger del insight. Si hay match:

• Se sugiere el runbook (insight.suggested_runbook = rb)
• Se incrementa usage_count
• En el InsightDetailModal aparece un badge con el título del runbook

Apply manual

También se puede aplicar un runbook a un insight manualmente:

POST /api/sentinel/itsm/runbooks/{runbook_id}/apply/{insight_id}

API

13. Fase 11: Recurring Patterns

Qué es

Detección automática de patrones recurrentes en los insights. El sistema analiza el historial y detecta si un mismo tipo de anomalía se repite con frecuencia temporal predecible.

Tipos de patrón

Detección

• Una tarea Huey se ejecuta diariamente a las 3:00 AM y analiza los últimos 30 días de insights
• Para cada combinación target + anomaly_trigger, busca patrones temporales
• Si detecta un patrón con confianza >= 0.6 (60%), lo registra

Gestión

En la sección “Recurring Patterns”:

• Ver patrones detectados con confianza, tipo, target, trigger y conteo
• Acknowledge: Marcar como “ya conozco este patrón” (deja de aparecer como alerta)
• Delete: Eliminar el patrón

API

14. Tareas en Background (Huey)

El sistema ITSM ejecuta 4 tareas periódicas via Huey task queue:

Estas tareas requieren que el worker Huey esté activo (incluido en Docker Compose).

15. API Endpoints

Resumen completo de endpoints ITSM

Total: 42 endpoints ITSM

16. Probando el Sistema

Prerequisitos

1. El Agent debe estar conectado y en modo Sentinel generando insights
2. O bien, usar la API para crear insights de prueba manualmente

Paso a paso para probar cada fase

1. Inicializar SLA Policies

# Crear las 3 policies por defecto con un solo call
curl -X POST http://localhost:8000/api/sentinel/itsm/sla/initialize

O desde la UI: pestaña ITSM → sección SLA Policies → botón “Initialize Default Policies”.

Para ajustar tiempos después de inicializar:

curl -X PUT http://localhost:8000/api/sentinel/itsm/sla/policies/HIGH \
  -H "Content-Type: application/json" \
  -d '{"ack_minutes": 10, "resolve_minutes": 45, "enabled": true}'

2. Configurar un canal de notificación

# Crear webhook de prueba (usar webhook.site para testing)
curl -X POST http://localhost:8000/api/sentinel/itsm/notifications/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Webhook Test",
    "channel_type": "webhook",
    "config": {"url": "https://webhook.site/your-unique-id"},
    "risk_levels": ["HIGH", "MEDIUM"],
    "enabled": true
  }'

Luego: Test para verificar que llega la notificación.

3. Crear una Escalation Policy

# Política: HIGH → notificar a canal 1 después de 15 min, canal 2 después de 30 min
curl -X POST http://localhost:8000/api/sentinel/itsm/escalation/policies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HIGH Critical",
    "risk_level": "HIGH",
    "enabled": true,
    "levels": [
      {"level": 1, "delay_minutes": 15, "notification_channel_id": 1},
      {"level": 2, "delay_minutes": 30, "notification_channel_id": 1}
    ]
  }'

4. Crear una Maintenance Window

Desde la UI: sección Maintenance Windows → Add Window → configurar fechas/targets.

5. Crear un Known Issue

curl -X POST http://localhost:8000/api/sentinel/itsm/known-issues \
  -H "Content-Type: application/json" \
  -d '{
    "title": "CRC Errors en Cisco Catalyst",
    "description": "Errores CRC frecuentes en interfaces GigabitEthernet",
    "resolution": "1. Verificar cable. 2. Reemplazar SFP. 3. clear counters",
    "match_keywords": ["crc", "errors", "interface"],
    "risk_level": "MEDIUM"
  }'

6. Crear un Runbook

curl -X POST http://localhost:8000/api/sentinel/itsm/runbooks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix Interface CRC Errors",
    "description": "Procedimiento para resolver errores CRC en interfaces",
    "steps": [
      {"step": 1, "action": "Check errors", "commands": ["show interface gi0/1"]},
      {"step": 2, "action": "Clear counters", "commands": ["clear counters gi0/1"]}
    ],
    "applicable_triggers": ["crc", "errors"],
    "vendor": "cisco_ios"
  }'

7. Verificar Analytics

Navegar a la pestaña ITSM → las métricas se actualizan automáticamente al cargar. Los gráficos de tendencia MTTA/MTTR y distribución de riesgo se renderizan con ECharts.

8. Verificar Patterns

Los patrones se detectan automáticamente. Para forzar la detección, ejecutar desde Django shell:

from monitoring.tasks import detect_recurring_patterns
detect_recurring_patterns()

9. Generar un Report

# Obtener report de un insight (reemplazar {id} con un ID real)
curl http://localhost:8000/api/sentinel/itsm/reports/{id}

# Descargar como Markdown
curl http://localhost:8000/api/sentinel/itsm/reports/{id}/markdown -o report.md

Verificación rápida

1. SLA funciona: Crear insight, esperar > ack_minutes, verificar sla_ack_breached = True
2. Notificaciones funcionan: Crear canal webhook → test → verificar en webhook.site
3. Escalation funciona: Crear policy + canal → crear insight HIGH → esperar delay → verificar notificación
4. Maintenance funciona: Crear ventana activa → crear insight en target incluido → insight NO se crea
5. Known Issue match: Crear KI con keywords → crear insight con esas keywords → verificar enlace
6. Runbook match: Crear runbook con triggers → crear insight con esos triggers → verificar sugerencia
7. Correlation: Crear 2+ insights del mismo target/trigger en <1 hora → verificar grupo creado

Django Admin

Todos los modelos ITSM están registrados en Django Admin (/admin/monitoring/), permitiendo gestión directa por superusuarios:

Esto es útil para:

• Inspeccionar datos de cualquier organización (cross-tenant)
• Editar/eliminar registros directamente
• Auditar notification logs y escalation state
• Crear maintenance windows manualmente

Modelos de Datos

Tabla resumen

Campos ITSM en AIInsight

Centralización ITSM (v1.0.43+)

ObservatoryITSM.js como servicio compartido

A partir de v1.0.43, ObservatoryITSM.js funciona como un servicio instanciable que acepta parámetros de configuración:

import { ObservatoryITSM } from '../pages/observatory/ObservatoryITSM.js';

const itsm = new ObservatoryITSM({
    containerId: 'itsm-container',
    namespace: 'observatory',
    targetIds: null,  // null = org-wide, [1,2,3] = scoped
});
itsm.init();

Comportamiento

• Genera su propio HTML skeleton: Al inicializar, ObservatoryITSM inyecta las secciones colapsables (SLA, Channels, Escalation, etc.) dentro del contenedor especificado
• Channel modal: El modal de edicion de canales se crea dinamicamente y se appende a document.body (evita problemas de z-index con modales dentro de tabs)
• Namespace: Los atributos data-action usan el namespace proporcionado como prefijo para evitar conflictos DOM cuando multiples instancias coexisten

Scoping por target_ids

Acceso desde otras páginas

Las pestañas CNS de Wireless y UPS incluyen un botón “ITSM Settings” que navega a la pestaña ITSM del Observatory (/monitoring/observatory/?tab=itsm). ITSM no se duplica en cada pagina — es un recurso org-level centralizado en Observatory.

Patrón de integración para nuevas páginas

Para que una nueva pagina de dispositivos acceda a ITSM:

1. Añadir botón “ITSM Settings” en la pestaña CNS de la nueva pagina
2. El botón navega a /monitoring/observatory/?tab=itsm
3. No es necesario instanciar ObservatoryITSM en la nueva pagina — solo en Observatory

Archivos del Sistema

Backend

Frontend

Última actualización: 17-03-2026 Mantenido por: Claude (Anthropic) + Equipo CreaRack

Véase también

• [[concept—monitoring—itsm]] — gestión de incidencias ITSM
• [[concept—monitoring—cns]] — concepto del CreaRack Network Sentinel
• [[crearack—monitoring—itsm]] — ITSM orientado al usuario
• [[crearack-tech—guides—cns-guide]] — guía técnica de CNS
• [[crearack-tech—guides—cns-itsm-user-guide]] — guía de usuario CNS + ITSM
• [[crearack-tech—agents—dev-cns]] — perfil de subagente dev-cns
• [[entity—monitoring—model—aiinsight]] — insight generado por CNS