Using the Logs

Viewing a Message

There are two ways to view the details of a log message:

  • To view the current log message (highlighted in green), press the Return or Enter key.
  • Click on any message to view it.

The details for the selected message are displayed in the Logs window:

The detailed version of the log message is displayed using the encoding specified by the Message Encoding list box in the LLP Listener and LLP Client components.

Note: This encoding is not used to display the list of log messages that appears when you first click the Logs tab. This encoding is only used to display the detailed version of the message.

The following table describes the icons in the log message details page and what they do. The option buttons that are displayed depend on the type of log message that you are viewing.

Button Description
Resubmit or forward this HL7 message (this icon is displayed only if the log message is of type Message). For more information, see Resubmitting Logged Messages. This button is disabled if you are not a member of the Administrators role. (See Roles for more information on roles in Iguana.)
Show all entries related to this log message. (For more information, see Viewing Related Log Messages.)
Display a direct link to this log message. (For more information, see Obtaining a Direct Link to a Logged Message.)
Download this message to a file (in text format).
The view mode in which the log message is being displayed. Click the arrow at the right of this button to display a drop-down menu that lists the available view modes. See Selecting the Log Message View Mode for more details.
Toggle line wrapping.
Mark an error. Only appears if the log message is of type Error and has not been marked. See Marking an Error for information on marking errors. This button is disabled if you are not a member of the Administrators role.
Unmark an error. Only appears if the log message is of type Error and has been marked.
Delete this log message. This button is disabled if you are not a member of the Administrators role.
Undelete a deleted log message. This button is disabled if you are not a member of the Administrators role.
Display the previous log message. If search criteria have been specified, go to the next-earliest log message that matches the criteria.
Display the next log message. If search criteria have been specified, go to the next log message that matches the criteria.

Click Close to return to the list of log messages.

Viewing Related Messages [top]

When you are viewing a log message, you can display the log messages that are related to it.

Tip: Related messages can be very useful for debugging:

  • Issues with messages that failed to process correctly, can be solved quickly by showing the related messages to identify which processing step failed.
  • If you want to identify processing steps in an unfamiliar system, simply look at related log messages for a message that processed correctly.

To view the related log messages:

  1. From Iguana, click the Logs tab.
  2. In the logs, locate the log message for which you want to view the related log messages, and click it. Detailed information on the log message is displayed:
  3. Click to view the related log messages:
  4. While you are displaying the related log messages, the Search Criteria panel is greyed out to indicate that you are viewing the log messages in context:
  5. Clicking the Bookmark Search button will create a URL for the associated messages.
  6. Click Close (in the Search Criteria panel) to return to the Logs screen.

Message View Modes [top]

You can view your message in various modes, plain text, hex, as segments etc.

Choosing the View Mode

Click the arrow at the right of the button, to show the view mode menu:

The list of available options depends on the type of log message that you are displaying. The following table lists the options that may be provided.

Button View Mode Description
Hex-dump View the log message in hexadecimal format. Non-displayable characters are highlighted in the following colors:

  • Carriage return (OD) characters are highlighted in light blue.
  • Other ASCII control characters are highlighted in dark blue.
  • Other non-printable characters are highlighted in green.
Plain-text View the log message in text format.
Segment View View the segments that are defined in this message. This view mode is available only if this message is of type Message. (For more information, see Viewing Message Segments below this table.)
Segment Grammar View View the segments in the segment grammar of the message definition that processed this message. This view mode is available only if this is a message that was processed by a channel whose destination component is To Database. (For more information, see Viewing Message Segments below this table.)
Table View (Graphical) Parse the message and view the generated tables in graphical format. This view mode is available only if this is a message that was processed by a channel whose destination component is To Database. (For more information, scroll down to Viewing generated Tables.)
Table View (Plain-text) Parse the message and view the generated tables in text format. This view mode is available only if this is a message that was processed by a channel whose destination component is To Database. (For more information, scroll down to Viewing generated Tables.)
SQL View Parse the message and view the SQL statements that add this message to the database. This view mode is available only if this is a message that was processed by a channel whose destination component is To Database. (For more information, scroll down to Viewing generated SQL Statements.)

Viewing Message Segments

You can view detailed segment information for any logged message.

To view message segments:

  1. From Iguana, click the Logs tab.
  2. Click a message to view it.
  3. Select Segment View from the view mode drop-down menu:
  4. The Logs screen will display the message segments:
  5. Click anywhere on a segment to expand it, click on it again to contract it:
  6. If a field has subfields, you can also click on it to expand and contract.
  7. Errors or warnings are displayed in the bottom panel, to hide them uncheck Show Warnings:

Note: If a VMD file has been specified for the channel through which this message was sent, the segment field names are retrieved from the segment definitions specified in the VMD file.

If no VMD file has been specified, segment field names are obtained from the segment definitions in the HL7_2.6.vmd library VMD file.

The HL7_2.6.vmd library file is included with your Iguana installation, and is stored in the <Iguana install directory>\Libraries directory.

If the message was loged by a channel with a To Database destination component, you can also view the segment grammar definition matching the message (message definitions are specified in the VMD for the channel).

  1. To view the segment grammar, select Segment Grammar View from the view mode menu:
  2. As in the Segment View, you can click anywhere on a segment to expand/contract it:
  3. To view the complete segment grammar, check Show Complete Grammar. This displays the empty segments that are part of the message grammar (the same as “Show Empty Nodes” for annotations):

Viewing generated Tables

If a message was logged by a channel using a To Database destination component, you view the database table entries that have been generated for it. These table entries can be displayed in graphical or text format. Iguana uses the table definitions from VMD file configured in the To Database component.

To view table information for an HL7 message:

  1. To view message tables in graphical format, select Table View (Graphical) from the view mode menu:
  2. In this case the message definition is ADT, and its table grammar consists of two tables, patient and kin:

To view the data generated for a table.

  1. Click the name of a table to view data:
  2. If more than one row of table data has been generated from a message, you can view the row location for a specific row. To view this information, click a Row Location link:

    In this example the second Row Location link was clicked. The Grammar Information window indicates that this line of data is the second kin table row generated from the message.
    Note: The row numbering starts from zero, i.e., the first row is labelled Row 0, the second is labelled Row 1, and so on.
  3. To display the tables in text format, select the Table View (Plain-text) view mode:
  4. When you have finished, click Close (top right) to go back to the log messages.

You can use Table View with messages from a Source Channel when the Destination Channel uses a To Database destination component. The Table View uses the table definitions from the To Database destination component. If there are multiple Destination Channels, then you can choose which table definitions to use.

Note: A Source Channel forwards data to other channels by using a To Channel destination component. A Destination Channel receives data from other channels by using a From Channel source component.

For example:

  • Data is sent from a Source Channel named llp_to_channel
  • Data is sent to A Destination Channel named channel_to_db
    Note:
    Set the Source Channel in the Source channel properties
  • The Destination Channel channel_to_db uses a To Database destination component
  • Then you can use the database tables definitions in channel_to_db to parse the message sent through llp_to_channel
    Note:
    Table definitions are from the VMD file specified in the To Database component.

Here is an llp_to_channel message parsed using the table definitions in channel_to_db:

If we add a second Destination Channel then we can choose which table definitions to use.

For example:

  • A second Destination Channel named channel_to_db_2 also uses a To Database destination component
  • If channel_to_db_2 also uses llp_to_channel and as its Source Channel
  • Then you can choose the table definition from channel_to_db or channel_to_db_2

Here is an llp_to_channel message showing the choice from a drop-down menu:

Tip: If you get an error dialog “No available parsers for this message”, or this error message:

Then read this blog post: The saga of Table View with multiple Channels…

Viewing generated SQL Statements

If an HL7 message has been logged for a channel that has To Database as its destination component, you can view the SQL statements that were generated to add the message to the database.

To view generated SQL statements:

  1. Click a message to view it:
  2. To view the generated SQL statements, choose SQL View from the view mode menu:
  3. The SQL statements are displayed:
  4. Use to turn line wrapping on or off.

Other Message Types [top]

You can also view various other types of messages.

Network Messages

Iguana also provides detailed logging of network messages, such as connection errors and retry attempts. This makes it easier for you to diagnose any connection problems that may occur.

For example, here is a sequence of log messages generated when a channel is trying to connect to an LLP server, and the server is not listening to the channel:

Log Messages Generated By Failed Connection Attempts

From these log messages, you can see that Iguana is unable to connect to an LLP server at port 5145 of machine localhost. You can also see that Iguana will attempt to reconnect 10 times, and will try again every 1000 milliseconds.

Note: Iguana also generates log messages for the following events:

  • When a channel is added, modified or removed;
  • When a login session expires.

User Actions

The Iguana logs keep track of the following actions that users perform:

  • Logging into or logging out of the system
  • Attempting to log in with an unknown user name or incorrect password
  • Stopping a channel
  • Changing a channel configuration
  • Adding or deleting a channel

The Iguana logs also indicate when a user session has expired due to inactivity.

The following table lists the messages that are generated by the Iguana logs:

Action Message
User logs in to Iguana User <username> has logged in from remote IP <address>.
User logs out of Iguana User <username> has logged out.
User attempts to log in with an unknown user name Failed login attempt from remote IP <address>: non-existent user <username>.
User attempts to log in with an incorrect password Failed login attempt from remote IP <address>: incorrect password for user <username>.
Channel stopped Channel is being stopped by user <username>.
Channel configuration changed Channel <channelname> modified by user <username>.
Channel added Channel <channelname> added by user <username>.
Channel deleted Channel <channelname> removed by user <username>.
User session expires Session has expired for user <username>.

Note: Failed login attempts are recorded as log messages of type Error. This means that they will appear on the Dashboard Control Panel as errors.

For example, here is what the Logs screen looks like when user admin logs in and then logs out:

The easiest way to determine who has logged in is to search the logs using the text query “has logged in”. See Searching the Logs for more information.

Search/Filter the Logs [top]

From the dashboard we can get to the Logs tab directly or by clicking on various statistics like the LAST ACTIVITY, ERRORS or QUEUED messages for a channel.

This screen shot of the logs tab shows the search related features:

  1. The text query box is used to filter the logs, it can take a plain string or a complex boolean expression, it also accepts regex patterns. Iguana maintains a full text index for rapid searching. Partial substring searches have to be escaped with a “!” before the string, which will be slightly slower as it does a linear search of the logs. For more information on the search criteria that you can use, see Specifying Search Criteria in a Dashboard Search (which uses the same criteria).

    Note: Iguana uses index-based searching. For most searches this search method produces results much more quickly.

    Iguana also contains a low-priority thread that checks whether each log file has had an index file defined for it. If an index file is missing, the thread creates it. Log files are searched in reverse chronological order, from newest to oldest.

    Searches that use regular expressions or prefixed with “!” are do not use the indexes.

    Tip: Using the “!” search prefix.

    In some cases, the index-based search may not display matches that are found in the middle of a word. For example, the search criterion “Acct” may not match a message containing the string PatientAcct. If you suspect that this might be happening in your search, try ! as the first character in your search to use slower non-indexed search (for example, use “!Acct” instead of “Acct”).

    ! only has special significance when it is the first character in a search. If ! appears anywhere else in a search criterion, it is treated as part of the string to be searched for.

  2. Use the Channel list box to select the source of the log messages. We can filter results for a specific channel or the Service Entries (administrative log entries from the Iguana Server service/daemon).
  3. Check Time Range to restrict to a given date or time range. You can enter dates in free format like January 1 2011 or 1-Jan-2011, or use the calendar control.
     

    Note: If you do not specify a start date, Iguana displays all messages that were sent before the to date. Similarly If you do not specify an end date, Iguana displays all messages after the from date.

  4. Use the Type list box to filter on the type of logs. Select All to display all message log types, or you can select one or more log message types to display. See Types of Log Messages, for more information on the various log types.
     

    Note: Log entries cannot be deleted, only hidden.

    Errors can be Marked as not needing attention (hidden), you can choose to view Marked or Unmarked errors.

  5. Use the Show Deleted list box to choose whether to show/hide “deleted messages”:

    Note: Log entries cannot be deleted, only hidden.

    Messages can be flagged as Deleted (hidden), you can choose to show deleted messages.

  6. Deleted messages are displayed using grey overstrike characters, and DELETED is superimposed on the message icon:

    As with any other log message, you can click a deleted message to view it:
  7. We can use the Bookmark Search to create a URL for a search. Using a URL to quickly recreate a search is really handy (particularly with complex searches and regex). Some customers have even set up wikis that allow their team to retrieve common search criteria.
  8. The Up and Down buttons, or Ctrl+Home and Ctrl+End shortcuts, jump to the to first or last item meeting the current filter criteria.

Tip: When the Export panel is visible the Search Criteria are hidden.

Click the link or the “+” to show the Search Criteria panel:

Regex Search Criteria [top]

You can use also use regular expressions (regex) in the Log Text Query search field, simply enclose the expression in slash characters /<regex>/.
Note: The closing slash is optional unless you wish to combine multiple regex expressions.

Tip: I found the Regex 101 online tester very helpful when creating/testing the expressions on this page. The Regex Buddy application (Windows only) also comes highly recommended, though it is not free. And you can google to find many other regex testers.

Also the regexper page is helpful for visualising regex queries as Railroad Diagrams (EBNF Syntax Diagrams), for example the regex “/PID(\|[^|]*){5}(Sm[iy]the?)\b/” looks like this:

Here are a few ideas for (hopefully) useful things you can do with regex queries:

  1. Match all HL7 messages for all channels
    • Use an anchor “^” to match all channels beginning with “MSH”:
      /^MSH/

      Alternatively you can omit the second slash:

      /^MSH
    • This query will return all log entries starting with MSH, to restrict it to messages select “Messages” from the Type list in the Search Criteria panel.
  2. Match non-HL7 messages for all channels:
    • First select “Messages” from the Type list in the Search Criteria panel.
    • Then negate the regex (from above) that matches all HL7 messages:
      NOT /^MSH/
    • Alternatively use a regex with look-ahead not equals “?!”:
      /^(?!MSH)/
  3. Match all messages for all patients with the same surname, for a specified channel.
    • Select “Messages” from the Type list in the Search Criteria panel.
    • Select the the desired channel name from Channel drop down (we used Sender).
    • This regex returns all records containing the name, unfortunately it matches relatives (NK1) and doctors (PV1) named “Smith” as well as Patients (PID):
      Note: A simple (non-regex) search (without the slashes) will give the same result.

      /Smith/
    • This regex checks the Name field in the PID segment so it only matches only matches patients named “Smith”:
      /PID(\|[^|]*){5}Smith/
    • Check for alternative spelling of Smith, Smithe, Smyth, or Smythe:
      /PID(\|[^|]*){5}(Sm[iy]the?)\b/
    • You can also check for multiple names:
      /PID(\|[^|]*){5}(Smith|Jones)/
  4. Exclude all messages for all patients with the same surname, for a specified channel.
    • Select “Messages” from the Type list in the Search Criteria panel.
    • Select the the desired channel name from Channel drop down (we used Sender).
    • Negating the matching regex excludes all records containing the name, unfortunately it excludes relatives (NK1) and doctors (PV1) named “Smith” as well as Patients (PID):
      Note: A simple (non-regex) search (without the slashes) will give the same result.

      NOT /Smith/

      Alternatively use regex with look-ahead not equals “?!”, unfortunately this also excludes all messages containing “Smith” not just patients:

      /^(?!.*Smith)/
    • Negating a regex that checks the Name field in the PID segment excludes patients named “Smith”:
      NOT /PID(\|[^|]*){5}Smith/

      Alternatively use regex with look-ahead not equals “?!”:

      /PID(\|[^|]*){4}\|(?!Smith\b)/
    • Negate checking for alternative spelling of Smith, Smyth, or Smythe:
      NOT /PID(\|[^|]*){5}(Sm[iy]the?)/

      Alternatively use regex with look-ahead not equals “?!”:

      /PID(\|[^|]*){4}\|(?!Sm[iy]the?)/

      Note: This regex relies checking the first (surname) sub-field in the name field, by using “\|” (/PID(\|[^|]*){4}\|(?!Sm[i|y]th[e]?)/) to match the start of the name field.

    • You can also negate checking for multiple names:names:
      NOT /PID(\|[^|]*){5}(Smith\b|Jones)/

      Alternatively use regex with look-ahead not equals “?!”:

      /PID(\|[^|]*){4}\|(?!Smith\b|Jones)/
  5. Match a specified value in a specified field in an HL7 message.
    • Use this regex format:
      /<segment>(\|[^|]*){<field>}<value>/
    • To find Toronto in the address field of the PID segment:
      /PID(\|[^|]*){11}Toronto/
    • To find LA or Los Angeles in the address field of the PID segment:
      Note: The “\b” (word boundary) to only match “LA” as a whole word, to prevent matching things like “Miller Lane” or “Lake Rd”

      /PID(\|[^|]*){11}(Los Angeles|LA\b)/
  6. Exclude a specified value in a specified field in an HL7 message.
    • Negate this regex format:
      NOT /<segment>(\|[^|]*){<field>}<value>/
    • To exclude Toronto in the address field of the PID segment:
      NOT /PID(\|[^|]*){11}Toronto/
    • To exclude LA or Los Angeles in the address field of the PID segment:
      Note: The “\b” (word boundary) to only match “LA” as a whole word, to prevent matching things like “Miller Lane” or “Lake Rd”

      NOT /PID(\|[^|]*){11}(Los Angeles|LA\b)/
    • We didn’t come up with a regex to exclude values in a field (let us know if you figure it out). However we were able to exclude values in a sub-field (see point 8 below).
  7. Match a specified value in a specified sub-field in an HL7 message.
    • Use this regex format:
      /<segment>((\|[^|]*){<previous-field>}\|([^^]*\^){<sub-field>})<value>/
    • To find Toronto in the address field of the PID segment:
      /PID((\|[^|]*){10}\|([^^]*\^){2})Toronto/
    • To find LA or Los Angeles in the address field of the PID segment:
      Note: A “\b” (word boundary) to match “LA” only is not required, because we are now only searching the specific sub-field.

      /PID((\|[^|]*){10}\|([^^]*\^){2})(Los Angeles|LA)/
    • To find the name Smith, Smyth, or Smythe in the surname sub-field:
      Note: A “\b” (word boundary) is not required because we are only searching the specific sub-field.

      /PID((\|[^|]*){4}\|([^^]*\^){0})(Sm[iy]the?)/
  8. Exclude a specified value in a specified sub-field in an HL7 message.
    • Use this regex format:
      /<segment>((\|[^|]*){<previous-field>}\|([^^]*\^){<sub-field>})[^(<value>)]/
    • To exclude Toronto in the address field of the PID segment:
      /PID((\|[^|]*){10}\|([^^]*\^){2})[^(Toronto)]/
    • To exclude LA or Los Angeles in the address field of the PID segment:
      Note: A “\b” (word boundary) to match “LA” only is not required, because we are now only searching the specific sub-field.

      /PID((\|[^|]*){10}\|([^^]*\^){2})[^(Los Angeles|LA)]/
    • To exclude the name Smith, Smyth, or Smythe in the surname sub-field:
      Note: A “\b” (word boundary) is not required because we are only searching the specific sub-field, also we used “(i|y)” instead of the bracketed character class “[iy]” we used earlier (because it raises an error when used with character class negation [^…]).

      /PID((\|[^|]*){4}\|([^^]*\^){0})[^(Sm(i|y)the?)]/
  9. Match or exclude messages where the patient surname matches the surname of a relative.
    1. Use this regex to match:
      Note: “(?s)” is a PCRE option to match newlines (\n), “\d” matches a single numerical digit, “\3” represents the 3rd capture group (that captures the surname).

      /(?s)PID((\|[^|]*){4}\|([^^]*[\^|\|]){1})(.*NK1\|\d\|\3)/

      Alternatively using a named group can be easier to understand:
      Note: “?P<surname>” names the group, “?P=surname” references it, also we used “?:” to make other groups non-capturing (more efficient).

      (?s)PID(?:(?:\|[^|]*){4}\|(?P<surname>[^^]*[\^|\|]){1})(.*NK1\|\d\|(?P=surname))
    2. Use a regex with look-ahead not equals “?!” to exclude:
      /(?s)PID(?:(?:\|[^|]*){4}\|(?P<surname>[^^]*[\^|\|]){1})(?!.*NK1\|\d\|(?P=surname))/
  10. Match or exclude messages where the patient surname matches the surname of a (referring) doctor.
    • Use this regex to match:
      Note: “(?s)” is a PCRE option to match newlines (\n), “\d” matches a single numerical digit, “\3” represents the 3rd capture group (that captures the surname).

      /(?s)PID(?:(?:\|[^|]*){4}\|(?P<surname>[^^]*[\^|\|]){1})(.*PV1.*[\d]*\^(?P=surname))/

      Note: This regex assumes that the Person Identifier code for the Doctor contains a numeric code, or if the code is alpha, the regex will not match.

    • Use a regex with look-ahead not equals “?!” to exclude:
      /(?s)PID(?:(?:\|[^|]*){4}\|(?P<surname>[^^]*[\^|\|]){1})(?!.*PV1.*[\d]*\^(?P=surname))

 

Leave A Comment?