Perf-ARM - README

Perf::ARM is a very simple XS wrapper around the Application Response Measurement interface. To quote the ARM FAQ: (http://www.cmg.org/regions/cmgarmw/armfaq.html)

"What is ARM?
ARM stands for Application Response Measurement. It is an API jointly developed by an industry partnership that is used to monitor the availability and performance of applications. This monitoring is done from the perspective of the application itself, so it reflects those units of work that are important from the perspective of the business."

Basically, putting the arm_start and arm_stop calls in your C (and now perl) code will allow you to gather and view performance data with HP Openview tools, including Glance, and other consumers of ARM data, like Tivoli's tools.

Documentation and links:

as usual, try 'perldoc ARM.pm' or after install, 'perdoc Perf::ARM' for usage info
the test scripts in the t/ directory may serve as interesting examples to get you started
check out + ARM FAQ at http://www.cmg.org/regions/cmgarmw/armfaq.html + CMG ARM Working Group info page at http://www.cmg.org/regions/cmgarmw/ + HP-UX: /opt/perf/include/arm.h or /usr/include/arm.h + Glance docs at http://www.openview.hp.com/products/

Prerequisites
perl 5.005 or later The module has only been heavily used with 5.6 -- older versions may or may not work. Please report problems to me. In particular, some implementations of libarm use threads, which has not worked well for me with perl 5.004_04.
A functioning cc, gcc, or ANSI compliant C compiler
the ARM include file - generally /usr/include/arm.h
a functioning ARM library (check for /usr/lib/libarm.* or build and use the libarm from the CMG ARM SDK) for HP-UX, this means the Measureware Glance Pak's libarm.sl The default HP-UX installation includes a NOP library that will allow an application that links with ARM to run, but no ARM instrumentation will really be collected. The same is true for this perl module -- it is possible to use the perl ARM calls without checking error codes, and a NOP libarm will be silently ignored. However, the 'make test' step of the Perf::ARM module installation does check error codes, so it will fail if the any arm_* related calls fail. Calls to the NOP library will fail, so the 'make test' will fail as well.

HP-UX Installation notes:

see /usr/include/arm.h for a list of the errors that can be returned from the calls. Hint: search for ARM_INVID to jump to the error code listing.
You may need to make adjustments to your /var/opt/perf/ttd.conf file to allow arm_init() and arm_getid() to succeed. See the ttd.conf(4) man page for more information.

Current limitations:

'make test' does not pass for the ARM SDK no-operation (NULL) shared libraries, as the module expects real return codes. The libagent library from the SDK works fine.
the arm_update() routine is not supported yet
user metrics and correlators have not been tested
the module has only been tested on an HP-UX 11.00 system using the Measureware/Glance libarm.sl
this is my first submission to CPAN and my first XS module -- doubtless it shows. :) Feedback, suggestions, constructive criticism, and random assistance are very welcome
the tests included in t/ are very rudimentary
some versions of perl built with usemymalloc='y' fail. Workaround: rebuild with usemymalloc='n'.

Glance note:

on HP-UX systems with the Glance/Measureware tools, you may also find a line like this useful for seeing the ARM traffic: glance -adviser_only -j 5 -syntax /opt/perf/examples/adviser/arm

Acknowledgements
Many thanks to Doug Grumann for the ARM examples and insights
David Carter has sent several improvements to the tests and demonstrated how to use Inline. Look for these in an upcoming version of Perf::ARM.