myarmquery -- displays application and transaction instances

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

$ 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 instance by specifying a printf() like format string. The following sections describe 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

-t, --trans

selects query of transaction instances, which is the default behaviour.

-a, --apps

selects query of application instances.

-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 works 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 also supports the following options:

-dtf string , --date-fmt string

specifies the date format in string for formatting and parsing dates. See "Configuring date formats" for details.

The default is specified by the basic.time.format configuration property.

-tmf string , --time-fmt string

specifies the time format in string for formatting and parsing times. See "Configuring time formats" for details.

The default is specified by the basic.time.date.format configuration property.

-rf string , --rt-fmt string

specifies the response time format in string for printing and parsing response times. See "Configuring response time formats" for details.

The default is specified by the tools.rtformat configuration property.

-li string, --level-indent string

Uses string instead of a normal space character for indentation.

Default is " " (two spaces).

-tf string, --tran-format string

Uses string as the transaction formatting template (See below).

The default is specified by the tools.query.tranformat configuration property.

-af string, --app-format string

Uses string as the application formatting template (See below).

The default is specified by the tools.query.appformat configuration property.

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 insert transaction specific information into the output. These are the characters which introduce a format specifier:

%

introduces transaction specific insertion

&, \

introduces layout specific insertion

Also the formatting supports to the insertion if the 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 supported transaction specifiers:

%a

prints the arrival time of the transaction

%A

prints the hostname (system address) of the transaction

%b

prints the blocked time of the transaction

%B

prints the detailed blocking times of the transaction

%c

prints the context values associated with this transaction

%d

prints the diagnostic detail string associated with the transaction

%Xe

prints the plain net response time in nanoseconds without any unit string (similar to "%r"). If X is specified, it specifies that the time is to be divided by 10 to the power X (e.g. %3e results in microsecond resolution).

%XE

prints the plain raw response time in nanoseconds without any unit string (similar to "%R"). If X is specified, it specifies that the time is to be divided by 10 to the power X (e.g. %3E results in microsecond resolution).

%g

within parent/child transaction chains it will print the percentage of the current transaction in relation to the complete chain

%G

prints the application group the transaction belongs to

%h

prints the hostname (system address) of the transaction

%H

prints the application instance ID of the transaction (in hexadecimal encoding)

%i

prints the ID of the transaction definition

%I

prints the ID of the associated application definition

%J

prints the application instance the transaction was executed on

%k

prints the transaction instance ID, also known as the correlation ID

%K

prints the parent transaction instance ID also known as the parent correlation ID

%Xm

prints the X metric of the transaction, where X is a number 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 as descriptive text

%S

prints the one letter status of the transaction

%t

prints the thread ID the transaction was executed on (if available)

%T

prints the thread name the transaction was executed on (if available)

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

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

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

Threshold statistics

Selecting threshold statistics will output a summary of activated measurement thresholds. For example executing the following myarmquery command on our myarm.info measurement database will print out the following lines:

$ myarmquery --utc --thresholds -sf "30.10.12" -su "31.10.12"
1351616640,PyCDDB:DB-Connect,30ms,136ms,1,1
1351555860,httpd:HTTP,1000ms,8395ms,15,637
1351616640,PyCDDB:CDDB-Query,100ms,247ms,1,1
1351616640,PyCDDB:Fetch-Tracks,5ms,36ms,4,20
1351616640,PyCDDB:Generate-Output,5ms,12ms,1,1
1351616640,PyCDDB:Generate-Output,myarm.info,5ms,12ms,1,1
1351616640,PyCDDB:DB-Connect,myarm.info,30ms,136ms,1,1
1351616640,PyCDDB:CDDB-Query,myarm.info,100ms,247ms,1,1
1351555860,httpd:HTTP,myarm.info,1000ms,8395ms,15,637
1351616640,PyCDDB:Fetch-Tracks,myarm.info,5ms,36ms,4,20

The result consists of lines with columns separated with a comma charater. There are either lines with 6 or 7 columns. Lines with 6 columns represents threshold statistics for all systems and lines with 7 columns is the result for the specific system as specified in the third column (here myarm.info). The following list describes the columns briefly:

Lines with 6 columns:

1. UTC timestamp in seconds since epoch
2. Application and transaction name delimited by a colon
3. Threshold in milliseconds
4. Maximum response time in milliseconds of the requested interval
5. Number of measurements exceeded their threshold
6. Total number of measurements of the requested interval

Lines with 7 columns:

1. UTC timestamp in seconds since epoch
2. Application and transaction name delimited by a colon
3. System the measurements were recorded
4. Threshold in milliseconds
5. Maximum response time in milliseconds of the requested interval
6. Number of measurements exceeded their threshold
7. Total number of measurements of the requested interval

See Also