Concepts

Documentation / Enterprise Edition / User Guide / Agent / 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:

  1. store any measured data onto disk (filesink)
  2. read the measured data from the disk and send it to a central server using TCP/IP (tcpsink)
  3. 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 the basic.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 the basic.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 the basic.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:

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.