# Monitor Complex Activity with AutoSteps > Use AutoSteps to measure activities that span several steps or servers, beyond single-transaction response times. Source: https://docs.capaone.com/performanceguard/administration/more-setup/monitor-complex-activity-with-autosteps/ Product: PerformanceGuard — a separate CapaSystems product; do not apply this page to any other. :::caution 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. :::note[Important] 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. :::note[Important] 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: - > [!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. :::caution 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. :::caution 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. :::caution A valueName is limited to 32 characters. ::: ## **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. :::caution 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. :::caution 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. :::caution 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. :::caution 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: :::note[Important] \[ 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 \_ :::caution 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: :::note[Important] start ::: - Mark the end of a measurement: :::note[Important] stop ::: - Mark the end of an unsuccessful measurement: :::note[Important] fail ::: :::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%. ::: - Convey a measurement (if the result of a measurement is already known, and no start and stop commands are therefore needed): :::note[Important] measure ::: ### Parameters :::caution Parameters are case-sensitive ::: - The name of the transaction: :::note[Important] transaction=\ ::: - The name of a transaction group: :::note[Important] transactionGroup=\ ::: - The name of the logged-in user: :::note[Important] userName=\ ::: - The domain that the logged-in user belongs to: :::note[Important] userDomain=\ ::: - Information about the transaction in the form of a tag: :::note[Important] tag=\ ::: 1. The name of a value (must be used together with the value parameter): :::note[Important] valuename=\ ::: - A value (must be used together with the valuename parameter): :::note[Important] value=\ ::: - The duration of an already known measurement (used with the measure command): :::note[Important] duration=\ ::: - The result of an already known measurement (used with the measure command): :::note[Important] result=\ ::: :::note[Important]
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.
::: :::note[Important]
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:" :::note[Important] 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**](http://en.wikipedia.org/wiki/CURL). When you use cURL, you type curl followed by the required URL. :::note[Important]
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: :::note[Important] 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: :::note[Important] curl "http://localhost:4007/btm/12345/stop?tag=AllTestsPassed" ::: ... or this one if two of the tests failed: :::note[Important] 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: :::note[Important] 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: :::note[Important] curl "http://localhost:4007/btm/measure?transaction=ProductA\_Build&transactionGroup=Builds&userName=bob&userDomain=softwarecompany&result=fail&duration=500" ::: :::caution You must include the URL in quotation marks like in the examples. ::: :::caution 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: :::note[Important] -start (Default : false.) ::: - Mark the end of a measurement: :::note[Important] -stop (Default : false.) ::: - Mark the end of an unsuccessful measurement : :::note[Important] -fail (Default : false.) ::: :::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%. ::: - The name of the transaction: :::note[Important] -name=\ (Default : BTMUtil Test Transaction.) ::: BTMUtil will also understand the -transaction parameter. - The name of a transaction group: :::note[Important] -groupname=\ (Default : BTM Util Test group.) ::: BTMUtil will also understand the -transactionGroup parameter. - The name of the logged-in user: :::note[Important] -user=\ (Default : hsloth.) ::: BTMUtil will also understand the -userName parameter. - The domain that the logged-in user belongs to: :::note[Important] -domain=\ (Default : PREMITECH.) ::: BTMUtil will also understand the -userDomain parameter. - Information about the transaction in the form of a tag: :::note[Important] -tag=\ ::: - The name of a value (must be used together with the value parameter): :::note[Important] -valuename=\ ::: - A value (must be used together with the valuename parameter): :::note[Important] -value=\ (Default : 0.000000) ::: - A transaction ID number: :::note[Important] -id=\ (Default : 2147483647.) ::: - A transaction ID file: :::note[Important] -idfile=\ (Default : id.txt.) ::: ### **BTMUtil Help Options** - Print normal options: :::note[Important] -? (Default : false.) ::: - List all options: :::note[Important] -?? (Default : false.) ::: - Print usage examples: :::note[Important] -examples (Default : false.) ::: ### **BTMUtil Debug Options** - Print all messages in the queue: :::note[Important] -Dump (Default : false.) ::: 1. Show the number of messages every two seconds: :::note[Important] -Header (Default : false.) ::: - Insert a number of messages in the queue: :::note[Important] -Put=\ (Default : 0.) ::: ## **BTMUtil Usage Examples** Make a measurement with an ID and set a value: :::note[Important] 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: :::note[Important] 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: :::note[Important] 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*](http://localhost:4007). In the agent information window that opens, select **View > BTM Data**. ![](/attachments/performanceguard/2e886215-2b3f-46ec-b97d-25aca0579e15.png) :::caution 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 and Agents](/performanceguard/analyze/btm-tags-and-agents/) (**ANALYZE > Graphs > Combined Bar Charts > BTM Tags/Agents**). :::note[Important]
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 *un*available. 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 *un*available, 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/administration/manage-agent-configuration-groups/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 *un*available, 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.