ARM 4 User Guide

Table of Contents

Installation

Getting The Software

Download the source

Building From Source

Unpack the source files and configure any options: 

$ tar xzf arm4-0.8.tar.gz
$ cd arm4-0.8
$ ./configure
$ make

Then, as root: 

# make install

Configuration options can be listed by running 

$ ./configure --help

Creating Users and Groups

For system wide installations, creating a unique user and group is highly recommended. While the details will vary from system to system, on Red Hat Linux this is typically done using the following commands: 

# groupadd -r arm4
# useradd -r -c "ARM4 daemon" -M -g arm4 -s /sbin/nologin arm4

You can then add users to the group to allow them to access the system wide installation. On Red Hat, this is done with the following command: 

# usermod -a -G arm4 <user>

For example, you may want to add your Apache user for measuring httpd response times in conjuction with the Apache mod_arm4 module.

The Configuration File

The configuration file controls all aspects of the arm4_daemon(1) program. For example, it sets the user and group for the daemon. Full details of configuration options are available from the man page arm4.conf(5).

An example configuration file is in the conf directory of the installation source.

Automating Startup and Shutdown

Log File Management

Upgrading

There is no upgrade path from previous versions to version 0.8. Back up your data and run arm4_control wipe to remove any shared memory, semaphores, and message queues before installing. It may also be necessary to manually remove older library and executable images as these may have moved since your last install.

User Space Installations

It's possible to use the ARM4 agent without installing as root, or use an installed version without using the system wide datastore.

The default system installation uses an instance number of 0. You can use a different instance by setting the instance number as follows:

  • Create an alternative configuration file specifying an alternative instance number

e.g. local_arm4.conf' 

instance = 1
  • Start an instance of arm4_daemon using this new configuration file 
$ arm4_daemon -C local_arm4.conf
  • Set the ARM4_INSTANCE environment variable to match your configuration file's instance number 
$ ARM4_INSTANCE=1
$ export ARM4_INSTANCE

or 

$ setenv ARM4_INSTANCE=1
  • Run your application

If you get permission errors, then you've probably chosen an instance number already in use. Select another and try again. You can see the instance numbers in use by checking the /tmp/arm4 directory.

Managing Applications

Applications and transactions are normally created by running programs using the ARM4 API. Once the applications have been created, they can be exported using either the arm4_control export definitions or arm4_export commands. The XML file created can then be used to "seed" applications on a different system using the arm4_control import command.

There are four basic modes of data collection.

  • Trace All
    As the name implies, all transactions are sampled. This will allow you to examine all application and transaction instances and their inter-relationships, but at the cost of higher overhead. Depending on your datastore, this may have a significant impact on the performance of your application.
  • Trace every N
    Every Nth transaction instance will be measured.
  • Trace every N/10 seconds
    A transaction is sampled approximately every N/10 seconds. Once the timer expires, the next transaction is measured and the timer rest.
  • Trace none
    No transactions are measured.

There are some common exceptions to these settings. If a correlator is passed into a transaction, then the transaction will be traced regardless of setting. This guarantees the transaction chain is recorded in it's entirety. Also, in certain circumstances, the transaction itself may request a trace be made. Whether or not this request is honoured is a configurable setting.

Settings are modified using the arm4_control program. To set the base collection mode for a transaction, one of the following commands is required: 

$ arm4_control transaction {tran_id} trace all
$ arm4_control transaction {tran_id} trace none
$ arm4_control transaction {tran_id} trace {n}
$ arm4_control transaction {tran_id} trace {n}[s|S]

Similarly, to configure whether or not the application may request a trace: 

$ arm4_control transaction {tran_id} trace application
$ arm4_control transaction {tran_id} trace noapplication

In all cases, the transaction must be defined before the settings may be changed.

Datastores

See Arm4Datastores for information on supported datastores.

Using the Agent

This section introduces information specific to this implementation and isn't intended to provide a tutorial to using the ARM 4 APIs. Tutorials are available at Arm4Tutorials.

C/C++

For compilation, it may be necessary to specify the location of the header files. The default installation puts them in /usr/local/include. Building an arm application (e.g. arm4_example from arm4_example.c) will look similar to this: 

$ cc -I/usr/local/include -c example.c

Similarly, on UNIX/Linux the libraries are implemented as shared libraries and are linked in the standard fashion. 

$ cc -L/usr/include/lib -o example example.o -larm4

libarm4_null

As a convenience, a null library is also provided that allows the user to link against the ARM 4 API without actually collecting any transaction information. This may be useful in the development cycles where collection isn't required. To link against this library, specifiy -larm4_null instead or -larm4.

Java

The Java libraries are in a .jar file in the installation library directory. For the default installation, this is /usr/local/lib. It is in the form of arm4-<version>.jar, so for example if your installed version is 0.8, this will be /usr/local/lib/arm4-0.8.jar.

Compiling java applications

It will be necessary to include an ARM library in your class path when compiling. Any implementation will work for this, including the ARM4 SDK. To use the ARM4.org version, specify the path to the library as specified in the previous section. For example: 

$ javac -cp /usr/local/lib/arm4-0.8.jar <java_program>

Running java applications

In addition to specifying the implementation library, it will also be necessary to define the transaction, metric, and report factories. While this can be hard coded into the application, it is usually preferable to define this on the command line. For example: 

$ java -cp /usr/local/lib/arm4-0.8.jar -DArm40.ArmTransactionFactory=org.arm4.arm40.transaction.ArmTransactionFactory -DArm40.ArmMetricFactory=org.arm4.arm40.metric.ArmMetricFactory -DArm40.ArmTranReportFactory=org.arm4.arm40.metric.ArmTranReportFactory

For examples of how to do this with specific application containers, see Arm4HowTo.