arm_register_metric (3) - Linux Man Pages
arm_register_metric: describe metrics
arm_register_metric - describe metrics
const arm_id_t *app_id,
const arm_char_t *name,
const arm_metric_format_t format,
const arm_metric_usage_t usage,
const arm_char_t *unit,
const arm_id_t *input_metric_id,
const arm_int32_t flags,
const arm_buffer4_t *buffer4,
describes metadata about a metric.
The application uses arm_register_metric() to inform the ARM library of metadata about each
metric the application provides.
ARM generates an ID that is passed in the metric binding sub-buffer to
app_id is an application ID returned from an arm_register_application() call in the same
buffer4 is a pointer to the user data buffer, if any. If the pointer is null, there is no buffer. No
sub-buffer types are currently valid with this function call, so the pointer should be
flags contains 32-bit flags. No values are currently defined. The field should be zero
format describes the data type. The value must be one of the following values:
(ARM_METRIC_FORMAT_COUNTER32) = arm_int32_t counter
(ARM_METRIC_FORMAT_COUNTER64) = arm_int64_t counter
(ARM_METRIC_FORMAT_CNTRDIVR) = arm_int32_t counter + arm_int32_t
(ARM_METRIC_FORMAT_GAUGE32) = arm_int32_t gauge
(ARM_METRIC_FORMAT_GAUGE64) = arm_int64_t gauge
(ARM_METRIC_FORMAT_GAUGEDIVR32) = arm_int32_t gauge +
(ARM_METRIC_FORMAT_NUMERICID32) = arm_int32_t numeric ID
(ARM_METRIC_FORMAT_NUMERICID64) = arm_int64_t numeric ID
(ARM_METRIC_FORMAT_STRING32) = string (null-terminated) of a
maximum length of 32 characters (33 including the null termination character)
input_metric_id is a pointer to an optional 128-bit ID (16 bytes) that is unique and that can be treated as
an alias for the other metadata. It can be any value except all zeros or all ones. If the
pointer is null (ARM_ID_NONE), no ID is provided.
An ID is unique if the probability of the ID being associated with more than one set
of metadata is vanishingly small. The selection of 128-bit IDs yields 3.4 x 10**38
unique IDs, so the objective is to select an ID that makes use of all 128 bits and is
reasonably likely to not be selected by another person creating an ID of the same
form. Two suggested algorithms that generate 128-bit values with these
The Universal Unique Identifier (UUID) algorithm that is part of The Open
Group specification: DCE 1.1: Remote Procedure Call. A developer could use the
algorithm at the time the application is developed using a utility on his or her
system, and be reasonably certain that nobody else would generate the same 128-bit
The MD5 Message-Digest Algorithm, described in IETF RFC 1321. Applying
this algorithm to a concatenation of all the metadata properties would almost
certainly result in a value that would not collide with any other ID created with a
different set of metadata properties.
If an ARM implementation is passed an ID that was previously registered within
this process, the implementation can ignore the other metadata parameters and
assume they are identical to the previously registered metadata. The metric
metadata consists of the following fields: app_id, name, format, usage, and unit.
name is a pointer to a null-terminated string containing the name of the metric. The maximum
length of the string is 128 characters, including the termination character. It serves
no purpose and is illegal to make this call if the pointer is null. The name should not
contain trailing blank characters or consist of only blank characters.
The name can be any string, with one exception. Strings beginning with the four
characters "ARM:" are reserved for the ARM specification. The specification will
define names with known semantics using this prefix. One name format is currently
defined. Any name beginning with the eight character prefix "ARM:CIM:"
represents a name defined using the DMTF CIM (Distributed Management Task
Force Common Information Model) naming rules. For example,
"ARM:CIM:CIM_SoftwareElement.Name" indicates that the metric value has the
semantics of the Name property of the CIM_SoftwareElement class. It is anticipated
that additional naming semantics are likely to be added in the future.
output_metric_id is a pointer to a 16-byte field. ARM will store a 16-byte value. There are no
requirements on the value it is set to, except that it must be possible to pass it in the
metric binding sub-buffer on the arm_register_transaction() call, without the
application needing to do any error checking.
unit is a pointer to a null-terminated string containing the units (such as "files transferred")
of the metric. The maximum length of the string is 128 characters, including the
termination character. The pointer may be null.
usage describes how the metric is used. The value must be one of the following values, or
a negative value (any negative value is specific to the application; the negative
values are not expected to be widely used).
(ARM_METRIC_USE_GENERAL) = a metric without a specified usage. Most
metrics are described with a GENERAL usage.
(ARM_METRIC_USE_TRAN_SIZE) = a metric that indicates the "size" of a
transaction. The "size" is something that would be expected to affect the response
time, such as the number of bytes in a file transfer or the number of files backed up
by a "backup" transaction. ARM implementations can use this knowledge to better
interpret the response time.
(ARM_METRIC_USE_TRAN_STATUS) = a metric that further explains the
transaction status passed on arm_stop_transaction(), such as a sense code that
explains why a transaction failed.
On success, the function returns ARM_SUCCESS. A non-zero value indicates
If the return code is negative, an error occurred. If the return code is not negative, an error may
or may not have occurred - the determination of what is an error and whether an error code is
returned is at the discretion of the ARM implementation. The application can test the return code
if it wants to provide its own error logging.
The following errors are recognized by this implementation, but may not be portable to other implementations:
The output_metric_id pointer must not be null.
One of name or unit is invalid.
The alias provided contains all 0's or all 1's.
The alias provided already refers to a metric with different metadata.
An internal error has occurred that prevented the operation from completing. Check your
system log for more details.
ARM Issue 4.0 C Language Bindings, Version 2