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.

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.

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:

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

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:

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

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 

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

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

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.

   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:

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:

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

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

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/Agents bar chart (ANALYZE > Graphs > Combined Bar Charts > BTM Tags/Agents).

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.