Monitor Complex Activity with AutoSteps

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.

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.

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.

BTM COM Interface Methods

The COM for AutoSteps interface has five methods:

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

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.

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.

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.

BTM COM Interface Properties

The COM interface for BTM has six properties:

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

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.

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.

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.

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_

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

Commands

Mark the beginning of a measurement:

Mark the end of a measurement:

Mark the end of an unsuccessful measurement:

Convey a measurement (if the result of a measurement is already known, and no start and stop commands are therefore needed):

Parameters

The name of the transaction:

The name of a transaction group:

The name of the logged-in user:

The domain that the logged-in user belongs to:

Information about the transaction in the form of a tag:

The name of a value (must be used together with the value parameter):

A value (must be used together with the valuename parameter):

The duration of an already known measurement (used with the measure command):

The result of an already known measurement (used with the measure command):

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

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.

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:

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:

… or this one if two of the tests failed:

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:

… and here’s an example of an unsuccessful build that took 500 seconds:

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:

Mark the end of a measurement:

Mark the end of an unsuccessful measurement :

The name of the transaction:

BTMUtil will also understand the -transaction parameter.

The name of a transaction group:

BTMUtil will also understand the -transactionGroup parameter.

The name of the logged-in user:

BTMUtil will also understand the -userName parameter.

The domain that the logged-in user belongs to:

BTMUtil will also understand the -userDomain parameter.

Information about the transaction in the form of a tag:

The name of a value (must be used together with the value parameter):

A value (must be used together with the valuename parameter):

A transaction ID number:

A transaction ID file:

BTMUtil Help Options

Print normal options:

List all options:

Print usage examples:

BTMUtil Debug Options

Print all messages in the queue:

Show the number of messages every two seconds:

Insert a number of messages in the queue:

BTMUtil Usage Examples

Make a measurement with an ID and set a value:

Make a measurement and create and store the ID in a file:

Make a measurement, assign a tag and a value, and mark it as failed:

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.

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 and Agents (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 Agent Configuration Group Settings, 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.