T3.2: Uses Visual Trace

Concepto Fundamental

El Session ID es un concepto fundamental en InterSystems HealthConnect que vincula mensajes relacionados juntos a lo largo de su ciclo de vida de procesamiento. Entender Session ID es esencial para el uso efectivo de Visual Trace e investigación de mensajes.

Ubicación de Almacenamiento

Session ID se almacena en el encabezado de mensaje (Ens.MessageHeader), no en el cuerpo del mensaje. Cuando el primer mensaje en un flujo de procesamiento entra a la production, IRIS le asigna un Message ID único. Este Message ID se convierte en el Session ID para ese mensaje inicial y todos los mensajes subsiguientes generados durante su procesamiento.

Herencia de Session ID

Por ejemplo, cuando un Business Service recibe un mensaje HL7 ADT y lo reenvía a un Message Router, el router crea nuevos mensajes para enviar a múltiples Business Operations. Todos estos mensajes reciben el mismo Session ID que el mensaje original, aunque cada uno tiene su propio Message ID único. Esto permite a Visual Trace agrupar todos los mensajes relacionados juntos, mostrando el flujo de procesamiento completo en una sola vista.

Propagación a Través de Límites

El Session ID permanece constante a través de intercambios de mensajes síncronos y asíncronos, a través de transformaciones y a través de límites de componentes. Ya sea que un Business Process llame a un Business Operation síncronamente o envíe una solicitud asíncrona, el Session ID se propaga a través de toda la cadena de mensajes.

Uso en Resolución de Problemas

Al resolver problemas, puede identificar el Session ID viendo cualquier encabezado de mensaje en Message Viewer o Visual Trace. Una vez que tiene el Session ID, puede abrir Visual Trace para esa sesión para ver todos los mensajes relacionados y su secuencia de procesamiento. Esto es particularmente valioso al investigar escenarios de enrutamiento complejos o rastrear cómo un solo mensaje entrante resultó en múltiples mensajes salientes.

Diseño Bidimensional

Visual Trace presenta flujo de mensajes usando un diseño bidimensional que codifica tanto información temporal como espacial. Dominar este diseño es esencial para resolución de problemas rápida y entender patrones de procesamiento de mensajes.

Eje Vertical: Tiempo

El eje vertical representa tiempo, con mensajes y eventos apareciendo de arriba hacia abajo en orden cronológico. El primer mensaje aparece en la parte superior, y los pasos de procesamiento subsiguientes caen en cascada hacia abajo. Este ordenamiento cronológico facilita seguir la secuencia de operaciones e identificar dónde ocurrieron retrasos de procesamiento o errores.

Eje Horizontal: Componentes

El eje horizontal representa límites de componentes, con cada componente de production ocupando una columna vertical. Los mensajes fluyen entre estas columnas a medida que se mueven desde Business Services a través de Business Processes hasta Business Operations. Este diseño espacial proporciona retroalimentación visual instantánea sobre qué componentes estuvieron involucrados en el procesamiento y la dirección del flujo de mensajes.

Tipos de Íconos

Los íconos que aparecen en la columna de cada componente representan diferentes tipos de eventos. Los íconos de mensaje muestran creación, transmisión y recepción de mensajes. Los íconos de event log (apareciendo como íconos circulares pequeños) representan eventos registrados como errores, advertencias o mensajes informativos. Los íconos de rule log aparecen como íconos verdes numerados cuando se ejecutan reglas de enrutamiento.

Elementos Clicables

Cada ícono es clicable, proporcionando información detallada cuando se selecciona. Hacer clic en un ícono de mensaje muestra el encabezado, body y contenidos del mensaje en pestañas debajo del trace. Hacer clic en un ícono de evento muestra el texto del evento, timestamp y severidad. Hacer clic en un ícono de ejecución de regla muestra qué regla fue evaluada y qué cláusula when coincidió.

Patrones Visuales

El diseño del trace hace que ciertos patrones sean inmediatamente obvios: las llamadas síncronas aparecen como pares de flechas de solicitud-respuesta, los mensajes asíncronos muestran una sola flecha sin respuesta inmediata, y los escenarios de enrutamiento complejos se muestran como un mensaje dividiéndose en múltiples mensajes downstream.

Propósito de Codificación de Colores

Visual Trace usa codificación de colores para distinguir entre diferentes patrones de comunicación de mensajes, habilitando identificación rápida de procesamiento síncrono versus asíncrono y posibles problemas de temporización.

Mensajes Síncronos

Los mensajes síncronos aparecen como pares de flechas de colores conectando dos componentes. La flecha de solicitud fluye desde el componente llamante al componente llamado, y una flecha de respuesta fluye de vuelta. Estas flechas comparten colores coordinados, haciendo que el emparejamiento solicitud-respuesta sea visualmente obvio. La comunicación síncrona indica que el componente llamante espera la respuesta antes de continuar el procesamiento.

Mensajes Asíncronos

Los mensajes asíncronos aparecen como flechas de color únicas desde el remitente al receptor sin flecha de respuesta inmediata. Esto indica que el remitente despachó el mensaje y continuó el procesamiento sin esperar una respuesta. Algunos mensajes asíncronos pueden generar respuestas más tarde, que aparecen más abajo en la línea de tiempo del trace, pero no hay emparejamiento visual entre la solicitud y la respuesta retrasada.

Mensajes de Un Solo Sentido

Los mensajes de un solo sentido representan comunicación de disparar y olvidar donde no se espera o es posible ninguna respuesta. Estos típicamente aparecen como flechas únicas a Business Operations que realizan acciones sin retornar información de estado.

Mensajes Grises (Tardíos)

Los mensajes grises indican respuestas tardías que llegaron después de que el componente llamante dejó de esperar. Esto comúnmente ocurre en dos escenarios: Primero, cuando un timeout expira antes de que llegue una respuesta síncrona, el componente llamante deja de esperar. Si la respuesta eventualmente llega, aparece en gris para indicar que fue ignorada. Segundo, cuando un Business Process hace una llamada asíncrona pero no ejecuta una operación de respuesta síncrona correspondiente, cualquier respuesta aparece en gris porque el proceso no está esperándola.

Beneficios de Resolución de Problemas

Entender la codificación de colores acelera la resolución de problemas haciendo que problemas de temporización, patrones de comunicación y respuestas tardías inesperadas sean inmediatamente visibles sin requerir examen detallado de mensajes.

Descripción General de Íconos

Visual Trace muestra múltiples tipos de íconos que representan diferentes aspectos del procesamiento de mensajes. Entender qué representa cada tipo de ícono y cómo interpretar su secuencia es esencial para resolución efectiva de problemas.

Íconos de Mensaje

Los íconos de mensaje típicamente aparecen como símbolos de sobre o flechas. Estos representan objetos de mensaje reales fluyendo entre componentes. Cuando ve un ícono de mensaje en la columna de un componente, indica que ese componente creó, recibió o procesó ese mensaje. La dirección de la flecha muestra el flujo de mensajes, facilitando rastrear cómo se mueven los datos a través de la production.

Íconos de Event Log

Los íconos de event log aparecen como íconos circulares pequeños dentro de columnas de componentes. Estos representan entradas en el Event Log, incluyendo errores, advertencias, mensajes informativos y declaraciones de trace. El color y estilo del ícono indican la severidad del evento: rojo para errores, amarillo para advertencias, azul para mensajes informativos y otros colores para eventos de trace y assert. Hacer clic en un ícono de evento muestra el texto completo del evento, permitiéndole ver mensajes de error, stack traces o detalles informativos sin dejar Visual Trace.

Íconos de Rule Log

Los íconos de rule log son círculos verdes numerados distintivos que aparecen cuando se ejecuta una regla de enrutamiento o regla de decisión. El número dentro del ícono indica qué ejecución representa dentro de la sesión. Cuando múltiples decisiones de enrutamiento ocurren en una sesión, cada una recibe un número secuencial, facilitando identificar el orden de evaluaciones de reglas. Hacer clic en un ícono de rule log muestra información detallada de ejecución, incluyendo qué regla específica en el conjunto coincidió y qué cláusula when se activó.

Secuencia de Íconos

La secuencia de íconos dentro de la columna de un componente muestra el orden de operaciones dentro de ese componente. Por ejemplo, podría ver un ícono de mensaje (mensaje recibido), seguido de un ícono de rule log (regla de enrutamiento evaluada), seguido de múltiples íconos de mensaje (mensajes enrutados enviados a destinos). Esta secuencia cuenta la historia completa de lo que hizo el componente y en qué orden.

Interpretación de Contexto

El contexto de íconos es crucial. Un ícono de error en un Business Operation sugiere un problema de conexión a sistema externo, mientras que un error en un Business Process podría indicar un problema de transformación o lógica. Leer íconos en su contexto de componente acelera la identificación de causa raíz.

Descripción General de Pestañas

Cuando selecciona un mensaje en Visual Trace, aparecen tres pestañas debajo del diagrama de trace, cada una proporcionando diferentes perspectivas sobre los datos del mensaje. Entender qué información contiene cada pestaña y cuándo usar cada una es esencial para resolución eficiente de problemas.

Pestaña Header

La pestaña Header muestra las propiedades de encabezado de mensaje (Ens.MessageHeader) que IRIS crea automáticamente para cada mensaje. Esto incluye Session ID, Message ID, TimeCreated, TimeProcessed, nombre de configuración Source, nombre de configuración Target, Status, ErrorStatus y otros metadatos. El encabezado no contiene el contenido real del mensaje; contiene información sobre el ciclo de vida y enrutamiento del mensaje. Al investigar problemas de flujo de mensajes, la pestaña Header muestra exactamente de dónde vino el mensaje (Source) y hacia dónde iba (Target), facilitando verificar el comportamiento de enrutamiento.

Pestaña Body

La pestaña Body muestra el contenido del cuerpo del mensaje en su forma sin procesar. Para mensajes HL7, esto muestra el mensaje completo como un flujo de texto con separadores de segmento. Para clases de business message personalizadas, muestra los valores de propiedad. La pestaña Body es útil cuando necesita ver exactamente qué datos fueron transmitidos, incluyendo cualquier formato o caracteres especiales.

Pestaña Contents

La pestaña Contents es específicamente valiosa para mensajes HL7 (EnsLib.HL7.Message). Presenta la estructura HL7 parseada en una vista de árbol jerárquico, mostrando segmentos, campos, componentes y subcomponentes. Puede expandir segmentos como PID o PV1 para ver campos individuales, y expandir más campos repetitivos para ver múltiples ocurrencias. Esta vista parseada facilita mucho localizar elementos de datos específicos que escanear la sintaxis de separador de segmento en la pestaña Body. Por ejemplo, para encontrar el número de registro médico del paciente, puede navegar a PID:3(1).1 en la pestaña Contents en lugar de parsear manualmente la sintaxis de separador de segmento.

Consejos de Resolución de Problemas HL7

Al resolver problemas de HL7, use la pestaña Contents para verificar que los datos esperados existen en los campos correctos, que la asignación DocType resultó en parseo apropiado, y que las transformaciones movieron correctamente datos entre campos. La vista jerárquica hace que la navegación de campos sea intuitiva y reduce errores comparado con contar separadores de campo en el mensaje sin procesar.

Visibilidad de Alerta

Visual Trace proporciona visibilidad completa de la generación de alertas, permitiéndole identificar no solo que ocurrió una alerta, sino exactamente qué la desencadenó y qué información contiene. Esto es crucial para investigación y resolución efectivas de alertas.

Alert on Error

Las alertas generadas por la configuración "Alert on Error" aparecen en Visual Trace inmediatamente después de que ocurre el error. Verá un ícono de evento de error en el componente que experimentó el problema, seguido de un ícono de mensaje representando un Ens.AlertRequest fluyendo al componente Ens.Alert. Al hacer clic en el ícono de evento de error, puede ver el texto de error y stack trace. Al hacer clic en el mensaje Ens.AlertRequest, puede ver cómo ese error fue empaquetado en la alerta, incluyendo texto de alerta, nombre de componente de origen y Session ID asociado.

Alert on Bad Message

"Alert on Bad Message" funciona de manera similar pero se activa específicamente en fallas de validación en Message Routers. Cuando un mensaje HL7 falla validación, verá el mensaje enrutarse al Bad Message Handler (si está configurado) y simultáneamente verá un Ens.AlertRequest fluir a Ens.Alert. El body de la alerta contiene detalles sobre la falla de validación, incluyendo qué reglas de validación fallaron e información sobre el mensaje inválido.

Alertas Personalizadas (SendAlert)

Las alertas personalizadas creadas usando la acción SendAlert en lógica de Business Process aparecen como mensajes Ens.AlertRequest explícitos originándose desde el Business Process. Estos son distinguibles de alertas automáticas porque ocurren en puntos específicos en la lógica del proceso donde el desarrollador colocó la acción SendAlert. El texto de alerta para alertas personalizadas es definido por el desarrollador, por lo que puede proporcionar contexto específico sobre la condición de negocio que activó la alerta.

Convergencia de Alerta e Investigación

Todos los tipos de alerta convergen en el componente Ens.Alert, haciendo de Visual Trace la ubicación central para entender el flujo de alertas. Al examinar el body del mensaje Ens.AlertRequest, puede ver AlertText, SourceConfigName, AlertTime y SessionId asociado. Esta información le permite navegar desde la alerta de vuelta a la sesión originante para investigar la causa raíz.

Entender patrones de alerta en Visual Trace ayuda a identificar si las alertas representan errores únicos, problemas recurrentes con mensajes específicos o problemas sistémicos que requieren cambios de configuración.

Descripción General de Depuración de Configuración

Visual Trace sobresale en identificar problemas de configuración de production mostrando exactamente dónde falla el procesamiento de mensajes y qué mensajes de error se generan. Entender patrones comunes de problemas de configuración acelera la resolución de problemas.

TargetConfigNames Faltantes

Los TargetConfigNames faltantes se manifiestan en Visual Trace como mensajes que llegan a un Message Router pero no generan ningún mensaje saliente a Business Operations. Cuando examina la ejecución de regla de enrutamiento (ícono verde numerado), los detalles muestran que ninguna regla de enrutamiento coincidió, o la regla coincidió pero no retornó ningún target. Esto típicamente indica constraints de regla de enrutamiento que no coinciden con las propiedades de mensaje entrante, o reglas que no han sido actualizadas después de cambios de production. Verifique el campo Reason del rule log para ver qué cláusulas when fueron evaluadas y por qué no coincidieron.

Message Schema Category Faltante

Message Schema Category faltante en Business Services HL7 causa fallas de validación y parseo. En Visual Trace, verá un ícono de evento de error inmediatamente después de que el service recibe el mensaje, con un error indicando que IRIS no pudo determinar la estructura del mensaje. La configuración Message Schema Category le dice al Business Service qué versión de schema HL7 usar. Sin esta configuración, IRIS no puede parsear o validar mensajes entrantes. La solución es establecer Message Schema Category al schema apropiado (por ejemplo, "2.5" para mensajes HL7 v2.5).

Discordancias de Constraint de Regla de Enrutamiento

Las discordancias de constraint de regla de enrutamiento aparecen cuando los mensajes alcanzan el Message Router pero no coinciden con las reglas de enrutamiento esperadas. El rule log de ejecución muestra qué reglas fueron evaluadas pero muestra que las cláusulas when fallaron en coincidir. Las causas comunes incluyen constraints Source que referencian nombres de Business Service no existentes, constraints de ruta de campo usando rutas de propiedad incorrectas, o constraints de valor esperando datos que no están presentes en el mensaje. Al examinar la pestaña Contents del mensaje junto con los detalles de rule log, puede identificar discrepancias entre lo que la regla espera y lo que el mensaje contiene.

DocType Faltante

DocType faltante causa múltiples problemas visibles en Visual Trace. Los mensajes sin DocType no pueden validarse (automáticamente enrutan a Bad Message Handler si la validación está habilitada), no pueden parsearse en la estructura de schema apropiada (la pestaña Contents muestra segmentos genéricos en lugar de estructura específica de schema), y pueden fallar reglas de enrutamiento que acceden campos específicos de schema. Los mensajes de error explícitamente indican "DocType not set" o similar. La solución es asegurar que el Business Service asigna DocType usando la configuración DocType o DocSchemaCategory con expresión DocType.

Eficiencia de Resolución de Problemas

Visual Trace acelera la resolución de problemas de configuración mostrando no solo que ocurrió un error, sino el componente exacto, el mensaje exacto y el texto de error exacto, permitiéndole ir directamente a la configuración relevante.