KPI de canales fuera de línea¶

Un canal de video caído no avisa. La cámara deja de reportar, su mosaico queda en negro y, si nadie está mirando ese mosaico en ese momento, la falla puede pasar horas sin detectarse. En una instalación con cientos de canales repartidos entre varios NVR, recorrer el árbol de dispositivos uno por uno no es una opción.

El widget KPI resuelve esto con un indicador siempre visible: un número grande en el panel que responde, de un vistazo, ¿cuántos canales de video están fuera de línea ahora mismo? Y como el conteo se puede acotar por dominio, el mismo widget sirve tanto para una lectura global de toda la plataforma como para una lectura por sede, edificio o marca de equipo.

Esta guía construye ese indicador paso a paso: primero la versión global, y luego la variante acotada a un dominio.

Requisitos previos¶

Requisito	Detalle
Canales de video integrados	Debe existir al menos un dispositivo de video (NVR o cámara) dado de alta, con sus canales publicados como objetos de tipo `video_channel`.
Permiso de usuario	Tu usuario necesita el permiso `dashboard:canSeeKpiWidget`. Sin él, el widget KPI no aparece en el catálogo.
Permiso para editar el panel	Para agregar widgets, el panel no debe estar bloqueado y tu usuario debe poder modificarlo.

Por qué no basta el KPI nativo¶

Al abrir el catálogo de KPIs encontrarás una pestaña Native KPIs con un indicador llamado Online/Offline objects. Es tentador usarlo, pero no responde la pregunta de esta guía.

Pestaña de KPIs nativos

Ese KPI nativo cuenta todos los objetos de la plataforma: canales de video, pero también sensores, puertas, candados, lectoras y motores de video, todos mezclados en la misma dona. No admite ninguna configuración: ni filtro por tipo de objeto, ni filtro por dominio, ni título propio.

Para contar solo canales de video, y para poder acotarlos por dominio, hay que crear un KPI personalizado. Eso es lo que hacemos a continuación.

En la barra superior del panel, presiona Add. Aparece un widget vacío en la grilla. Haz clic sobre él, sobre el texto Select Widget.

Se abre el catálogo de widgets. Escribe KPI en el buscador y selecciona la tarjeta KPI (Key Performance Indicator).

Dentro del widget KPI verás cuatro pestañas. Abre Kpi perzonalized, que da paso a un asistente de cuatro etapas: Basics, Chart type, Data y Review.

Paso 3: Nombrar el indicador¶

En Basics, escribe un nombre en KPI name. Este nombre es el que verás luego en la lista de KPIs guardados y como título del widget, así que conviene que sea explícito: Offline video channels.

Paso Basics del asistente

Continúa con Next.

Paso 4: Elegir la visualización¶

En Chart type, elige Big number (Single highlighted metric). Es el formato adecuado para este caso: una sola cifra, grande y legible desde lejos, que es exactamente lo que se quiere de un indicador de canales caídos.

Paso Chart type del asistente

TIP Los demás formatos (Pie, Donut, Bar, Line…) tienen sentido cuando un KPI compara varios elementos entre sí. Si más adelante quieres comparar cuántos canales están caídos en cada dominio, agrega un elemento de datos por dominio y elige Bar en lugar de Big number.

Paso 5: Definir la fuente de datos¶

Este es el paso que hace el trabajo. En Data, presiona Add item: cada item es un valor que el KPI mostrará.

Paso Data con un elemento agregado

Escribe una etiqueta en Label —por ejemplo Offline channels— y presiona Configure para abrir el panel lateral Configure data source.

Ahí, la primera decisión es de dónde salen los datos. Deja seleccionada la primera opción, Object count (cantidad de objetos), y completa los campos así:

Campo	Valor	Qué hace
Domain (optional)	(vacío)	Cuenta en todos los dominios. Es la lectura global.
Object type (optional)	`video_channel`	Restringe el conteo a los canales de video. Es un campo de etiquetas: escribe el valor y confírmalo con Enter.
Filter by property (optional)	`offline` — equals	La propiedad de estado que indica si el canal perdió la conexión.
Value to match	`true`	Solo cuenta los canales cuya propiedad `offline` vale `true`, es decir, los caídos.
Value to show	Current value (latest)	Muestra el valor más reciente, no un promedio del rango.

Fuente de datos configurada para el conteo global

Debajo del elemento, el asistente resume en una frase lo que acabas de armar: Count of objects where offline equals true of type video_channel. Si esa frase describe lo que buscas, la configuración es correcta.

Cierra el panel con Done.

Paso 6: Acotar por dominio¶

Para que el indicador cuente solo los canales de una parte de la instalación, vuelve a abrir Configure y despliega Domain (optional).

Los dominios de canales de video siguen el patrón marca_dispositivo.video_channel, de modo que basta escribir video en el buscador para verlos todos:

Dominios de canales de video en el selector

Elige uno o varios. El campo admite selección múltiple, así que puedes agrupar, por ejemplo, todos los NVR de una sede.

Fuente de datos acotada a un dominio

El resumen del elemento refleja ahora el alcance: …of type video_channel in domains: dahua_dolynk_cctv.video_channel.stream.

INFO El campo vacío es el modo global; no existe una opción "Todos" que haya que marcar. Lo dice la propia ayuda del campo: Leave empty to count across all domains, or pick one or more to limit the count.

Consulta Dominios para entender cómo se construyen y qué agrupan.

Paso 7: Colorear el número según su valor¶

Un 0 y un 14 no significan lo mismo, y el widget puede decirlo con el color. En el bloque Color thresholds, el Base color es el color normal del número; con Add threshold agregas un valor a partir del cual el número cambia de color.

Bloque de umbrales de color

Un esquema razonable para canales caídos: base en verde, un umbral en 1 en ámbar (hay al menos un canal caído) y otro en 10 en rojo (varios canales caídos a la vez, algo que merece atención inmediata).

El número toma el color del umbral más alto que alcanza: con este esquema, un 0 se ve verde, un 3 en ámbar y un 12 en rojo.

Paso 8: Revisar, guardar y colocar¶

En Review verás el resumen del KPI: nombre, tipo de gráfico y el detalle de cada elemento. Confirma con Save KPI.

Paso Review del asistente

El KPI queda guardado y aparece en la pestaña Kpi list, desde donde puedes reutilizarlo en otros paneles, editarlo o eliminarlo. Haz clic sobre su tarjeta para colocarlo en el widget vacío.

Repitiendo el proceso puedes tener, uno al lado del otro, el indicador global y uno por cada sede que te interese vigilar.

Rango de tiempo y frecuencia de actualización¶

El control con forma de reloj, en la esquina del widget, gobierna la ventana de tiempo. No se configura en el asistente sino en el widget ya colocado, y la elección se recuerda para ese KPI.

Panel de rango de tiempo y refresco

Control	Para qué sirve
Relative time ranges	Ventana móvil: Last 5 minutes, Last Hour, Last 6 hours… Es la opción habitual.
Absolute time range	Ventana fija entre dos fechas, útil para revisar un incidente pasado.
Refresh every (minutes)	Cada cuántos minutos el widget vuelve a consultar. Por defecto, 5.

TIP Para un tablero de operación en vivo, baja Refresh every a 1. Un indicador de canales caídos que se actualiza cada 5 minutos puede tardar ese tiempo en enterarse de una caída.

Cómo leer el número¶

El conteo se calcula a partir de las propiedades de estado que los canales reportan a la plataforma: se cuentan los objetos video_channel cuya propiedad offline vale true. Conviene tener presentes dos cosas al interpretarlo.

Un canal que nunca reportó su estado no entra en la cuenta. El indicador se apoya en el historial de estados de cada objeto; un canal recién integrado, o uno cuyo driver no publica la propiedad offline, no será contabilizado aunque esté caído. Por eso el número del KPI conviene contrastarlo, al menos una vez tras configurarlo, con lo que muestra el árbol del panel, donde el estado de cada dispositivo se ve caso por caso.

Un 0 no siempre significa "todo en línea". Si la consulta al servidor falla o expira, el widget muestra 0 sin señalar el error. Ante un cero sostenido en una instalación grande, refresca el widget con el botón de recarga para confirmar que el dato es real.

NOTA La propiedad offline está documentada como parte del estado del tipo de objeto Video Channel, junto con el resto de estados que un canal puede reportar.

Buenas prácticas¶

Empieza por el global y luego desagrega. Un solo indicador con el total te dice si hay un problema; los indicadores por dominio te dicen dónde. Tener ambos en el panel es lo que convierte el número en algo accionable.
Nombra los KPIs por lo que vigilan, no por cómo se calculan. Offline channels — North Building se entiende de inmediato; KPI object_count offline no.
Un dominio por marca de equipo. Como los dominios incluyen la marca del dispositivo (hikvision_nvr.video_channel, dahua_nvr.video_channel), un indicador por dominio te dice si los canales caídos se concentran en los equipos de un fabricante o están repartidos entre todos, lo que orienta por dónde empezar a buscar.
El KPI observa; la automatización reacciona. Para enterarte de una caída sin mirar el panel, complementa el indicador con una regla sobre el estado del canal. Consulta Tu primera automatización.