myarmquery

Documentation / Standard 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 880.

ruppert@debian:/opt/myarm$ myarmquery -ri 880 -rm 10 httpd
881. HTTP      4.959000 ms GOOD      17.06.06 18:36:13 peglin.local
882. HTTP      2.699000 ms GOOD      17.06.06 18:36:13 peglin.local
883. HTTP      6.014000 ms GOOD      17.06.06 18:36:13 peglin.local
884. HTTP      6.276000 ms FAILED    17.06.06 18:36:13 peglin.local
885. HTTP      5.087000 ms GOOD      17.06.06 18:36:13 peglin.local
886. HTTP      2.700000 ms GOOD      17.06.06 18:36:13 peglin.local
887. HTTP      6.024000 ms GOOD      17.06.06 18:36:13 peglin.local
888. HTTP      5.770000 ms GOOD      17.06.06 18:36:13 peglin.local
889. HTTP     18.319000 ms GOOD      17.06.06 18:36:13 peglin.local
890. HTTP      6.423000 ms GOOD      17.06.06 18:36:13 peglin.local

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

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

Selection criteria options
-a, --apps
selects query of application instances.
-t, --trans
selects query of transaction instances, which is the default behaviour.
-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. If the maximal number is reached to program terminates normally.
-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
-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 "&l&n. %n\t%r\t%s\t%q %p %A %U %c %0m %1m\n".
-af string, --app-format string
Uses string as the application formatting template (See below). Default is "&n. %n\t%q %p\t%r\t%A\t%g\t%i %c\n".

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 (analog to "%r").
%E
prints the plain net response time in nanoseconds without any unit string (analog 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 appliction 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.
%y
prints the asynchronous parent/child duration of transaction trees.
%y
prints the asynchronous child/parent duration of transaction trees.
%z
prints the normalised response time if available. Normalised 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.query.max
Maximum number of results are set to val.
tools.query.timeformat
Specifies the string formatting a time. See Configuring time formats section for details.
tools.query.dateformat
Specifies the string for formatting a date. See Configuring date formats section for details.
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".
tools.query.rtformat
Specifies the response time display entity. (See appendix "Configuring response time formats")
See Also
myarmoptions, myarmdefinition, myarmcorrelate, myarmdelete, myarmconfig