Concepts
Concepts
All MyARM supported ARM 4.0 language binding agents and analysis tools use the following concepts.
Configuration
The adaption of the MyARM agent to the current hard- and
software environment is done using a set of configuration files.
Each file contains name-value pairs, so-called configuration
properties. For example setting the basic.time.use_utc
property to true
will instruct MyARM to show time
information only in UTC.
basic.time.use_utc = true
For more and detailed information read the configuration chapter.
All MyARM agents and tools are using the MYARM_CONFIG_URL environment variable to get the configuration file.
Logging
The ARM standard is designed to transparently plugin into an instrumented application. Also, the ARM agent should never interfere with the application. The MyARM ARM agent uses log messages to report the current configuration, state changes, warnings and errors. The log messages can be written to different kinds of output media such as normal files, Windows event log or Unix syslog.
MyARM supports the following levels of log messages:
- error
- Error log messages to report errors
- warning
- Warning log messages to report some unusual situations
- status
- Status log messages to report state changes within the ARM agent
- info
- Only informational messages
- config
- Logs the configuration used by the ARM agent
For more information read the section "Configuring Log facility".
ARM data buffer
When executing an instrumented application measured and recorded ARM data is serialized and written to a so-called ARM data buffer. Therefore such an ARM data buffer can contain any kind of data like transaction response time measurements, log messages or even other kind of data like CPU utilization.
An ARM data buffer has a defined size in bytes which can be specified by a configuration property. Avoiding memory shortage due to a high rate transaction measurements, a maximum number of allocated ARM data buffers is defined. For more detailed information about configuring the ARM data buffer concept read the configuration properties section.
Handler
A handler is a technical concept for implementing filters, monitors or calculators for transaction measurements. It is used to process a measured transaction instance according to the current runtime configuration or performs additional tasks such as sending an auto response message for event flow measurements.
For a detailed description of all features implemented by handler read section handler.
Datasink
The datasink concept is used to transport and store any kind of measured and recorded ARM data in a consistent way. Datasinks within MyARM are plugins which are loaded during initialization phase according to the current configuration.
With this concept it is possible to use a chain of datasinks which will:
- store any measured data onto disk (filesink)
- read the measured data from the disk and send it to a central server using TCP/IP (tcpsink)
- finally storing the measured data into a MySQL database (mysqlsink).
For a detailed description of all available datasinks read section datasinks.
Datasource
The datasource concept defines a consistent interface to read in and manage recorded ARM data stored in a database. Like datasinks they are implemented as plugins which are loaded during runtime. Each analysis tool uses this datasource concept to retrieve the measured ARM data from the database. A datasource exists for each supported database as described in section Databases.
File storage
The file storage concept is a sub-component of the MyARM agent which is used to read and write ARM data files. The reading and writing be used separately or combined within a program. It is used to efficiently store measured ARM data onto a hard disk and retrieve the data later from the hard disk within the following programs:
- myarmdaemon
- uses the file storage concept to collect all measured ARM data for the whole host. The myarmdaemon can be started as a Windows service or an Unix daemon process to collect all measured ARM data for the whole host.
- myarmdaemon TCP server part
- can use the file storage concept to save any data received through TCP/IP onto disk. Therefore it is secured that any incoming data is first stored onto local hard drive before further processing. The myarmdaemon itself will read in the stored ARM data if its configured datasink (database or another myarmdaemon accepting TCP data connections) is ready to accept data.
- ARM agent
- uses this concept to temporarily store ARM data if the configured datasink is currently not available (database or myarmdaemon are down). Later if the datasink resource is available again it will read in the ARM data and write it to the datasink.
For detailed information about configuring the file storage concept read the configuration properties section.
Archive
The archive concept uses a set of MyARM binary files to store any measured ARM data. These files are created by the archive datasink and can be queried using the myarmarchive tool or by using the archive component (TCP protocol) of the myarmdaemon.
To efficiently store and retrieve data within the archive,
files are created using time stamp information within the filename
of the measured data. For example the file
transactions/myarm.info/20170801_091014.myarm
contains
transaction measurements from our myarm.info demo site recorded on
1st of august 2017 at 10 minutes and 14 seconds past nine
(UTC).
The archive uses a directory sub-tree to store all its data, starting at its configured root directory. Currently the archive distinguishes between the following main ARM data and uses a configureable file pattern relative to the archive root to create files for each of it:
- ARM definitions
- normally, the following file pattern is used
definitions/$s_defs
, where the$s
part is replaced by the system address of the host the definitions were created. The file pattern can be configured using thebasic.archive.definition.filepattern
. - ARM transaction measurements
- this is the most used file pattern and therefore it
offers many pattern keys to create a file. The transaction file in
the above example was generated by the following file pattern:
transactions/$s/%Y%m%d_%H%M%S
. This pattern can be configured by using thebasic.archive.transaction.filepattern
. - ARM threshold data
- for threshold data the following file pattern is used:
thresholds/${LOCATION}_thresholds_%Y%m%d%H%M
. This pattern can be configured by using thebasic.archive.threshold.filepattern
.Note: Thresholds are only generated if
basic.archive.threshold.enable
is set to true.
For a complete list of basic archive configuration properties read section Archive configuration propertes.
Resource watchdog
During deployment MyARM needs some resources (mainly memory) to operate correctly. The amount of memory needed depends highly on the number and frequency of transaction measurements. However MyARM should never interfere with expend the resources of the deployed application. Therefore MyARM provides various configuration properties to limit the amount of used resources. To monitor the used resources by MyARM the resource watchdog provides a simple mechanism to log the used resources.
The resource watchdog can be separately configured for monitoring of resources of following programs:
- the myarmdaemon
- any instrumented application
Runtime configuration and notification
With the release 3.0 MyARM supports so-called runtime configuration and runtime notifications starting with 4.0 of MyARM. The runtime configuration can be created and managed by the myarmadmin web application and send to appropriate configured myarmdaemon processes.
The following runtime configurations can be used:
- Real Time statistics (RTS)
- selects transaction definitions to calculate statistics and to provide them in real time
- Transactions
- selects transaction definitions to filter or monitor current measurements
- Notifications
- based on transaction or RTS conditions a configured notification can be issued
Real time statistics
Real time statistics are used to monitor executed transactions within a production environment to get in overall picture of the performance and health of the whole system including end-to-end response times. Real time in this sense means that performance data is available 5 to 10 minutes after current time (presence). With this data just few minutes ago it is possible to react on hard or software failures very quickly!
To use the real time statistics MyARM needs to know which transactions are key performance indicators (KPI). Such a KPI can be directly derived from the ARM transaction definition by adding some important information. Within MyARM a key performance indicator is formed from the following data:
- ARM transaction definition
- is used to form the base data set for the key performance indicator. This transaction definition is defined by the application and therefore represents the applications typical character
- Filter criteria
- Besides the response time each ARM transaction
measurement has several attributes associated. Therefore the
following attributes can be used to form a specialized KPI for the
given ARM transaction definition:
- System address
- defines the host or system the transaction was executed on. To monitor the performance on a specific system this filter criteria can be used.
- URI
- within web environments each transaction measurement can be associated with the appropriate URI. Use this criteria to collect performance indicators for specific or groups of web applications.
- Users
- a transaction measurement can be executed on behalf of an user. With this criteria a specific user can be monitored.
- Context properties
- a transaction measurement can have several context information associated with. For example within a load balancer the server name can be associated with the transaction measurement and be used as a KPI. Therefore different servers can be monitored simultaneously.
- Time interval
- is used to aggregate all single measurements within this interval
- Response time thresholds
- are used to calculate a performance index to classify the
performance of the transaction measurements. It is possible to
define up to three thresholds:
- Threshold 1
- response times below this threshold are expected and judged to be good
- Threshold 2
- response times below this threshold are tolerated
- Threshold 3
- response times below this threshold are bad and response times above this threshold are unacceptable
- Monitor
- defines a condition which will trigger the execution of a
notification action (New since
"4.0.x.0"):
- Response time condition
- defines a threshold for the average of deviation of response times to trigger the action
- Index condition
- defines a percentage threshold for the response time or status index to trigger the action
- Status condition
- defines a count threshold for measurements with 'Failed', 'Not good', 'Abort' or 'Unknown' status to trigger the action
Note: Its only available if runtime notification (RTN) Add-on is licensed.
To define these KPIs MyARM provides a web application to manage such information. For details read the myarmadmin chapter.
Transaction runtime configuration
Transaction runtime configuration is used to manage and control instrumented applications remotely. Appropriate configured myarmdaemon processes are listening for new runtime configuration connections from the myarmadmin web interface to receive new runtime configurations. The myarmdaemon will propagate the runtime configurations to all instrumented applications local or remote by using the TCP datasink.
The following types of runtime configuration are supported:
- Transaction management
- measuring running transactions can be disabled or enabled again. This can be achieved by disabling or enabling a single transaction definition or a configured group of transactions.
- Transaction monitor (New since "4.0.x.0")
- transactions can be monitored and a notification action can be
triggered according to the following conditions:
- Context condition
- triggers the action if the defined context property contains the specified string
- Response time condition
- triggers the action if the response time is greater than the specified threshold
- Status condition
- triggers the action if the status of the transaction equals to the specified status ('Failed', 'Not good', 'Abort' or 'Unknown')
- URI condition
- triggers the action if the URI contains the specified string
Note: Its only available if runtime notification (RTN) Add-on is licensed.
For details how to configure these concepts please read the myarmadmin chapter.
Runtime notification
Runtime notifications are new in MyARM 4.0. They are used to notify conditions of the running applications by executing a script which can either send an email/sms or react on the condition by starting a new server for a better load balancing of the application. Runtime notification is a so-called Add-on and can be used with any MyARM edition.
Currently Real time statistics and single transaction measurements can be monitored with a notification condition. For a detailed description please read the "Manage notification actions" chapter.