Status API

The Status API allows to fetch statistics from the software components running in Toolpack or TMG-CONTROL.

Getting used with Status API

Status API consists of status request queries based on a "path". Each status has a path, like:

/adapter
/adapter/ip_interface
/isup/interface
/clock/ref
etc.

We already provide two ways of accessing the Toolpack Status:

- Web Portal
- Command-line tool "tbstatus", that you will find installed within toolpack installation under /lib/tb/toolpack/pkg/2.X.X/bin/release/[your_platform]/tbstatus

Viewing status tree using Web Portal

I suggest that you start by using the "browse" option in the WEB portal: Go to the Web Portal -> Status -> Browse This tool will list available paths that can be queried. When you click one of these paths, the web page will show a table that list all fields returned from that path.

Note: If you bring the mouse over a field name, a tool tip will appear and show a short description.

Viewing status tree using the command-line tool

The command-line tool will also allow getting a list of available paths:

./tbstatus

You can also query stats using one of these path, result is formatted as text output:

./tbstatus /adapter

Example above show stat of all adapters. You can query more specific stats too:

./tbstatus /adapter:TB005432 

Or you can query "recursive" information that also includes paths "under" a base path:

./tbstatus /adapter:TB005432/* 

Or you can query very deep and specific information:

./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12

Viewing statistics field description with the command-line tool

You can query a short description of each statistic field by providing the '-D' option to the command-line tool.

./tbstatus /isup/interface/cic_group -D

For example:

[root@TB011107 monitoring]# tbstatus /isup/interface/cic_group -D
The requested path is '/isup/interface/cic_group'.
0:/isup:ISUP/interface:ISUP_IF0/cic_group:C011107_00
C011107_00 -
  - desired_group_state                   : Default       (Default,Blocked,Unblocked) Circuit Group desired state.
  - toggle_group_reset                    : No            (No,Yes) Setting this flag will toggle a Circuit Group reset.
  - start_continuity_check                : No            (No,Yes) Setting this flag will send a Continuity Check Request (CCR) on all CICs of the group (not available if no drop box).
  - interface_down                        false           Circuit group's interface is down.
  - idle_cnt                              30              Number of idle circuits.
  - incoming_cnt                          0               Number of active incoming circuits.
  - outgoing_cnt                          0               Number of active outgoing circuits.
  - locally_blocked_cnt                   0               Number of circuits in locally blocked state (maintenance).
  - remotely_blocked_cnt                  0               Number of circuits in remotely blocked state (maintenance)).
  - locally_remotely_blocked_cnt          0               Number of circuits in locally remotely blocked state.
  - reset_cnt                             0               Number of circuits in reset state.
  - total_ccr_success_cnt                 0               Total number of CCR tests that were succesful for any CIC of this group.
  - total_ccr_fail_cnt                    0               Total number of CCR tests that failed for any CIC of this group.
  - last_ccr_unknown_cnt                  30              Number of circuits for which no CCR test was started.
  - last_ccr_in_progress_cnt              0               Number of circuits for which a CCR test is in progress
  - last_ccr_success_cnt                  0               Number of circuits for which the last CCR test was succesful.
  - last_ccr_fail_cnt                     0               Number of circuits for which the last CCR test failed.
  - last_ccr_error_cnt                    0               Number of circuits for which an internal error occured in the last CCR test. Might be because circuit was not idle prior to launching the test

Paths for ISUP Circuit states

You can query states for one circuit group using a path like this one (replace C002020_2_0_12 by your circuit group name, as seen in it's Web portal configuration):

./tbstatus /isup/interface/cic_group:C002020_2_0_12

If you're using version 2.4 or up, you also have access to individual circuits states... but you HAVE to use "-x" option (extended stats mode) to get these. To get states for all CICs of a group:

./tbstatus [u]-x[/u] /isup/interface/cic_group:C002020_2_0_12/*

For example, to get states for CIC #1705, you can use:

./tbstatus -x /isup/interface/cic_group/cic:1705

Querying/modifying individual field value using the command-line tool

To query individual field value, you add "::" after the path, then specify the specific field name. For example:

./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state

Or to modify the circuit state (here to force blocking state):

./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state=Blocked

• Note: Remember that this change is PERSISTENT, which means circuit will remain blocked forever (no matter trunk state) until you change it again (to "Default", or "Unblocked" for example).

How to write code that use that API

Now that you understand a bit how Status API works, here is a short explanation on how to write code to manipulate these states.

In short you need to create and start the status client service in your application:

 pClient = tbnew CTBCAFServiceStatusClient();
 pClient->Start();

Then each available stat is reported under a "path". Your code can call the following function to get available paths:

 pClient->GetRegisteredPaths();

Once you know the path you want to query, you can retrieve the stats, either synchronously or asynchronously: Synchronously:

 pStatList = pClient->GetStat(
   "your_path",
   "x"
 );

Asynchronously:

 pClient->ReqStat(
   pMyStatPipe,
   "your_path",
   "x"
 );

Available options:

- Option "x" passed to in_pszOptions means "extended" stats query (provides more detailed stats in some cases, like individual circuits)
- Option "d" will make documentation be returned for each field with the query response (by default, only field names and values are returned)

For more information on "pMyStatPipe", please read documentation from the header files in the code.

Once you get your "pStatList", you can get each item it retBold texturned (there can be many if your request matches many):

 pStat = pStatList->GetItem( un32StatIdx );

And for each item, you can get list of fields:

 pFieldList = pStat->GetFields();

... and list each field (one field is one individual stat value):

 pField = pFieldList->GetItem( un32FieldIdx );

Now, as you traverse the stat tree, you will encounter some values that can be changed using:

 pField->Set( "new value" );

Once you have changed one or more fields of the stat, you can commit it:

 pStat->CommitStates();

For more detailed information, please refer to the source code of the "tbstatus" application, and to documentation in appropriate header files.

Note

In order to get/set individual circuits states, you need:
- Release 2.4 or more recent, since release 2.3 allowed only to change state per circuit group... (per trunk in other words)
- Need to use "-x" in the options field of GetStat, as per-circuit stats are shown only in "extended" mode