myarmquery

Documentation / C# Edition / User Guide / Tools / myarmquery

myarmquery -- displays applications and transaction instances

This section describes the myarmquery command line tool to submit queries to a MyARM data source. This tool allows query to any MyARM data source (database) selecting instances of applications and transactions measured by the MyARM agent. It offers various select criteria such as application and/or transaction names, start and stop time of an instance and some other attributes of these application and transaction instances. It is possible to limit the query to a maximum number of instances. For example the following example shows the output of 10 HTTP transaction measurements starting at index 120.

ruppert@myarm /opt/myarm $ myarmquery -ri 120 -rm 10 httpd
121. HTTP  40.828 ms GOOD   01.10.12 09:37:20.036 myarm.info /query
122. HTTP  43.812 ms GOOD   01.10.12 09:37:21.465 myarm.info /query
123. HTTP  41.042 ms GOOD   01.10.12 09:37:22.881 myarm.info /ticket/10
124. HTTP  94.771 ms GOOD   01.10.12 09:37:24.292 myarm.info /wiki/WikiRes...
125. HTTP  49.893 ms FAILED 01.10.12 09:37:25.900 myarm.info /wiki/about
126. HTTP 761.434 ms GOOD   01.10.12 09:55:50.362 myarm.info /wiki/TracQuery
127. HTTP 120.569 ms GOOD   01.10.12 10:03:18.445 myarm.info /changeset/1/...
128. HTTP  46.487 ms FAILED 01.10.12 10:03:26.271 myarm.info /wiki/newticket
129. HTTP  46.598 ms FAILED 01.10.12 10:03:26.399 myarm.info /newticket
130. HTTP  44.826 ms FAILED 01.10.12 10:03:26.529 myarm.info /ticket/newti...

However the program allows to format the output of each application and transaction instance by specifying an printf() like format string. The following sections describes the supported command line options, optional configuration file properties and the supported format specifiers for formatting a transaction and formatting an application output.

Command line options

Usage:

myarmquery [options] [appName][:tranName] [appName2][:tranName2] ...
appName:tranName, appName2:tranName2
specifies the application and/or transaction name(s) to be queried. For details about specifying application and/or transaction names read the section "Application and transaction names".

In addition to the options listed below, the myarmquery command supports standard options described in appendix "Standard options", the constraint options in appendix "Constraints options" and the sorting options in appendix "Sorting options".

Selection criteria options

-a, --apps
selects query of application instances.
-t, --trans
selects query of transaction instances, which is the default behaviour.
-D, --dropped
selects query of dropped transaction instances
-r, --rts
selects query of real time statistics data
-e, --rte
selects query of runtime events

Display options

-c, --children
indicates, that each child (sub) transaction should be displayed as well. Note that this only work if you have generated the correlation information within the database by using the myarmcorrelate command.
-rm num, --result-max num
specifies a maximum number of application or transaction instances to display.
-ri num, --result-index num
specifies the number of application or transaction instances to skip and start printing with the instance at index number num.
-rp num, --result-page num
specifies the number of application or transaction instances to display per page. When the number of transactions is reached the program will prompt you to hit the return key.

Output formatting options

In addition to the standard formatting options myarmquery supports also the following options:

-li string, --level-indent string
Uses string instead of a normal space character
-tf string, --tran-format string
Uses string as the transaction formatting template (See below).

Default is specified by the tools.query.tranformat.

-af string, --app-format string
Uses string as the application formatting template (See below).

Default is specified by the tools.query.appformat.

RTS data options

The following options are used to specify additional constraints querying RTS data:

-i ival, --interval ival
defines the interval (in minutes) for retrieving (aggregating) RTS data. Possible values are 1, 5, 15, 30, 60, hour, day, week, month and year.

Transaction instance formatting

Formatting a transaction instance output can be modified by a so-called format string. This string specifies plain text which is directly copied one by one to the resulting output and so-called format specifiers which inserts transaction specific information into the output. There are the following characters which introduce a format specifier:

%
introduces transaction specific insertion
&, \
introduces layout specific insertion

Also the formatting supports to insert contents of environment variables. This can be done by specifying $(var) or ${ var} where var stands for the environment variable name.

Here is the list of all support transaction specifiers:

%a
prints the arrival time of the transaction.
%A
prints the system address of the transaction.
%b
prints the blocked time of the transaction.
%c
prints the context values associated with this transaction.
%d
prints the diagnostic detail string associated with the transaction.
%e
prints the plain net response time in nanoseconds without any unit string (analogue to "%r").
%E
prints the plain net response time in nanoseconds without any unit string (analogy to "%R").
%g
within parent/child transaction chains the percentage of the current transaction in relation to the complete chain.
%G
prints the application group the transaction belongs to.
%h
prints the handle of the transaction (in hexadecimal encoding).
%H
prints the application handle of the transaction (in hexadecimal encoding).
%i
prints the ID of the transaction.
%I
prints the ID of the associated application.
%J
prints the application instance the transaction was executed on.
%k
prints the database key of the transaction.
%Xm
prints the X metric of the transaction, where X is between 1 and 7
%n
prints the transaction name of the transaction.
%N
prints the application and transaction name delimited by a colon (':').
%p
prints the start time of the transaction.
%P
prints the stop time of the transaction.
%q
prints the start date of the transaction.
%Q
prints the stop date of the transaction.
%r
prints the net response time of the transaction that is the response time minus the blocking plus the arrival time.
%R
prints the raw response time without any adjustments (blocking, arrival time).
%s
prints the status of the transaction in descriptive text.
%S
prints the status of the transaction (numerical).
%u
prints the URI of the transaction.
%U
prints the associated user name of the transaction, if any.
%x
prints the start time of the transaction as milliseconds since 1.1.1970.
%X
prints the stop time of the transaction as milliseconds since 1.1.1970.
%z
prints the normalized response time if available. Normalized response time is calculated by dividing the response time by the metric value marked as the transaction size metric.

And here the layout specifiers:

&l
indent sub-transactions
&n
number of current transaction
\t
tabulator
\n
new line

Application instance formatting

Formatting an application instance output can be modified by a so-called format string. This string specifies plain text which is directly copied one by one to the resulting output and so-called format specifiers which insert application specific information into the output. There are the following characters which introduce a format specifier:

%
introduces application specific insertion
&, \
introduces layout specific insertion

Also the formatting supports to insert contents of environment variables. This can be done by specifying $(var) or ${var} where var stands for the environment variable name.

Here is the list of all support application specifiers:

%A
prints the system address of the transaction.
%c
prints the context values associated with this application.
%g
prints the associated group name.
%h
prints the handle of the application.
%i
prints the associated instance name.
%I
prints the ID of the application.
%k
prints the database key of the application.
%n
prints the name of the application.
%p
prints the start time of the application.
%P
prints the stop time of the application.
%q
prints the start date of the application.
%Q
prints the stop date of the application.
%r
prints the running time of the application.
%x
prints the start time in milliseconds since 1.1.1970.
%X
prints the stop time in milliseconds since 1.1.1970.

Configuration properties

The following properties can be used to configure the myarmquery tool within the standard MyARM configuration file.

tools.rtformat
Specifies the response time display entity. (See appendix "Configuring response time formats")
tools.query.max
Maximum number of results are set to val.
tools.query.child.indent
Specifies the string to use for indentation of child transactions.
tools.query.tranformat
Specifies the formatting string for transactions.

Default is "&l&n. %n\t%r\t%s\t%q %p %A %U %c %0m %1m\n".

tools.query.appformat
Specifies the formatting string for transactions.

Default is "&n. %n\t%q %p\t%r\t%A\t%g\t%i %c\n".

See Also
myarmoptions, myarmdefinition, myarmcorrelate, myarmdelete, myarmconfig