Status API - Revision history

Lucas Joyal: /* How to write code that use that API */ fix typo

2017-11-27T15:46:54Z

How to write code that use that API: fix typo

Lucas Trottier at 03:41, 18 September 2014

2014-09-18T03:41:20Z

Lucas Trottier at 03:29, 18 September 2014

2014-09-18T03:29:49Z

Lucas Trottier at 03:25, 18 September 2014

2014-09-18T03:25:35Z

Clod Patry: remove italic code which was incorrect

2013-10-25T14:12:03Z

remove italic code which was incorrect

Abrassard at 15:40, 9 June 2010

2010-06-09T15:40:45Z

Abrassard: Created page with ''''* 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_interfa…'

2010-05-06T16:24:47Z

Created page with ''''******* 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_interfa…'

New page

'''******* 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.

'''******* Viewing status tree using the command-line tool **********'''

The command-line tool will also allow getting a list of available paths:
[i]./tbstatus [/i]
You can also query stats using one of these path, result is formatted as text output:
[i]./tbstatus /adapter [/i]
Example above show stat of all adapters. You can query more specific stats too:
[i]./tbstatus /adapter:TB005432 [/i]
Or you can query "recursive" information that also includes paths "under" a base path:
[i]./tbstatus /adapter:TB005432/* [/i]
Or you can query very deep and specific information:
[i]./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12[/i]

'''******* 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):
[i]./tbstatus /isup/interface/cic_group:C002020_2_0_12[/i]

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:
[i]./tbstatus [u]-x[/u] /isup/interface/cic_group:C002020_2_0_12/*[/i]
For example, to get states for CIC #1705, you can use:
[i]./tbstatus -x /isup/interface/cic_group/cic:1705[/i]

'''******* 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:
[i]./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state[/i]
Or to modify the circuit state (here to force blocking state):
[i]./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state=Blocked[/i]

* 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 sort 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 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"
);

Argument "-x" passed to in_pszOptions means "extended" stats query (provides more detailed stats in some cases, like individual circuits)
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 returned (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

@@ Line 38: / Line 38: @@
   ./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12
-== Viewing statistics field documentation with the command-line tool ==
+== 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.

@@ Line 21: / Line 21: @@
 This tool will list available paths that can be queried.<br>
 When you click one of these paths, the web page will show a table that list all fields returned from that path.
@@ Line 64: / Line 66: @@
     - 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 ==

@@ Line 92: / Line 92: @@
 == How to write code that use that API ==
-Now that you understand a bit how Status API works, here is sort explanation on how to write code to manipulate these states.
+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:
@@ Line 98: / Line 98: @@
    pClient->Start();
-Then each available stat is reported under a "path". Your code can call following function to get available paths:
+Then each available stat is reported under a "path". Your code can call the following function to get available paths:
    pClient->GetRegisteredPaths();

@@ Line 1: / Line 1: @@
-'''******* Getting used with Status API **********'''
+The Status API allows to fetch statistics from the software components running in Toolpack or TMG-CONTROL.
 Status API consists of status request queries based on a "path". Each status has a path, like:
@@ Line 13: / Line 15: @@
-'''******* Viewing status tree using Web Portal **********'''
+== Viewing status tree using Web Portal ==
 I suggest that you start by using the "browse" option in the WEB portal:<br>
@@ Line 21: / Line 23: @@
-'''******* Viewing status tree using the command-line tool **********'''
+== Viewing status tree using the command-line tool ==
 The command-line tool will also allow getting a list of available paths:
@@ Line 34: / Line 36: @@
   ./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12
-'''******* Paths for ISUP Circuit states **********'''
+== 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):
@@ Line 48: / Line 78: @@
-'''******* Querying/modifying individual field value using the command-line tool **********'''
+== 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.
@@ Line 59: / Line 89: @@
-'''******* How to write code that use that API **********'''
+== How to write code that use that API ==
 Now that you understand a bit how Status API works, here is sort explanation on how to write code to manipulate these states.
@@ Line 89: / Line 119: @@
 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 returned (there can be many if your request matches many):
+Once you get your "pStatList", you can get each item it ret'''Bold text'''urned (there can be many if your request matches many):
    pStat = pStatList->GetItem( un32StatIdx );
@@ Line 108: / Line 138: @@
 For more detailed information, please refer to the source code of the "tbstatus" application, and to documentation in appropriate header files.
-'''******* Note **********'''
+'''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

@@ Line 24: / Line 24: @@
 The command-line tool will also allow getting a list of available paths:
-  [i]./tbstatus [/i]
+  ./tbstatus
 You can also query stats using one of these path, result is formatted as text output:
-  [i]./tbstatus /adapter [/i]
+  ./tbstatus /adapter
 Example above show stat of all adapters. You can query more specific stats too:
-  [i]./tbstatus /adapter:TB005432 [/i]
+  ./tbstatus /adapter:TB005432
 Or you can query "recursive" information that also includes paths "under" a base path:
-  [i]./tbstatus /adapter:TB005432/* [/i]
+  ./tbstatus /adapter:TB005432/*
 Or you can query very deep and specific information:
-  [i]./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12[/i]
+  ./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12
@@ Line 39: / Line 39: @@
 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):
-  [i]./tbstatus /isup/interface/cic_group:C002020_2_0_12[/i]
+  ./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:
-  [i]./tbstatus [u]-x[/u] /isup/interface/cic_group:C002020_2_0_12/*[/i]
+  ./tbstatus [u]-x[/u] /isup/interface/cic_group:C002020_2_0_12/*
 For example, to get states for CIC #1705, you can use:
-  [i]./tbstatus -x /isup/interface/cic_group/cic:1705[/i]
+  ./tbstatus -x /isup/interface/cic_group/cic:1705
@@ Line 52: / Line 52: @@
 To query individual field value, you add "::" after the path, then specify the specific field name.
 For example:
-  [i]./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state[/i]
+  ./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state
 Or to modify the circuit state (here to force blocking state):
-  [i]./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state=Blocked[/i]
+  ./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).