T3.1: Identifies Troubleshooting Tools

Descripción General

La Página de Production Configuration es la interfaz principal de resolución de problemas en InterSystems HealthConnect. Proporciona visibilidad completa de la salud de la production y sirve como el hub de navegación para todas las demás herramientas de resolución de problemas. Entender esta página es esencial ya que representa el primer punto de contacto al investigar problemas de production.

Relación de Production y Namespace

La página muestra todos los componentes para el namespace actual, respetando la relación uno a uno entre production y namespace. Los botones Start/Stop controlan el estado completo de la production, afectando todos los componentes habilitados. El botón Recover maneja situaciones especiales donde la production se detuvo incorrectamente, gestionando mensajes que estaban pendientes durante un cierre no limpio.

Filtro de Categoría

El filtro Category es crítico para gestionar productions complejas con muchos componentes. Configurarlo a "All" muestra Business Services, Business Processes y Business Operations juntos. Para resolución de problemas enfocada, puede filtrar para ver solo tipos de componentes específicos, reduciendo el desorden visual en productions grandes.

Pestañas Conscientes de Contexto

Cuando selecciona un componente o Production Settings, todas las pestañas en el lado derecho (Settings, Queue, Log, Messages, Jobs, Actions) se vuelven conscientes de contexto, mostrando información filtrada para ese componente específico. Navegar a páginas detalladas desde estas pestañas mantiene este filtrado, proporcionando vistas prefiltradas que aceleran la resolución de problemas.

Sistema de Retroalimentación Visual

El sistema de codificación de colores proporciona retroalimentación visual instantánea sobre la salud de componentes sin requerir investigación detallada. Este lenguaje visual está estandarizado en todas las productions de HealthConnect y debería memorizarse para resolución de problemas rápida.

Estados Verdes

Verde oscuro indica operación normal con procesamiento activo de mensajes. Este es el estado esperado para la mayoría de los componentes activos. Verde claro aparece para componentes que están ejecutándose pero no procesando mensajes actualmente, frecuentemente porque carecen de adapter (algunos Business Processes operan de esta manera).

Estados de Error y Reintento

Rojo significa errores que requieren atención inmediata. Estos pueden incluir fallas de validación de mensajes, incapacidad para conectar a sistemas remotos, o errores de procesamiento dentro de la lógica de componentes. Cuando ve rojo, verifique primero la pestaña Log del componente para detalles de error.

Púrpura indica un estado de reintento donde el componente está intentando entregar un mensaje pero ha fallado al menos una vez. El componente está siguiendo su configuración de reintento, intentando automáticamente la reentrega. Esto puede resolverse solo o puede indicar un problema persistente de conectividad o configuración.

Estados de Advertencia y Deshabilitado

Amarillo advierte que un componente ha excedido su timeout de inactividad sin procesar mensajes. Para Business Services que esperan entrada regular, esto puede indicar que el sistema remoto ha dejado de enviar datos, representando una posible falla de integración.

Gris simplemente muestra componentes deshabilitados que no están participando en el procesamiento de mensajes. Estos están intencionalmente excluidos del flujo de production.

Descripción General de Estados

Las productions operan en cuatro estados distintos, dos de los cuales son normales y dos que indican problemas que requieren intervención. Entender estos estados es crítico para mantener la confiabilidad de la production.

Estados Normales

Running es el estado operacional normal donde la production está procesando mensajes. Stopped indica un cierre limpio donde todos los mensajes completaron el procesamiento y las colas están vacías. Estos dos estados representan el ciclo de vida normal de la production.

Estado Suspended

Suspended aparece cuando un operador detiene manualmente la production, pero mensajes síncronos todavía están esperando respuestas. InterSystems IRIS tiene un período de timeout de cierre durante el cual espera que las operaciones pendientes se completen. Los mensajes que no se completan dentro de esta ventana se marcan como suspendidos. Cuando reinicia la production, IRIS procesa automáticamente estos mensajes suspendidos. Para mantenimiento planificado, es mejor práctica reiniciar y detener limpiamente la production de nuevo para alcanzar el estado Stopped en lugar de dejarla Suspended.

Estado Troubled

El estado Troubled es más serio e indica que la production se detuvo incorrectamente, típicamente debido a un crash de componente o falla del sistema. Esto requiere investigación de registros del sistema para identificar la causa raíz. El botón Recover puede reiniciar componentes fallidos y manejar mensajes pendientes, pero debería entender por qué ocurrió el crash para prevenir recurrencia. El estado Troubled es relativamente raro en productions estables y siempre justifica investigación exhaustiva.

Propósito y Funcionalidad

La configuración Archive I/O proporciona visibilidad granular de los datos reales transmitidos y recibidos por Business Services y Business Operations. Cuando está habilitada, esta configuración agrega columnas I/O al Visual Trace, permitiéndole inspeccionar la entrada y salida sin procesar para cada intercambio de mensajes.

Depuración de ACK HL7

Para integraciones HL7, Archive I/O es particularmente valiosa al depurar problemas de acknowledgment. Sin esta configuración, Visual Trace muestra el flujo principal de mensajes HL7 pero puede no mostrar mensajes ACK. Con Archive I/O habilitado en el Business Operation, puede ver tanto el mensaje HL7 enviado como el ACK recibido en columnas I/O separadas, facilitando verificar que los acknowledgments están siendo recibidos y procesados correctamente.

Uso en Business Service

En Business Services, Archive I/O registra la entrada exacta recibida de sistemas externos antes del parseo. Esto es invaluable al investigar fallas de parseo o cuando sospecha que el formato de datos entrantes no coincide con las expectativas. Puede comparar la entrada sin procesar contra la definición DocType para identificar discrepancias.

Consideraciones de Rendimiento

La configuración se aplica a nivel de componente, por lo que puede habilitarla selectivamente para componentes que experimentan problemas en lugar de para toda la production. Este enfoque dirigido minimiza el impacto en el rendimiento mientras proporciona información de depuración necesaria. En entornos de producción de alto volumen, considere las implicaciones de almacenamiento de registrar toda la I/O y habilítela solo durante resolución activa de problemas.

Nombre de Componente Reservado

El nombre de componente Ens.Alert está reservado y tiene significado especial en InterSystems HealthConnect. Cuando cualquier componente en la production genera una alerta, IRIS automáticamente enruta el mensaje Ens.AlertRequest resultante a un componente llamado "Ens.Alert". Este nombre está fijado por el framework y no puede cambiarse.

Flexibilidad de Implementación

Mientras el nombre está fijo, la implementación es completamente flexible. Puede implementar Ens.Alert como un Message Router que usa reglas de enrutamiento para distribuir diferentes tipos de alerta a diferentes destinos basándose en severidad de error, componente de origen o contenido de mensaje de error. Alternativamente, puede implementarlo como un Business Operation que maneja directamente alertas enviando emails, escribiendo a archivos de registro o integrándose con sistemas de monitoreo externos.

Arquitecturas de Alerta Complejas

Para manejo complejo de alertas, podría implementar Ens.Alert como un Message Router que envía alertas a múltiples Business Operations: una para notificaciones de email, una para registro a un sistema de monitoreo y una para archivar errores críticos a una base de datos. Esta arquitectura proporciona enrutamiento centralizado de alertas con manejo distribuido.

Evitando Bucles Infinitos

La regla de configuración más crítica para manejo de alertas es nunca habilitar "Alert on Error" en Ens.Alert o cualquier componente downstream que procese alertas. Si ocurre un error durante el procesamiento de alertas y "Alert on Error" está habilitado, el sistema genera otra alerta, que enruta de vuelta a Ens.Alert, potencialmente creando un bucle infinito. Siempre deshabilite "Alert on Error" en toda la cadena de manejo de alertas.

Propósito y Disponibilidad

El Bad Message Handler proporciona un mecanismo para manejar con gracia mensajes HL7 que fallan validación en lugar de generar errores que detienen el procesamiento. Esta configuración existe solo en componentes HL7 Message Router (EnsLib.HL7.MsgRouter.RoutingEngine) y requiere que la validación esté habilitada.

Pasos de Implementación

Para implementar Bad Message Handler, primero debe habilitar validación en el Message Router estableciendo el parámetro Validation a "1", "dm", "z" u otro valor no-cero. Luego cree un componente de destino (típicamente un Business Operation) que reciba mensajes inválidos. En las configuraciones del Message Router, establezca el parámetro Bad Message Handler al nombre exacto de este componente de destino.

Manejando Mensajes Inválidos

El componente de destino recibe el EnsLib.HL7.Message completo aunque falló validación. Las estrategias comunes de manejo incluyen escribir mensajes inválidos a disco para revisión manual, registrarlos a una base de datos con detalles de error, o reenviarlos a una cola de procesamiento manual. Esto previene pérdida de datos mientras asegura que los mensajes inválidos no interrumpan el procesamiento normal.

Requisito de DocType

Un punto crítico para preparación de examen: los mensajes que llegan al Message Router sin un DocType especificado no pueden validarse porque IRIS no sabe contra qué schema validar. Estos mensajes automáticamente se enrutan al Bad Message Handler. El DocType debería asignarse en el Business Service antes de enviar el mensaje al Message Router.

Integración de Alerta

La configuración "Alert on Bad Message" complementa Bad Message Handler generando un Ens.AlertRequest al componente Ens.Alert cada vez que falla la validación. Esto proporciona notificación en tiempo real de problemas de validación mientras el Bad Message Handler asegura que el mensaje se preserve para investigación.

Descripción General

HealthConnect proporciona múltiples páginas especializadas para monitorear diferentes aspectos de operación de production. Cada una sirve un propósito distinto en el flujo de trabajo de resolución de problemas.

Production Monitor

La página Production Monitor proporciona una vista de dashboard de salud de production, mostrando componentes activos, tasas de mensajes, profundidades de cola y conteos de errores. Esta es típicamente la primera página que los administradores verifican para evaluar la salud general de production e identificar componentes que requieren atención.

Página Queues

La página Queues muestra mensajes pendientes organizados por componente, mostrando cuántos mensajes están esperando procesamiento en cada cola. Profundidades altas de cola pueden indicar cuellos de botella de rendimiento, sistemas externos lentos o componentes que se han retrasado en el procesamiento. La página le permite profundizar en colas específicas para ver mensajes individuales y sus edades.

Página Jobs

La página Jobs muestra los procesos de IRIS ejecutándose para cada componente. Esto es valioso para entender el paralelismo de componentes, identificar procesos colgados y diagnosticar problemas de rendimiento. Para componentes configurados con tamaños de pool mayores que uno, verá múltiples procesos de job. Comparar jobs activos contra el tamaño de pool configurado ayuda a identificar si los componentes están utilizando completamente la capacidad disponible.

Página Messages

La página Messages proporciona historial completo de mensajes para componentes, permitiéndole filtrar, buscar y ver detalles de mensajes. Esto es esencial para investigar problemas de procesamiento de mensajes específicos o entender el comportamiento de componentes a lo largo del tiempo.

Filtrado Consciente de Contexto

Una característica clave de todas estas páginas es el filtrado consciente de contexto. Cuando navega a cualquiera de estas páginas desde la página Production Configuration con un componente específico seleccionado, la página de destino automáticamente filtra para mostrar solo información para ese componente. Este prefiltrado acelera significativamente la resolución de problemas al eliminar la necesidad de configurar filtros manualmente.

Propósito

El testing service proporciona un mecanismo poderoso para probar reglas de enrutamiento y procesamiento de mensajes sin requerir conectividad a sistemas externos. Esta herramienta es particularmente valiosa durante fases de desarrollo, testing y resolución de problemas.

Habilitando el Service

Por defecto, el testing service está deshabilitado en entornos de producción para prevenir que operadores envíen inadvertidamente mensajes de prueba que podrían desencadenar acciones en sistemas externos conectados. Antes de usar la herramienta de testing, debe habilitarla en Production Settings. Este paso de habilitación deliberado asegura que está consciente de que está trabajando en modo de prueba.

Proceso de Testing

Para probar una regla de enrutamiento usando la herramienta de testing, navegue a la página de testing y seleccione el Business Process o Business Operation de destino. En el campo "document content", pegue el mensaje HL7 completo que desea probar. Sin embargo, pegar solo el contenido del mensaje es insuficiente para testing apropiado.

Campos Requeridos: DocType

También debe especificar el DocType en el campo designado. El DocType habilita parseo y validación apropiados del mensaje HL7 contra el schema. Sin el DocType correcto, el mensaje puede fallar validación o ser parseado incorrectamente, llevando a resultados de prueba engañosos.

Campos Requeridos: Source

Adicionalmente, si sus reglas de enrutamiento incluyen constraints basados en el componente de origen (usando la propiedad Source), debe especificar el campo Source con el nombre del Business Service que normalmente enviaría el mensaje. Sin esto, las reglas de enrutamiento con constraints Source no coincidirán, y su mensaje de prueba no se enrutará como se espera.

Visibilidad de Sesión de Prueba

La herramienta de testing crea sesiones de prueba reales que aparecen en Visual Trace y Message Viewer. Puede usar todas las herramientas estándar de resolución de problemas para analizar el procesamiento de mensajes de prueba, facilitando validar reglas de enrutamiento y lógica de transformación.