T3.4: Uses Logs and Debugging

Propósito

El Business Rule Log proporciona un historial completo de todas las ejecuciones de reglas de enrutamiento y reglas de decisión en toda la producción. Este log es invaluable para comprender por qué los mensajes se enrutaron a destinos específicos o por qué se tomaron ciertas decisiones de negocio.

Contenido de las Entradas del Log

Cada entrada en el Business Rule Log representa una ejecución de regla, mostrando cuándo se ejecutó la regla, qué componente la invocó, qué conjunto de reglas se utilizó y qué resultado devolvió la regla. Para las reglas de enrutamiento, el resultado muestra la lista de nombres de configuración de destino a los que se enrutó el mensaje. Para las reglas de decisión, muestra los valores de decisión devueltos. Este registro histórico le permite investigar el comportamiento de enrutamiento sin reproducir el flujo de mensajes original.

Navegación a Visual Trace

El log proporciona navegación directa a la sesión de mensaje asociada. Cada entrada del log de reglas incluye un enlace a la sesión donde se ejecutó la regla. Al hacer clic en este enlace se abre Visual Trace para esa sesión, mostrando la ejecución de la regla en contexto con todos los mensajes relacionados. Esta integración entre el Business Rule Log y Visual Trace facilita comprender no solo qué decisión se tomó, sino qué mensaje desencadenó la decisión y qué procesamiento ocurrió después.

Capacidades de Búsqueda

Las capacidades de búsqueda dentro del Business Rule Log permiten filtrar por rango de tiempo y nombre de componente. Al investigar problemas de enrutamiento para un componente específico, puede filtrar para mostrar solo las ejecuciones de reglas del motor de enrutamiento de ese componente. El filtrado por rango de tiempo es útil cuando sabe cuándo ocurrió el problema y desea examinar las ejecuciones de reglas durante ese período.

Análisis Detallado en Visual Trace

Para un análisis detallado de ejecución de reglas, Visual Trace proporciona la vista más completa. Dentro de Visual Trace, las ejecuciones de reglas aparecen como iconos verdes numerados. Al hacer clic en estos iconos se muestra el campo Reason, que contiene información detallada de ejecución incluyendo qué regla específica del conjunto coincidió y qué cláusula when se activó. Este nivel de detalle es esencial para depurar reglas de enrutamiento complejas con múltiples cláusulas when y lógica condicional.

Valor para la Resolución de Problemas

El Business Rule Log es particularmente valioso al solucionar escenarios donde los mensajes no se enrutan como se esperaba. Al examinar el log, puede verificar que la regla de enrutamiento realmente se ejecutó (si no existe entrada en el log, el componente puede no estar configurado correctamente), confirmar qué destinos fueron seleccionados e identificar patrones en las decisiones de enrutamiento a lo largo del tiempo.

Repositorio Central

El Event Log es el repositorio central para todos los eventos de producción, proporcionando visibilidad completa de errores, advertencias, mensajes informativos y declaraciones de trace del desarrollador. Comprender la jerarquía de tipos de eventos y cómo buscar efectivamente en el log es esencial para la resolución de problemas de producción.

Eventos de Error

Los eventos de Error representan fallos de integración que requieren atención inmediata. Estos incluyen errores de procesamiento de mensajes, fallos de conectividad con sistemas externos, errores de transformación y caídas de componentes. Al solucionar problemas de producción, el Event Log filtrado para mostrar solo Errors proporciona una vista enfocada de los problemas que requieren resolución. Cada entrada de error incluye el texto del mensaje de error, el stack trace (cuando está disponible), el componente de origen y la marca de tiempo. Esta información típicamente apunta directamente a la causa raíz.

Eventos de Advertencia

Los eventos de Warning indican problemas no críticos que no detienen el procesamiento pero pueden señalar problemas. Las advertencias comunes incluyen desconexiones de conexión TCP (que pueden ser normales durante el reciclaje de conexiones), timeouts de inactividad, intentos de reintento y uso de características obsoletas. Aunque las advertencias no requieren acción inmediata como los errores, a menudo señalan condiciones que se degradan y que pueden conducir a fallos si no se abordan. Por ejemplo, el aumento en la frecuencia de advertencias de conexión puede indicar inestabilidad de red.

Eventos de Información

Los eventos de Info proporcionan contexto operacional sin indicar problemas. Estos incluyen eventos de inicio/parada de componentes, cambios de configuración, acciones manuales del operador e hitos de procesamiento normal. Los eventos de Info son valiosos para comprender la línea de tiempo de producción y correlacionar cambios operacionales con problemas. Por ejemplo, si los errores comenzaron después de un momento específico, verificar los eventos de Info para ese período de tiempo puede revelar un cambio de configuración o reinicio de componente que desencadenó los problemas.

Eventos de Trace

Los eventos de Trace son mensajes de depuración generados por el desarrollador creados usando macros $$$TRACE o declaraciones de registro similares en componentes personalizados. Estos eventos solo aparecen en el log si la configuración "Log Trace Events" del componente está habilitada. Por defecto, esta configuración está deshabilitada para prevenir el desorden del log en entornos de producción. Al depurar lógica de componentes personalizados, habilite Log Trace Events para el componente específico, reproduzca el problema, luego examine los eventos de Trace para ver el flujo de ejecución detallado. Recuerde deshabilitar Log Trace Events después de la depuración para prevenir el impacto en el rendimiento por registro excesivo.

Eventos de Assert

Los eventos de Assert representan aserciones en el código, típicamente usadas durante el desarrollo para verificar suposiciones. Como los eventos de Trace, estos son principalmente relevantes durante el desarrollo y la depuración en lugar de la operación normal de producción.

Filtrado Sensible al Contexto

Al navegar al Event Log desde la página de Configuración de Producción con un componente específico seleccionado, el log filtra automáticamente para mostrar solo eventos de ese componente. Este filtrado sensible al contexto acelera la resolución de problemas al eliminar el ruido de componentes no relacionados. Sin embargo, tenga en cuenta que este filtrado persiste incluso cuando navega directamente al Event Log desde otras páginas. Siempre verifique el filtro Source Config Name para asegurarse de que está viendo el alcance deseado de eventos.

Capacidades de Filtrado

La interfaz de búsqueda del Event Log proporciona potentes capacidades de filtrado que deben usarse efectivamente para encontrar eventos relevantes en logs potencialmente grandes. Comprender cómo funcionan e interactúan los filtros es crítico para una resolución de problemas eficiente.

Filtro Source Config Name

El filtro Source Config Name restringe los eventos a aquellos generados por un componente de producción específico. El menú desplegable lista todos los componentes de producción actuales más cualquier componente histórico que haya generado eventos registrados. Este filtro es particularmente útil al solucionar problemas específicos de un componente. Al investigar problemas de conectividad de un Business Operation, filtrar por el nombre de esa operación muestra solo sus errores y advertencias, eliminando eventos de otros componentes.

Población Automática del Filtro

Una característica importante del filtrado por Source Config Name es la población automática al navegar desde la página de Configuración de Producción. Si selecciona un componente en la producción y hace clic para ver su pestaña Log, el Event Log se abre con Source Config Name preestablecido a ese componente. Esto acelera la resolución de problemas pero puede ser confuso si olvida que el filtro está activo. Puede navegar al Event Log esperando ver todos los eventos pero ver solo los eventos de un componente debido al filtrado persistente de una navegación anterior.

Filtrado por Rango de Tiempo

El filtrado por rango de tiempo usa los parámetros StartTime y EndTime para mostrar solo eventos dentro de una ventana específica. Esto es esencial al investigar incidentes que ocurrieron en momentos conocidos. Por ejemplo, si un sistema externo estuvo no disponible de 2:00 PM a 2:15 PM, establecer el rango de tiempo a esa ventana muestra solo eventos durante la interrupción, facilitando identificar qué mensajes fallaron y qué componentes fueron afectados.

Filtrado por Tipo de Evento

El filtrado por tipo de evento permite seleccionar severidades específicas: Error, Warning, Info, Trace, Assert o All. Para la resolución de problemas inicial, filtrar a Errors proporciona una vista enfocada de los problemas. Para una investigación completa, All muestra la línea de tiempo completa de eventos incluyendo errores en contexto con advertencias y mensajes informativos. Este contexto a menudo revela que lo que parece un error repentino fue en realidad precedido por señales de advertencia visibles en el flujo completo de eventos.

Importancia del Botón Reset

El botón Reset es críticamente importante porque los filtros del Event Log persisten entre visitas a la página. Si establece Source Config Name a MyOperation y regresa al Event Log más tarde (incluso en una sesión de navegador diferente si las cookies persisten), el filtro permanece activo. Esto puede llevar a confusión donde espera ver todos los eventos pero ve solo los eventos de un componente. Siempre verifique los filtros activos cuando el Event Log muestre menos eventos de lo esperado, y use Reset para limpiar todos los filtros y ver el log completo.

Visualización de Resultados de Búsqueda

Los resultados de búsqueda se muestran con los eventos más recientes primero por defecto, lo cual es apropiado para la mayoría de los escenarios de resolución de problemas donde está investigando problemas recientes. Cada fila de evento muestra marca de tiempo, componente de origen, tipo de evento y texto abreviado del evento. Al hacer clic en una fila de evento se muestran los detalles completos incluyendo mensajes de error completos y stack traces.

Resolución de Problemas Multi-Componente

Para escenarios complejos de resolución de problemas que involucran múltiples componentes, considere buscar sin filtrado por Source Config Name pero con filtrado de rango de tiempo apropiado. Esto revela patrones de interacción entre componentes y ayuda a identificar fallos en cascada donde un error en un componente desencadena fallos en componentes posteriores.

Descripción General de la Configuración

La configuración Log Trace Events proporciona control granular sobre el registro a nivel de trace para componentes de producción individuales. Comprender cuándo y cómo usar esta configuración es importante para una depuración efectiva sin impactar el rendimiento de producción.

Cómo Funciona

Log Trace Events es una configuración a nivel de componente que se encuentra en la sección Additional Settings de cada Business Service, Business Process y Business Operation. Cuando está habilitada, las declaraciones de trace dentro del código del componente generan entradas en el Event Log. Cuando está deshabilitada, las declaraciones de trace se ejecutan pero no se crean entradas en el log. Esto permite a los desarrolladores incluir registro de trace detallado en el código que puede activarse bajo demanda sin requerir cambios de código.

Razón de la Configuración Por Defecto

La configuración está deshabilitada por defecto por buenas razones. El registro de trace puede generar volúmenes significativos de entradas de log, especialmente en componentes de alto rendimiento. En entornos de producción, este volumen de log puede impactar el rendimiento (debido a la sobrecarga de E/S al escribir entradas de log) y dificultar encontrar mensajes de error y advertencia relevantes entre la salida de trace. Por lo tanto, el registro de trace debe permanecer deshabilitado durante la operación normal.

Cuándo Habilitar

Habilite Log Trace Events cuando esté depurando activamente el comportamiento de un componente, especialmente para componentes desarrollados personalizados. Al investigar por qué un Business Process no está tomando decisiones de enrutamiento esperadas o por qué una transformación no está mapeando datos correctamente, habilite el trace para ese componente específico, reproduzca el problema, luego examine los eventos de Trace en el Event Log. La salida de trace muestra el flujo de ejecución, valores de variables y puntos de decisión dentro del código.

Limpieza Post-Depuración

Después de que la depuración esté completa y el problema resuelto, recuerde deshabilitar Log Trace Events. Dejar el trace habilitado indefinidamente degrada el rendimiento y desordena el Event Log. En entornos de producción, establezca una política de revisar las configuraciones de trace habilitadas periódicamente para asegurar que los componentes no se dejen inadvertidamente en modo de trace.

Habilitación Selectiva

Para instalaciones de HealthConnect con muchos componentes, habilitar selectivamente el trace solo para el componente bajo investigación minimiza el impacto en el rendimiento. Puede habilitar el trace para un Business Process mientras lo deja deshabilitado para los Business Services y Business Operations con los que se comunica. Este enfoque enfocado proporciona la información de depuración necesaria sin la sobrecarga de registro a nivel de sistema.

Otros Tipos de Eventos

La configuración Log Trace Events aplica solo a eventos de nivel trace. Los eventos de Error, Warning e Info siempre se registran independientemente de esta configuración. Esto asegura que los eventos críticos nunca se pierdan incluso cuando el trace está deshabilitado.

Descripción General de Capacidades de Auditoría

InterSystems IRIS incluye capacidades completas de auditoría que rastrean automáticamente eventos de producción específicos en la Audit Database. Comprender qué eventos se auditan y cómo acceder a la información de auditoría es importante para el cumplimiento, seguridad y resolución de problemas.

Los componentes de Ensemble (ahora HealthConnect/Interoperability) generan cinco tipos principales de eventos auditables. Los nombres de eventos retienen el prefijo "Ensemble" por compatibilidad histórica, aunque el producto ahora se llama HealthConnect o Interoperability.

EnsembleMessageResend

Los eventos EnsembleMessageResend se crean cada vez que un operador usa el Message Viewer para reenviar uno o más mensajes. Este registro de auditoría registra quién reenvió los mensajes, cuándo ocurrió el reenvío, qué mensajes fueron reenviados y si se usó reenvío estándar, editar y reenviar, o reenvío a nuevo destino. Esto es particularmente importante para entornos de cumplimiento donde el reprocesamiento de mensajes debe ser rastreado y justificado. Si los mensajes reenviados desencadenan acciones en sistemas externos (órdenes de laboratorio, registros de administración de medicamentos), el registro de auditoría proporciona evidencia de lo que se hizo y por quién.

EnsembleViewContents

Los eventos EnsembleViewContents rastrean cuando los operadores ven el contenido de mensajes a través del Management Portal. En entornos de atención médica que manejan PHI (Protected Health Information - Información de Salud Protegida), este registro de auditoría demuestra cumplimiento con regulaciones de privacidad al registrar quién accedió a los datos del paciente y cuándo. No toda visualización de mensajes genera eventos de auditoría; solo las acciones que muestran el contenido real del mensaje desencadenan la auditoría.

EnsembleModifyConfiguration

Los eventos EnsembleModifyConfiguration registran cambios en las configuraciones de componentes dentro de la producción. Cuando un operador modifica la dirección IP de un Business Operation, habilita Archive I/O, o cambia cualquier configuración de componente, un evento de auditoría captura el cambio, quién lo hizo y cuándo. Este registro de auditoría es invaluable al solucionar problemas relacionados con la configuración, ya que permite correlacionar problemas con cambios de configuración recientes.

EnsembleModifyDefaultSettings

Los eventos EnsembleModifyDefaultSettings rastrean específicamente los cambios en System Default Settings, que son valores predeterminados de configuración que aplican a través de las producciones. Estas configuraciones tienen impacto en toda la producción, por lo que los cambios se auditan por separado para asegurar visibilidad en las modificaciones de configuración a nivel de sistema.

EnsembleStartStop

Los eventos EnsembleStartStop registran acciones de inicio y parada de producción. Este registro de auditoría muestra quién inició o detuvo la producción y cuándo, lo cual es crítico para comprender la disponibilidad de producción y correlacionar interrupciones con acciones del operador versus fallos del sistema. Si una producción fue detenida durante un momento en que debería haber estado procesando mensajes, el evento de auditoría identifica quién la detuvo.

Propiedades de Eventos de Auditoría

Todos los eventos de auditoría incluyen el nombre de usuario de la persona que realizó la acción, la marca de tiempo y detalles específicos del evento. Los datos de auditoría se almacenan en la InterSystems Audit Database, separada de la base de datos de producción, asegurando la integridad del registro de auditoría. Los eventos de auditoría no pueden ser modificados o eliminados a través de interfaces normales, proporcionando responsabilidad resistente a manipulaciones.

Visualización de Eventos de Auditoría

Para ver eventos de auditoría, acceda a la Audit Database a través del menú System Administration del Management Portal. La interfaz de auditoría permite buscar por tipo de evento, rango de fechas, usuario y otros criterios. Al investigar problemas de producción, verificar eventos de auditoría a menudo revela que cambios de configuración o reenvíos de mensajes se correlacionan con el inicio de los problemas.

Descripción General de la Integración

La integración entre el Business Rule Log y Visual Trace proporciona visibilidad completa en la ejecución de reglas de enrutamiento y reglas de decisión. Comprender cómo acceder e interpretar los detalles de ejecución de reglas es esencial para depurar escenarios de enrutamiento complejos.

Iconos Verdes Numerados

En Visual Trace, las ejecuciones de reglas aparecen como distintivos iconos verdes con números dentro. El número indica la secuencia de ejecuciones de reglas dentro de la sesión: la primera ejecución de regla está numerada 1, la segunda es 2, y así sucesivamente. Esta numeración facilita identificar múltiples ejecuciones de reglas en sesiones donde los mensajes pasan a través de varios motores de enrutamiento o donde un único motor de enrutamiento se invoca múltiples veces.

El Campo Reason

Al hacer clic en un icono verde de ejecución de regla se muestra información detallada en el panel de detalles debajo del trace. El campo más importante es Reason, que contiene la ruta de ejecución completa a través de la regla. El campo Reason especifica qué conjunto de reglas se usó (importante cuando existen múltiples motores de enrutamiento en la producción), qué regla específica dentro del conjunto coincidió, y qué cláusula when dentro de esa regla se activó.

Por ejemplo, un Reason podría indicar: "Executed rule 'ADT_Routing', matched rule 'Route to Registration', selected when clause 'Patient is inpatient' based on condition PV1:2.1='I'". Este nivel de detalle hace inmediatamente claro por qué el mensaje se enrutó a destinos específicos y qué valores de datos impulsaron la decisión.

Resultados de Ejecución de Reglas

Los detalles de ejecución de reglas también muestran el resultado devuelto por la regla. Para reglas de enrutamiento, esta es la lista de nombres de configuración de destino a los que se envió el mensaje. Para reglas de decisión, son los valores de decisión devueltos. Comparar los destinos esperados contra los destinos reales mostrados en la ejecución de la regla ayuda a identificar desajustes de configuración o valores de datos inesperados.

Contexto de Visual Trace

Los detalles de ejecución de reglas de Visual Trace complementan el Business Rule Log al proporcionar información de ejecución en el contexto del flujo de mensajes completo. Mientras que el Business Rule Log muestra todas las ejecuciones de reglas en una lista buscable, Visual Trace muestra cada ejecución en relación con los mensajes que la desencadenaron y los mensajes que generó. Este contexto es invaluable para comprender escenarios de enrutamiento complejos donde múltiples componentes y reglas interactúan.

Flujo de Trabajo de Resolución de Problemas

Al solucionar problemas de enrutamiento, el flujo de trabajo típicamente es: identificar el mensaje problemático en Message Viewer, abrir su Visual Trace, localizar el icono de ejecución de regla, examinar el campo Reason para comprender qué decisión se tomó y por qué, y comparar contra las expectativas. Si la regla no se ejecutó en absoluto (no aparece ningún icono verde), el problema probablemente está en la configuración del componente o en el enrutamiento del mensaje antes del motor de reglas. Si la regla se ejecutó pero seleccionó destinos inesperados, el campo Reason muestra qué cláusula when coincidió, permitiéndole verificar la lógica de la regla de enrutamiento contra los datos reales del mensaje.

Herramientas Complementarias

La combinación del Business Rule Log para análisis histórico y Visual Trace para contexto de ejecución detallado proporciona capacidades completas de depuración de reglas.