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

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:

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.
stop([in, optional] contextId);
fail([in, optional] contextId);
setTag([in] tagName, [in, optional] contextId);
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.

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.

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.

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.

A valueName is limited to 32 characters.

BTM COM Interface Properties

The COM interface for BTM has six properties:

userName [in];
domain [in];
transactionGroup [in];
OEMTarget [in];
version [out];
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.

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.

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.

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.

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:

[
object,
uuid(4FF37F23-9EF1-4a2f-95D5-F8E88BE8687D),
dual,
helpstring("ITransactionHelper Interface"),
pointer_default(unique)
]

interface ITransactionHelper : IDispatch
{
[id(1), helpstring("method start")]
HRESULT start([in] VARIANT transactionName, [in,optional] VARIANT customId, [out, retval] VARIANT* contextId);
[id(2), helpstring("method stop")]
HRESULT stop([in,optional] VARIANT contextId);
[id(3), helpstring("method setTag")]
HRESULT setTag([in] VARIANT tagName, [in, optional] VARIANT contextId);
[id(4), helpstring("method setValue")]
HRESULT setValue([in] VARIANT valueName, [in] float value, [in, optional] VARIANT contextId);

[id(5), helpstring("method fail")]
HRESULT fail([in,optional] VARIANT contextId);
[propput, id(6), helpstring("property userName")] HRESULT userName([in] VARIANT userName);
[propput, id(7), helpstring("property domain")] HRESULT domain([in] VARIANT userDomian);
[propput, id(8), helpstring("property transactionGroup")] HRESULT transactionGroup([in] VARIANT transGroup);
[propput, id(9), helpstring("property OEMTarget")] HRESULT OEMTarget([in] VARIANT OEMName);
[propget, id(10), helpstring("property version")] HRESULT version([out, retval] VARIANT *pVal);
[propget, id(11), helpstring("property ignoreErrors")] HRESULT ignoreErrors([out, retval] BOOL *pVal);
[propput, id(11), helpstring("property ignoreErrors")] HRESULT ignoreErrors([in] BOOL newVal);
};

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_
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

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:
start

Mark the end of a measurement:
stop

Mark the end of an unsuccessful measurement:
fail
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):
measure

Parameters

Parameters are case-sensitive

The name of the transaction:
transaction=<transaction name>
The name of a transaction group:
transactionGroup=<transaction group name>
The name of the logged-in user:
userName=<user name>
The domain that the logged-in user belongs to:
userDomain=<user domain name>
Information about the transaction in the form of a tag:
tag=<tag name>

The name of a value (must be used together with the value parameter):
valuename=<Name of value>

A value (must be used together with the valuename parameter):
value=<value>
The duration of an already known measurement (used with the measure command):
duration=<duration in seconds>
The result of an already known measurement (used with the measure command):
result=<result>

I have used BTMUtil before. Where is the ID parameter?

When you use the REST interface, you supply the transaction ID number as part of the URL (unlike BTMUtil where you supply the ID as a separate parameter). View an example of a ID supplied as part of a URL in BTM REST Interface Usage Examples in the following.

I have used BTMUtil before. Where is the ID file parameter?

You can't use ID files with the REST interface.

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:"

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.
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:

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:

curl "http://localhost:4007/btm/12345/stop?tag=AllTestsPassed"

... or this one if two of the tests failed:

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:

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:

curl "http://localhost:4007/btm/measure?transaction=ProductA_Build&transactionGroup=Builds&userName=bob&userDomain=softwarecompany&result=fail&duration=500"

You must include the URL in quotation marks like in the examples.

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:
-start (Default : false.)
Mark the end of a measurement:
-stop (Default : false.)
Mark the end of an unsuccessful measurement :
-fail (Default : 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:
-name=<transaction name> (Default : BTMUtil Test Transaction.)
BTMUtil will also understand the -transaction parameter.
The name of a transaction group:
-groupname=<transaction group name> (Default : BTM Util Test group.)
BTMUtil will also understand the -transactionGroup parameter.
The name of the logged-in user:
-user=<user name> (Default : hsloth.)
BTMUtil will also understand the -userName parameter.
The domain that the logged-in user belongs to:
-domain=<user domain name> (Default : PREMITECH.)
BTMUtil will also understand the -userDomain parameter.
Information about the transaction in the form of a tag:
-tag=<tag name>
The name of a value (must be used together with the value parameter):
-valuename=<Name of value>
A value (must be used together with the valuename parameter):
-value=<value> (Default : 0.000000)
A transaction ID number:
-id=<id> (Default : 2147483647.)
A transaction ID file:
-idfile=<File for Id> (Default : id.txt.)

BTMUtil Help Options

Print normal options:
-? (Default : false.)
List all options:
-?? (Default : false.)
Print usage examples:
-examples (Default : false.)

BTMUtil Debug Options

Print all messages in the queue:
-Dump (Default : false.)

Show the number of messages every two seconds:
-Header (Default : false.)

Insert a number of messages in the queue:
-Put=<num.messages> (Default : 0.)

BTMUtil Usage Examples

Make a measurement with an ID and set a value:

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:

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:

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.

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).

When is something considered to be available?

To answer this we need to look at response times: If response times are so long that use of a service, website, transaction or similar becomes impossible, PerformanceGuard considers the service, etc. to be unavailable. By default, PerformanceGuard loses its patience with a service, etc. if it hasn't responded within 500,000 milliseconds (that's a little more than eight minutes). Everything that's not unavailable, is considered by PerformanceGuard to be available. So, if you see that a service has been 100% available during the last week, it means that it has not exceeded the acceptable response time limit during the last week.

Do you measure availability of application pings (HTTP requests, ICMP ping and/or traceroutes)?

For application pings, PerformanceGuard looks not only at acceptable response times, but also at whether a response is expected or not: If the response is unexpected, for example if the response has a response code of 404 Not Found, PerformanceGuard considers the service to be unavailable, even if the response was received within acceptable time.

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.

Search this documentation

On this page

In this section

Browser not supported