| Note | ||
|---|---|---|
| ||
You can only do this if you're a PerformanceGuard administrator. |
PerformanceGuard by default measures response times for single transactions against a single server.
If you want to monitor more complex activities that involve several steps or several servers, you must specify where activities begin and end, so that PerformanceGuard can record the execution time.
This is where the PerformanceGuard AutoSteps feature is useful.
It essentially works as a stop watch that lets you time any event or business transaction on your client and view response times in the PerformanceGuard web interface.
This way, AutoSteps can help you easily identify bottlenecks in your business processes, even when processes are complex.
The most common use of AutoSteps is in Citrix login scripts and scriptable application clients, like Lotus Notes, or inside your client application code.
To make AutoSteps response time measurements, you can either:
Use a COM interface from a command line on a computer that has the PerformanceGuard agent installed.
Info icon false COM, Component Object Model, is computer language-neutral way to make objects that can be used in other environments than the one in which they were created. A COM interface thus basically lets you take information from one system and use it in another system.
Use a REST interface directly from a web browser on a computer that has the PerformanceGuard agent installed.
The REST interface is primarily useful when you need to measure browser-based transactions.
Info icon false REST, REpresentational State Transfer, is a simple stateless web interface that uses XML and HTTP. Like COM, REST basically lets you take information from one system and use it in another system.
- Use BTMUtil.exe, a small tool that's installed together with the PerformanceGuard agent.
This is useful when you want to test your installation and when you want to time events in local scripts.
BTM via COM Interface
The COM interface for AutoSteps is called ITransactionHelper. It's installed and registered together with the default installation of the PerformanceGuard agent. If you're used to COM interfaces, ITransactionHelper is straightforward and allows a quick and safe way to store information about business transactions in the PerformanceGuard database.
| Tip | ||
|---|---|---|
| ||
The ITransactionHelper COM interface is supported by the PGExtHelper.dll component. PGExtHelper.dll includes a type library that you can use to include references to the component in various development tools. |
BTM COM Interface Methods
The COM for AutoSteps interface has five methods:
Info icon false The ITransactionHelper COM interface is supported by the PGExtHelper.dll component. PGExtHelper.dll includes a type library that you can use to include references to the component in various development tools.
Info icon false stop([in, optional] contextId);
Info icon false fail([in, optional] contextId);
Info icon false setTag([in] tagName, [in, optional] contextId);
Info icon false setValue([in] valueName, [in] single value, [in, optional] contextId);
start(VARIANT transactionName, VARIANT customId, VARIANT contextId)
Marks the start of the transaction with the specified transaction name, transactionName, and an optionally supplied context ID, customId. If no customId is provided, a context ID is automatically generated. The context ID can be retrieved from the contextId output parameter.
| Note | ||
|---|---|---|
| ||
A transactionName is limited to 64 characters. |
stop(VARIANT contextId)
Marks the end of a transaction with the specified context ID. If no context ID is provided, the stop event will be applied to the last transaction for which a call to the start method has been executed in the thread. If there has been a previous call to start with the same ID, the number of milliseconds that has elapsed between the two calls will be recorded.
fail(VARIANT contextId)
Marks that the transaction has failed. The contextId is optional. If no context ID is provided, the fail event will be applied to the last transaction for which a call to the start method has been executed in the thread.
| Tip | ||
|---|---|---|
| ||
When you or your colleagues later view BTM data in the PerformanceGuard web interface (see View BTM Data in PerformanceGuard Web Interface in the following), it is the amount of failed transactions that determine the transaction availability. If there are no failed occurrences of a transaction, that transaction will have an availability of 100%. |
setTag(VARIANT tagName, VARIANT contextId)
Sets an optional user-provided string value, tagName, for the transaction with the specified contextId. A specific transaction may be called with different input parameters that influence the execution time. For example, if you print something from an application, you may select to print in color or grayscale. In that case you could call the transaction itself Print and then apply the tag names Color or Grayscale when you execute the transaction. In the PerformanceGuard web interface you would then be able to view the difference in color and grayscale printing time.
If a tag value has already been set, it will be replaced with the new one. The contextId is optional. If no context ID is provided, the tag will be applied to the last transaction for which a call to the start method has been executed in the thread.
| Note | ||
|---|---|---|
| ||
A tagName is limited to 64 characters. |
setValue(VARIANT valueName, single value, VARIANT contextId)
Sets a user-provided named floating point value.
You can use valueName and a value to apply further information about the transaction. For example, tagName='Bytes printed' and value=654345 could be the number of bytes printed in a print transaction. If a value has already been inserted, the value will be overwritten.
The contextId is optional. If no context ID is provided, the value will be applied to the last transaction for which a call to the start method has been executed in this thread.
| Note | ||
|---|---|---|
| ||
A valueName is limited to 32 characters. |
BTM COM Interface Properties
The COM interface for BTM has six properties:
Info icon false userName [in];
Info icon false domain [in];
Info icon false transactionGroup [in];
Info icon false OEMTarget [in];
Info icon false version [out];
Info icon false ignoreErrors [in/out];
VARIANT userName
Identifies the user name that executes the transaction. By default the user name for the current logged-in user will be used. With this property you can overwrite the default value with a user-specified string. Only the transaction that follows will be affected.
| Note | ||
|---|---|---|
| ||
A userName is limited to 32 characters. |
VARIANT domain
Identifies the user domain. By default the domain information for the current logged-in user will be used. With this property you can overwrite the default value with a user-specified string. Only the transaction that follows will be affected.
| Note | ||
|---|---|---|
| ||
A domain is limited to 32 characters. |
VARIANT transactionGroup
This property lets you relate a transaction to a group of transactions. To do this, you specify the group name. If the group name doesn't exist in the PerformanceGuard database, it's automatically created.
| Note | ||
|---|---|---|
| ||
A transactionGroup is limited to 64 characters. |
VARIANT OEMTarget
If you have multiple PerformanceGuard agents that run on the same computer, this property lets you specify which agent instance you want to report to. By default data will be delivered to the standard (non-OEM) version of the PerformanceGuard agent.
| Note | ||
|---|---|---|
| ||
An OEMTarget is limited to 32 characters. |
VARIANT version
Text property that simply presents the version of the BTM interface.
VARIANT ignoreErrors
This Boolean property lets you suppress reports on internal BTM errors, for example an invalid argument provided to a method call. You'll typically set this property to true to make sure that errors from the BTM component won't be shown to your users.
IDL Definition
This is the IDL definition of the ITransactionHelper COM interface:
| Info | ||
|---|---|---|
| ||
[ |
BTM via REST Interface
The PerformanceGuard agent has a web interface. Most users of computers that have PerformanceGuard agents installed don't know about this, because the agent is completely transparent to them. However, you can view the PerformanceGuard agent web interface this way:
On the computer that has the PerformanceGuard agent installed, open a browser and connect to _http://localhost:4007_
Note icon false 4007 is the default port number. If the port number has been changed in your organization, PerformanceGuard administrators can view it in the PerformanceGuard web interface: Select ADMINISTRATION > Agent Configuration > Configurations, click the Edit link next to the agent configuration group that the agent belongs to, select the Agent Configuration tab, scroll down to Agent Service Parameters section and look for the Web Server TCP port number.
It's this PerformanceGuard agent web interface that you can also use for REST-based BTM. The REST interface uses a HTTP URL to transfer the required BTM commands and parameters.
BTM REST Interface Commands & Parameters
| Tip | ||
|---|---|---|
| ||
View examples of the commands and parameters in a usage context in BTM REST Interface Usage Examples in the following. |
Commands
Mark the beginning of a measurement:
Info icon false start
Mark the end of a measurement:
Info icon false stop
Mark the end of an unsuccessful measurement:
Info icon false fail
Tip icon false When you or your colleagues later view BTM data in the PerformanceGuard web interface (see View BTM Data in PerformanceGuard Web Interface in the following), it is the amount of failed transactions that determine the transaction availability. If there are no failed occurrences of a transaction, that transaction will have an availability of 100%.
Convey a measurement (if the result of a measurement is already known, and no start and stop commands are therefore needed):
Info icon false measure
Parameters
| Infonote |
|---|
Parameters are case-sensitive |
The name of the transaction:
Info icon false transaction=<transaction name>
The name of a transaction group:
Info icon false transactionGroup=<transaction group name>
The name of the logged-in user:
Info icon false userName=<user name>
The domain that the logged-in user belongs to:
Info icon false userDomain=<user domain name>
Information about the transaction in the form of a tag:
Info icon false tag=<tag name>
The name of a value (must be used together with the value parameter):
Info icon false valuename=<Name of value>
A value (must be used together with the valuename parameter):
Info icon false value=<value>
The duration of an already known measurement (used with the measure command):
Info icon false duration=<duration in seconds>
The result of an already known measurement (used with the measure command):
Info icon false result=<result>
| Info | |||||
|---|---|---|---|---|---|
| |||||
|
| Info | |||||
|---|---|---|---|---|---|
| |||||
|
BTM REST Interface Usage Examples
In this example a software company uses BTM to measure the time it takes to build a new version of their software, and whether the build process is successful or fails. The PerformanceGuard agent is installed on the server that builds the software version. When the server begins to build a new software version, a script that runs on the server sends the following string on the REST interface to make the PerformanceGuard agent start its BTM "stop watch:"
| Info | ||
|---|---|---|
| ||
curl "http://localhost:4007/btm/12345/start?transaction=ProductA_Build&transactionGroup=Builds&userName=bob&userDomain=softwarecompany" |
This is what the individual elements of the string mean:
curl refers to free open source command line tool cURL. When you use cURL, you type curl followed by the required URL.
Info icon false Expand title Do I need to use cURL? No, other tools that can transfer HTTP content may work equally well. cURL is merely the tool that we used when we documented these examples.
- http://localhost:4007 refers to the web interface of the PerformanceGuard agent installed on the server.
- btm simply means that the string concerns BTM.
- 12345 is ID of the transaction to be measured.
- start means that the string marks the start of the transaction.
- transaction=ProductA_Build indicates the transaction name. In this case the server builds the software company's Product A (they also have a Product B).
- transactionGroup=Builds means that the transaction belongs to a group of transactions called Builds. This parameter isn't strictly necessary, but it can be useful if you want to group similar transactions.
- userName=bob indicates the user name of the user who is logged in on the server.
- userDomain=softwarecompany indicates the domain that the logged-in user belongs to.
When the server has built the new software version, it sends this string to stop the transaction measurement on the PerformanceGuard:
| Info | ||
|---|---|---|
| ||
curl "http://localhost:4007/btm/12345/stop" |
Based on the start and stop strings PerformanceGuard can then calculate how long it has taken to build the new software version.
It's possible to add further information to the strings, For example, the software company runs a number of tests when they build new software versions. In that case the script that runs on the server could add this tag to the stop string if all tests were successful:
| Info | ||
|---|---|---|
| ||
curl "http://localhost:4007/btm/12345/stop?tag=AllTestsPassed" |
... or this one if two of the tests failed:
| Info | ||
|---|---|---|
| ||
curl "http://localhost:4007/btm/12345/stop?tag=2TestsFailed" |
The software company's build server may itself know how long it took to complete the build. In that case, the software company could use the measure command to convey the time measurements. Here's an example of a string that represents a successful build that took 200 seconds:
| Info | ||
|---|---|---|
| ||
curl "http://localhost:4007/btm/measure?transaction=ProductA_Build&transactionGroup=Builds&userName=bob&userDomain=softwarecompany&result=ok&duration=200" |
... and here's an example of an unsuccessful build that took 500 seconds:
| Info | ||
|---|---|---|
| ||
curl "http://localhost:4007/btm/measure?transaction=ProductA_Build&transactionGroup=Builds&userName=bob&userDomain=softwarecompany&result=fail&duration=500" |
| Note | ||
|---|---|---|
| ||
You must include the URL in quotation marks like in the examples. |
| Note | ||
|---|---|---|
| ||
The & character is used to separate parameters in the URL. Because of this, the parameters themselves mustn't include the & character. For example, a transaction mustn't have the name Red&Blue. |
BTM via BTMUtil.exe
BTMUtil.exe is a small tool that's installed together with the PerformanceGuard agent. This is useful when you want to test your installation and when you want to time events in local scripts.
BTMUtil Commands and Parameters
Mark the beginning of a measurement:
Info icon false -start (Default : false.)
Mark the end of a measurement:
Info icon false -stop (Default : false.)
Mark the end of an unsuccessful measurement :
Info icon false -fail (Default : false.)
Tip icon false When you or your colleagues later view BTM data in the PerformanceGuard web interface (see View BTM Data in PerformanceGuard Web Interface in the following), it is the amount of failed transactions that determine the transaction availability. If there are no failed occurrences of a transaction, that transaction will have an availability of 100%.
The name of the transaction:
Info icon false -name=<transaction name> (Default : BTMUtil Test Transaction.)
BTMUtil will also understand the -transaction parameter.
The name of a transaction group:
Info icon false -groupname=<transaction group name> (Default : BTM Util Test group.)
BTMUtil will also understand the -transactionGroup parameter.
The name of the logged-in user:
Info icon false -user=<user name> (Default : hsloth.)
BTMUtil will also understand the -userName parameter.
The domain that the logged-in user belongs to:
Info icon false -domain=<user domain name> (Default : PREMITECH.)
BTMUtil will also understand the -userDomain parameter.
Information about the transaction in the form of a tag:
Info icon false -tag=<tag name>
The name of a value (must be used together with the value parameter):
Info icon false -valuename=<Name of value>
A value (must be used together with the valuename parameter):
Info icon false -value=<value> (Default : 0.000000)
A transaction ID number:
Info icon false -id=<id> (Default : 2147483647.)
A transaction ID file:
Info icon false -idfile=<File for Id> (Default : id.txt.)
BTMUtil Help Options
Print normal options:
Info icon false -? (Default : false.)
List all options:
Info icon false -?? (Default : false.)
Print usage examples:
Info icon false -examples (Default : false.)
BTMUtil Debug Options
Print all messages in the queue:
Info icon false -Dump (Default : false.)
Show the number of messages every two seconds:
Info icon false -Header (Default : false.)
Insert a number of messages in the queue:
Info icon false -Put=<num.messages> (Default : 0.)
BTMUtil Usage Examples
Make a measurement with an ID and set a value:
| Info | ||
|---|---|---|
| ||
c:\>BTMUtil -start -id=100 -valuename=ByteCount -value=25000c:\>rem Do some stuff herec:\>BTMUtil -stop -id=100 |
Make a measurement and create and store the ID in a file:
| Info | ||
|---|---|---|
| ||
c:\>del context.txtc:\>BTMUtil -start -idfile=context.txtc:\>rem Do some stuff herec:\>BTMUtil -valuename=ByteCount -value=25000 -idfile=context.txtc:\>BTMUtil -stop -idfile=context.txt |
Make a measurement, assign a tag and a value, and mark it as failed:
| Info | ||
|---|---|---|
| ||
c:\>BTMUtil -start -user=John -domain=ourcompany -id=9876c:\>BTMUtil -tag=pricelist -id=9876c:\>BTMUtil -valuename=length -value=25.4 -id=9876c:\>BTMUtil -fail -id=9876 |
View BTM Data in Agent Web Interface
You can view BTM data locally on a client: On the computer that has the PerformanceGuard agent installed, open a browser and connect to http://localhost:4007. In the agent information window that opens, select View > BTM Data. 
| Note | ||
|---|---|---|
| ||
4007 is the default port number. If the port number has been changed in your organization, PerformanceGuard administrators can view it in the PerformanceGuard web interface: Select ADMINISTRATION > Agent Configuration > Configurations, click the Edit link next to the agent configuration group that the agent belongs to, select the Agent Configuration tab, scroll down to Agent Service Parameters section and look for the Web Server TCP port number. |
View BTM Data in PerformanceGuard Web Interface
To compare availability, etc. for transactions across groups of computers in the PerformanceGuard web interface, use the BTM Tags/Agents bar chart (ANALYZE > Graphs > Combined Bar Charts > BTM Tags/Agents).
| Info | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Backward Compatibility
You may occasionally see that the BTM feature is referred to as version 2 of BTM. This is because a now deprecated version 1 was used some years ago.
To ensure backward compatibility all recent PerformanceGuard agent versions also support the API for the old BTM version 1.
| Panel | ||||||
|---|---|---|---|---|---|---|
Search this documentation
On this page
In this section
|