Logs that aren’t useless

At the 2014 IGUANA User Conference, a number of presentations highlighted interesting, and incredibly useful ways to take advantage of IGUANA’s logging capabilities. As such, I thought I’d combine those lessons into a single post to introduce newbies to IGUANA’s logs and provide some tangible starting points for those of you looking to do even more.

Let’s start with what IGUANA’s logs are and what they are not.

IGUANA’s logs are a genuine feature of the product. They are not a “dumb” text-file or something that you only remember exists when an error arises.

Architecturally, the logs are actually a critical piece of IGUANA’s backbone. They are directly tied to the queuing system and the delivery of messages. They help power the out-of-the-box notification system. They can be browsed/searched/queried, either from within the UI or programmatically, and it’s trivial to augment the built-in logging by generating your own messages.

All of that is to say that: IGUANA’s logs are definitely not your typical logs.

So, what can you do with the logs?

If you’re looking for basic information about IGUANA’s logs – like viewing messages and marking errors – then I suggest you browse the following Help Center section: http://help.interfaceware.com/section/using-iguana/understanding-iguanas-logs

If however, you want to know how we leverage IGUANA’s logs to do some pretty amazing things, then continue reading and I’ll show you how to get started and give you a few examples of what you can do going forward.

There are really just 2 things you need to know how to do if you want to start taking advantage of IGUANA’s awesome logs.

You need to know how to query the logs programmatically.
You need to know how to create your own log entries.

Once you understand those two concepts, creating entirely new workflows, tapping into the huge amount of data that flows through your integration engine or doing just about anything you can imagine becomes a very real possibility.

Before we get to that though, let’s quickly explore how to do both of the tasks listed above.

1. Querying IGUANA’s Logs Programmatically

Every IGUANA instance has a simple API endpoint that you can query to bring back whatever information you want from the logs. The URL is http://<your_iguana_ip:port>/api_query

To actually return information from the API, you’ll need to pass along valid user credentials. (The logs can contain some pretty sensitive information, so we can’t just give that information out to anyone who asks.)

Below is a very simple script you can copy/paste into any Translator instance to see exactly how querying the logs works.

Note: If you’re using a different URL or port for your instance, and/or if you use usernames and passwords that are actually secure, just update line #1 and #6/7 respectively to match your settings.

local my_iguana = 'http://localhost:6543/api_query'

function main()
   local log = net.http.get{url=my_iguana,
      parameters={
         username='admin',
	 password='password',
	 limit   = 50,        -- show only 50 entries
      },
      live=true
   }
   xml.parse{data=log}
end

If all goes according to plan, you should see an XML document in your annotation windows that contains up to 50 log entries. From there, it’s just like working with any other form of a data. You can loop through the records, compile stats or do any other form of post-processing.

Also, if you’re curious, there are a number or parameters you can pass along with your request that will help you filter and segment the entries that are returned. Really, it’s the same as what you can do in the GUI. For a detailed list, please visit this page.

Now, that we’ve queried IGUANA’s logs, let’s also add an entry of our own.

2. Creating your own log entries

This may not seem like much at first, but the ability to create your own log entry, coupled with the fact that much of IGUANA’s internal functionality is tied to log events, means you can do some pretty creative and amazing stuff if you want.

For example: My custom reporting script – seen here – creates custom log entries whenever certain thresholds are met, so that IGUANA’s standard notification system will send out alerts.

Anyway, what’s possible with custom entries is nearly endless, but the process of creating them is, well, kind of boring…

All you have to do is:

iguana.logInfo('Art is very helpful.')

Now, if you want to generate one of the other log entry types, it’s just a matter of using a different command such as logDebug, logError or logWarning. For example:

iguana.logWarning('You forgot to tell Art how helpful he is.')

Side Note: If you’re reading this article around the time that it was posted (Feb. 25, 2015), and you click one of the links above, you’ll be one of the very first people in the world to see our latest API documentation. I actually made that one myself, using: wait for it, wait for it,… yep. The Translator! I’ll probably end up blogging about the process of creating it in a later post, but for now, just have a look and let me know what you think.

Advanced Uses of IGUANA’s Logs

Now that you’ve seen how to create and read log entries programatically, let’s dive into some of the things you can do with your newly acquired knowledge.

Create a Simple Message Counting App

Bret, from our development team, actually presented this at the 2014 User Conference. His presentation was actually geared towards demonstrating how you can easily build-and-deploy simple applications on top of IGUANA, but what he created was a great example of a useful query of the logs.

For his “app” he wanted to answer a question we had heard from a handful of customers:

“Is there an easy way for me to count the number of different messages that I receive?”

So, what did he come up with? Well, take a look for yourself: http://labs.interfaceware.com:6544/starting2/

This simple app let’s you select the message type you’re interested in, along with the timeframe, and then queries the logs on the local machine for matching messages. Once it gets back the result set, it publishes the count to your screen.

If you’re interested in the full code of the app, you can grab it here: Starting2_From_HTTPS.

To run it yourself: Create a “From HTTPS” / “To Channel” interface and import the .zip file. From there, you’ll need to update main.lua:69 to match your username/password and tiny_page.html:36 to match the URL path of your newly created channel.

Remember though, this was intended as a demonstration of true “app” building with IGUANA, so it includes code to serve up HTML and JavaScript along with the log query stuff.

Create Your Own Log Search (Custom GUI)

The following example wasn’t built for the 2014 User Conference, it was built during the conference.

A customer that I had previously spent some time visiting with was inspired by Bret’s presentation and asked:

“How easy it would be to leverage Bret’s work to create something that would allow me to easily search the logs to find specific information in a specific segment or field?

I took that as a challenge and started coding up an example on the spot. While I can’t claim I finished the code right then and there, I did deliver the following little “app” within a few days.

http://labs.interfaceware.com:6544/log/

Once again this “app” queries IGUANA’s logs. Only this time, rather than simply returning a count, I wrote a little logic that loops through the returned entries, parses the HL7 messages and then looks for matches of specific information. It’s a little more time intensive of a search, but the end result is that you can quickly and easily find all the messages where the patient’s last name is “Green” without returning messages where “Green” is mentioned in a note, address, next of kin or some other field. You could do the same with a complex regular expression search, but for me, I tend to prefer a form.

If you’re interested in the full code of the app, you can grab it here: Custom_Log_Search_From_HTTPS

To run it yourself: Create a “From HTTPS” / “To Channel” interface and import the .zip file. From there, you’ll need to update main.lua:6 & 7 to match your username/password.

Creating your own dashboard / Looking at “Small Data”

While I don’t have any source code to share with you for my final example, I wanted to talk briefly about one of the most powerful ways you can use IGUANA’s logs: as a source of massive data.

Think about it: For most of you, IGUANA is sitting in between dozens of critical systems; each of them passing huge amounts of data around each and every day. Now that you are familiar with the concept of querying IGUANA’s logs to access this information, think about how this might effect:

your reporting requirements,
your desire to gain deeper insight into who’s referring patients your way,
what times you’re seeing peaks in activity,
which claims are being rejected and why,
and much, much more.

We’ve actually been talking about these exact topics in our “Big Impact of Small Data” seminar series, so if you’d like to learn more, just reach out or comment below and we’ll be happy to share even more details.

That’s all folks

Well, that’s all I have for now. I hope that gets you thinking and planning on taking a closer look at IGUANA’s logs and what they can do for you.

Before I go though, a “Canadian” post that says “log” in excess of 67 times simply wouldn’t be complete without the inclusion of a very old, but very awesome, Canadian video. I leave you, for your viewing pleasure, with the Log Driver’s Waltz.

If you have any questions about IGUANA’s logs (or heck, this video), please let me know. I’m very helpful. 😉

Feb 25, 2015iNTERFACEWARE