How to monitor Iguana Channels programmatically

Introduction

This page arose from a question about how to access the thread and request data shown in the Channel Status tooltip that you see in the Dashboard. However there is a lot more Dashboard information you can access, so we expanded the TIP to include all Dashboard data.

This is the Channel Status tooltip:

status tooltip

And you can actually access all Dashboard data including other tooltips and activity, as well as error and queue data, etc.:

other tip info

We show you several different ways to access this type of information by using the same web APIs that we use internally in Iguana, and by using the builtin iguana.status() API function.

Task [top]

How to access Dashboard data in a Translator script.

Implementation [top]

There are several ways to access Dashboard data:

 

  • /monitor_query: Returns XML containing overall information about Iguana, plus summary details for all channels
  • /status: Returns XML containing summary details for all channels
  • The iguana.status() API function: Returns a table containing summary details for all channels
    Note: The returned data is the same a from /status
  • /channel_status_data.html?Channel=<channel name>: Returns JSON containing detailed information for a single channel

Note: The /channel_status_data.html?Channel=<channel name> is the only way to get the active/idle thread numbers that you see in the Channel Status tooltip.

Currently this data needs to be extracted from the “status” HTML — in the future the status data may be added to the structured JSON for easier access.

Follow these steps to try the example code:

  1. Create a new channel to try out the code:
    • Create a channel like this:
      • Name: Channel Monitoring (or similar)
      • Source: From Translator
      • Destination: To Channel
    • Alternatively use an existing channel:

      Your channel will need a From/To Translator or a Filter component.

  2. Load the code into your channel:
    • If you are using a new channel then load this Channelmonitoring-FromTranslator project zip file:

      You can load the project zip file into a From/To Translator or a Filter component. This will overwrite the code in your main module — you may not want to d this with an existing channel.

    • Alternatively for an existing channel you can paste the code from below into the main module:

      This allows you to paste the code without overriding the code in your main module. This is useful if you are using an existing channel and you want to modify the existing code.

  3. You may need to change the logon credentials and Iguana Server name:
    Note: We used the install defaults so it will probably work unchanged on a development machine.
    change parameters
  4. Check the Channel Status data returned from the getStatus() function:

    The /channel_status_data command returns a “status” HTML snippet that contains the the thread and request data shown in the Channel Status tooltip. The getStatus() function extracts the thread and request data from this HTML “status” snippet (and is therefore dependent on its structure). If the snippet structure changes in the future this code may need to be modified.

    get status

  5. Play around with the code to see how it works:
    • For example the /status: command returns XML that we parsed:
      /status XML parsed
  6. Adapt the code to your requirements.

You can also use the three Web Service commands in a browser — good for diagnostics/troubleshooting:

  1. Just paste command <your server>/<command> into a browser, like:
    1. http://localhost:6543/monitor_query
    2. http://localhost:6543/status
    3. http://localhost:6543/channel_status_data.html?Channel=Web%20Service%20date%20and%20time
  2. The results will look similar to these:
    1. /monitor_query:
      1. The summary data will show at the top:
        monitor_query summary
      2. Scroll down for socket and channel information:
        monitor_query socket & channel
    2. /status:
      /status results
    3. /channel_status_data.html?Channel=<channel name>:
      /channel_status_data results

Code [top]

This is the example code for the main module:
-- change to use your Iguana logon credentials
-- for a Production system you should probably encrypt the password
-- and save it in a file, see this page:
-- https://help.interfaceware.com/v6/encrypt-password-in-file
USER = 'admin'
PASSWORD = 'password'

-- this is the default Iguana install URL name you 
-- may need to change it to match your Iguana server
MONITOR_QUERY = 'http://localhost:6543/monitor_query'
STATUS = 'http://localhost:6543/status'
CHANNEL_STATUS_DATA = 'http://localhost:6543/channel_status_data.html?Channel=Web%20Service%20date%20and%20time'

function main()
     
   local R =net.http.get{url = MONITOR_QUERY, auth={username=USER, password=PASSWORD},live=true,}   
   trace(R)
   R = xml.parse(R)
   trace(R)
   
   local R =net.http.get{url = STATUS, auth={username=USER, password=PASSWORD},live=true,}   
   trace(R)
   R = xml.parse(R)
   trace(R)
   
   R = iguana.status()
   R = xml.parse(R)
   trace(R)
   
   local R =net.http.get{url = CHANNEL_STATUS_DATA, auth={username=USER, password=PASSWORD},live=true,}   
   trace(R)
   R = json.parse(R)
   trace(R)
   
   -- get status data from the result
   local S = getStatus(R)
   trace(S[1]) -- Queued requests
   trace(S[2]) -- Busy threads
   trace(S[3]) -- Idle threads
   
end

-- NOTE: this function is placed here for ease of presentation
--       only - in a live system it should be in a local module
-- this function depends on the structure of the data returned
-- by the /channel_status_data function - if the structure is 
-- changed in a future release the code may need to be changed
function getStatus(R)
   R = R.LiveStatus
	trace(R)
   
   local S = {} cnt = 1
   for k in R:gmatch('(%w+)') do
      trace(k)
      S[cnt] = tonumber(k)
      cnt = cnt + 1
   end
   
   return S
end

How it works [top]

There are several ways to access Dashboard data:

  • /monitor_query:

    Returns XML containing overall information about Iguana, plus summary details for all channels. For easier access to the data you can parse it into an XML node tree using xml.parse().

  • /status:

    Returns XML containing summary details for all channels. For easier access to the data you can parse it into an XML node tree using xml.parse().

  • The iguana.status() API function:

    Returns an XML node tree containing summary details for all channels. The returned data is exactly the same a from /status.

  • /channel_status_data.html?Channel=<channel name>:

    Returns JSON containing detailed information for a single channel. This is the only way to get the active/idle thread numbers that you see in the Channel Status tooltip. Currently this data needs to be extracted from the “status” HTML — in the future the status data may be added to the structured JSON for easier access. For easier access to the data you can parse it into a Lua table using json.parse().

How the code works:

  1. The code is very simple.
  2. It contains an example of each command:
    monitor command examples
  3. It uses the the default Iguana logon and password, you can change to match your Iguana installation:
    default logon info
  4. It uses the default Iguana host name to run the queries, you can change to match your Iguana installation:
    default host name
  5. The web service commands return raw XML or JSON so we parse it into a table, /status for example:
    parsing status result
  6. And this is JSON returned by the /channel_status_data.html?Channel=<channel name> command:
    /channel_status_data JSON
  7. There are many ways that you can use this, for example you might want to monitor Iguana Servers remotely from a central location.

More information [top]

Leave A Comment?