Configuration

Documentation / Web Edition / User Guide / Appendix / Configuration
 

Introduction

The configuration of the MyARM agent library is done mainly through configuration files which contain so-called named value pairs or just called properties. Each property is specified in one or more lines of the file in the following form:

name = value

where at least the name and the sign character have to be in the first line. Line concatenation have to be introduced by a backslash character at the end of a line. The name can be compound hierarchically by separating name parts with dots:

agent.sink.name = db_mysql

This examples assigns the value of db_mysql to the property name agent.sink.name which consists of the three parts agent, sink and name. One use of these hierarchical names is to unify the configuration of one component within the system by its first name part. In the above example the first name part is agent which means its a property of the agent library component of the MyARM system. The second name part sink specifies the sub-component and the third part name specifies the property of the sub-component. This configuration line configures the data sink name db_mysql to be used for the data sink of the MyARM agent.

A value can also refer to an environment variable which has to be enclosed by braces and prefixed by a dollar sign: ${VAR}. This gives you powerful possibilities in writing configuration files. For example you can write user independent configuration files.

agent.log.file = ${TMPDIR}/agent.log

To make configuration tasks easier MyARM has the ability to include other configuration files. Just add a line

include filename

in a configuration file and the file with the name filename within the configuration directory is included. The template configuration files makes use of the include mechanism.

Configuration files

There are three possibilities to specify a configuration file for an MyARM tool or an ARM instrumented application using MyARM. The first possibility overrides the following ones, etc.

  1. specifying a configuration file through the command line options: -cf conf_file or --conf-file conf_file. This is only available for MyARM tools. The ARM standard defines no way how to access command line options. Therefore it is not possible to configure an ARM instrumented application using this technique.
  2. specifying a configuration source through the $MYARM_CONFIG_URL environment variable. See section "Environment".
  3. providing the .myarmrc file in the $HOME directory of the current user.

User configuration file

MyARM provides a mechanism for user (New since "1.3.x.2") specific configuration of MyARM. If the file user.conf exists in the current configuration directory of MyARM it is loaded after all other configuration files. Each configuration property in this file will overwrite a previous loaded configuration property. Therefore the user can place any configuration property in the file which should be differ from the MyARM standard configuration.

Provided configuration files

By default MyARM provides ready to run configuration files for the all components. Thus all you need to do is to select your favorite configuration file from the templates directory and to change the values to your needs by overriding these values within the user.conf file.

Template configuration files

These template configuration files are the anchor to the MyARM configuration system and should be used with the setup.sh script or used with the MYARM_CONFIG_URL environment variable. They are located in the $MYARM_ROOT/conf/templates directory.

Under Unix like systems a symbolic link from $MYARM_ROOT/conf/<conffile> to the $MYARM_ROOT/conf/templates/<conffile> configuration file is created automatically with the setup.sh script.

Under Windows just copy (or use the mklink tool if available) the appropriate configuration file from the templates directory to the $MYARM_ROOT/conf/myarm.conf file.

mysql.conf
Main configuration file for using MyARM with a MySQL database without a Note this configuration will use the database directly from your instrumented application.
oracle.conf
Main configuration file for using MyARM with an Oracle database without a Note this configuration will use the database directly from your instrumented application.
sqlite3.conf
Main configuration file for using MyARM with a SQLite3 database without a Note this configuration will use the database directly from your instrumented application.
Main configuration file

The main configuration file includes all supported configuration properties with their default values. Thus this is the place to look for a configuration property and to copy it to the user.conf file and changing its value. Thats all.

Configuring components

Currently the following components can be configured using properties where the base prefix is specified in parentheses. free in this context means you can choose a name as you prefer (e.g. db_mysql for a MySQL database configuration):

Configuring basic attributes

Some properties are subject to all MyARM components and therefore can be configured in the basic section of the MyARM configuration. The following basic properties are available:

basic.time.use_utc (New since "1.3.x.3")
this boolean property is used to switch display of times between UTC (true) and local time (false). Default is false.
basic.sink.thread.tmpfile.name (Obsolete since "2.1.x.0")
the temporary sinkthread file concept is replaced by the generic file storage reader and writer concept.
basic.sink.thread.tmpfile.size (Obsolete since "2.1.x.0")

Basic logging configuration properties

basic.log.timefmt (New since "1.3.x.3")
specifies the format pattern to use for displaying time values. See Configuring time formats section for details.
basic.log.datefmt (New since "1.3.x.3")
specifies the format pattern to use for displaying date values. See Configuring date formats section for details.

Configuring log facility

ARM postulates that in any circumstance the instrumented application has to continue working regardless of errors within the ARM agent or with the current instrumentation. Therefore any error or inconsistency within the ARM agent has to be hidden from the application. But in many situations the instrumentor should know if an error occurred within the ARM agent. Therefore MyARM supports error and information reporting which can be configured using the following configuration keywords:

<component>.log.type
Specifies the type of the reporting facility. One of the following types can be used:
none
No reporting at all
stderr, stdout
Reports to standard error/output (file) channel. (Unix)
console
Reports to console (Windows).
file
Reports to the file specified via log.file
syslog
Reports to the system log service (Unix)
eventlog
Reports to the event log service (Windows)
<component>.log.level
Specifies the level of detail for logging. Currently the following levels are supported:
none
no logging at all
error
only log errors
warning
log warnings and errors
status
also log status information
info
some more information
config
log the read configuration of the different MyARM components
max
maximum logging information
<component>.log.datasink.level
Specifies the log level for which log messages should also be reported to the datasink (e.g. will be stored in the centralized database). Default is error.
<component>.log.file
Specifies the file to write any reporting information to.
<component>.log.file.mode
Specifies the mode to open the file specified via log.file. Mode can be either "w" to open the log file and possibly truncate the existing file or "a" to append to the existing file.
<component>.log.file.size
If log.file.generation is enabled this property specify the maximal size of the log file in bytes. If this limit is reached a new log file will be opened. Also this property specifies the size of the eventlog under Windows. Default is 1048576 (1MB).
<component>.log.file.generation
Specify the maximal number of log files which will be generated by the MyARM log component. In conjunction with the log.file.size property MyARM will not use more bytes of hard disk space than the arithmetic product of these two properties. If this property is zero the log file generation rotation is disabled and only one log file will be used. The latest log file has a suffix of .0 and the oldest log file generation has a suffix of .<generation>-1. Default is 5.
<component>.log.format
Specifies a template string used to prefix any output to the log. The following format specifier can be used:
%A
displays the name of the myarm application (e.g. myarmdaemon). For the agent log the currently used language binding is used.
%P
displays the current process id.
%H
displays the current host name.
%T
displays the internal thread id.
%C
displays the component name.
%N
displays the log message number.
%I
displays the log message ID.
%M
displays the log message. If this specifier is omitted the log message is appended at the end of the line.
<component>.log.show.level
Indicates that the log level should be logged (true) or not (false).
<component>.log.show.time
Indicates that the time of the log should be logged (true) or not (false).
<component>.log.flush
Specifies, if true, that after each log message a flush should be performed so that it is immediately written to its destination without any buffering. For error log messages this is always true.
<component>.log.syslog.facility (New since "2.1.x.1")
Specifies the facility to use for syslog service. It supports 'local0' to 'local7' and 'user'. Default is 'user'.

Configuring command line tools

The following configuration properties are used to change the behaviour of all command line tools.

tools.source.name
configures the name of the data source to be used.

Configuring web user interfaces

The following configuration properties are used to change the behaviour of all web user interfaces and the myarmbrowser specifically.

tools.web.user.admin (New since "3.0.x.1")
specifies the user name who has administrator rights. With administrator rights the order of selection and the time interval can be pre-defined for any other user.

Default is "" (empty means there is no administrator user).

tools.web.user.pre-defined (New since "3.0.x.1")
specifies a defined user name. Normally this property is left blank but if specified this user name is used for all sessions thus allowing a demostration or an application domain specific pre-defined user.

Default is "" (empty means there is no pre-defined user).

tools.web.browser.sidebar.percentile (New since "3.0.x.1")
specifies the default percentile to show in the SideBar statistics panel. A value of -1 hides the percentile row, a value between 0 and 99 defines the default percentile. The percentile can be changed by clicking on the label and selecting a new percentile from the shown list.

Default is -1.

tools.web.browser.timeinterval.min (New since "2.1.x.0")
specifies the minimum interval which can be used by the user in the single date selection mode in minutes.

Default is 1.

tools.web.browser.timeinterval.max (New since "2.1.x.0")
specifies the maximum interval which can be used by the user in the single date selection mode in minutes.

Default is 1440 (one day).

tools.web.browser.url (New since "3.0.x.1")
specifies the base URL where the myarmbrowser is running. This property is used by the myarmrtsbrowser and myarmrtsmonitor application to invoke the myarmbrowser to dig into raw data.

Default is http://localhost:8081/.

Configuring time formats

Time values can be represented in various ways. MyARM supports the following time formatting patterns:

HH:MM:SS
hour:minute:second for example 16:29:37 for nearly half past five in the afternoon.
HH:MM:SS.ZZZ
hour:minute:second.millisecond for example 16:29:37.546 for nearly past five in the afternoon including millisecond precision.
HH:MM:SS AP
hour:minute:second in 12-hour clock notation for example 04:29:37 PM for nearly half past five in the afternoon.
HH:MM:SS.ZZZ AP
hour:minute:second.millsecond in 12-hour clock notation for example 04:29:37 PM for nearly half past five in the afternoon including millisecond precision.

Configuring date formats

Date values can be represented in various ways. MyARM supports the following date formatting patterns:

DD.MM.YYYY
day.month.year for example 11.12.2009 for the eleventh december 2009.
YYYY-MM-DD
year-month-day for example 2009-12-11 for the eleventh december 2009.
MM/DD/YYYY
month/day/year for example 12/11/2009 for the eleventh december 2009.
DD.MM.YY
day.month.year with two digit year; for example 11.12.09 for the eleventh december 2009.
YY-MM-DD
year-month-day with two digit year; for example 09-12-11 for the eleventh december 2009.
MM/DD/YY
month/day/year with two digit year; for example 12/11/09 for the eleventh december 2009.

Configuring response time formats

Response times can be in a wide range of time intervals according to their corresponding transactions. For long running transactions it is not useful to display the response time in micro- or even nanoseconds. But if you want to measure low level transaction it may be necessary to use such short time units. For this purpose you can configure how MyARM tools display and parse response times:

<component>.rtformat= rtfmt
configures response time format of rtfmt in the configuration file for the specified component.
-rf rtfmt , --rt-fmt rtfmt
configures response time format of rtfmt on command line for various tools.

rtfmt can be one of the following strings (letters in parentheses can be omitted):

ns
response times in nanoseconds
mic(s)
response times in microseconds
ms
response times in milliseconds, nanoseconds remainder are omitted
s(ec)
response times in seconds, nanoseconds remainder are omitted
m(in)
response times in minutes, microseconds remainder are omitted
h(our)
response times in hours, microseconds remainder are omitted
d(ay)
response times in days, milliseconds remainder are omitted

Configuring sorting criteria

When operating on a set of application or transaction data it might be good in some circumstances that you can sort the output. For this purpose you can configure the sorting of application and transaction data within the configuration file or as a command line option:

<component>.sort.criteria=criteria
Configures the specified component to use the given sort criteria. See below.
-sb criteria, --sort-by criteria
Specifies the sort criteria. See below.

Currently valid sorting criteria are:

None
no sorting at all
Start
sorting by start time of the transactions
Stop
sorting by stop time of the transactions
Duration
sorting by response time of the transactions
Arrival
sorting by arrival time of the transactions
Blocked
sorting by blocked time of the transactions