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

← Older revision		Revision as of 11:46, 27 November 2017
Line 92:		Line 92:
	== 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.		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:		In short you need to create and start the status client service in your application:
Line 98:		Line 98:
	pClient->Start();		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();		pClient->GetRegisteredPaths();

Lucas Trottier at 03:41, 18 September 2014

2014-09-18T03:41:20Z

← Older revision		Revision as of 23:41, 17 September 2014
Line 38:		Line 38:
	./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12		./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.		You can query a short description of each statistic field by providing the '-D' option to the command-line tool.

Lucas Trottier at 03:29, 18 September 2014

2014-09-18T03:29:49Z

← Older revision		Revision as of 23:29, 17 September 2014
Line 21:		Line 21:
	This tool will list available paths that can be queried.<br>		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.		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.


Line 64:		Line 66:
	- last_ccr_fail_cnt 0 Number of circuits for which the last CCR test failed.		- 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		- 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
	~~</code>~~

	== Paths for ISUP Circuit states ==		== Paths for ISUP Circuit states ==

Lucas Trottier at 03:25, 18 September 2014

2014-09-18T03:25:35Z

← Older revision		Revision as of 23:25, 17 September 2014
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.

			== Getting used with Status API ==

	Status API consists of status request queries based on a "path". Each status has a path, like:		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>		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:		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		./tbstatus /isup:ISUP/interface:ISUP_INTERFACE/cic_group:C002020_2_0_12

			== Viewing statistics field documentation 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
			</code>

	'''***** 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):		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.		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.		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.		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 );		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.		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:		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)		- 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		- Need to use "-x" in the options field of GetStat, as per-circuit stats are shown only in "extended" mode

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

← Older revision		Revision as of 11:40, 9 June 2010
Line 2:		Line 2:

	Status API consists of status request queries based on a "path". Each status has a path, like:		Status API consists of status request queries based on a "path". Each status has a path, like:
	/adapter		/adapter
	/adapter/ip_interface		/adapter/ip_interface
	/isup/interface		/isup/interface
	/clock/ref		/clock/ref
	etc.		etc.

	We already provide two ways of accessing the Toolpack Status:		We already provide two ways of accessing the Toolpack Status:
	- Web Portal		- Web Portal
	- Command-line tool "tbstatus", that you will find installed within toolpack installation under		- 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
	/lib/tb/toolpack/pkg/2.X.X/bin/release/[your_platform]/tbstatus


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

Line 25:		Line 24:

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


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


Line 53:		Line 52:
	To query individual field value, you add "::" after the path, then specify the specific field name.		To query individual field value, you add "::" after the path, then specify the specific field name.
	For example:		For example:
	[i]./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state[/i]		[i]./tbstatus /isup/interface/cic_group/cic:1705::desired_cic_state[/i]
	Or to modify the circuit state (here to force blocking 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]		[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).		* 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).
Line 75:		Line 74:
	pStatList = pClient->GetStat(		pStatList = pClient->GetStat(
	"your_path",		"your_path",
	"-x"		"x"
	);		);

Line 82:		Line 81:
	pMyStatPipe,		pMyStatPipe,
	"your_path",		"your_path",
	"-x"		"x"
	);		);

	~~Argument~~ "-x" passed to in_pszOptions means "extended" stats query (provides more detailed stats in some cases, like individual circuits)		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.		For more information on "pMyStatPipe", please read documentation from the header files in the code.

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

← Older revision		Revision as of 10:12, 25 October 2013
Line 24:		Line 24:

	The command-line tool will also allow getting a list of available paths:		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:		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:		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:		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:		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):		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.		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:		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:		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.		To query individual field value, you add "::" after the path, then specify the specific field name.
	For example:		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):		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).		* 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).