1arm_register_metric(3) ARM 4 Programmer's Manual arm_register_metric(3)
2
6 arm_register_metric - describe metrics
7
9 #include <arm4.h>
10 arm_error_t
12 arm_register_metric(
13 const arm_id_t *app_id,
14 const arm_char_t *name,
15 const arm_metric_format_t format,
16 const arm_metric_usage_t usage,
17 const arm_char_t *unit,
18 const arm_id_t *input_metric_id,
19 const arm_int32_t flags,
20 const arm_buffer4_t *buffer4,
21 arm_id_t *output_metric_id);
22
24 arm_register_metric() describes metadata about a metric.
25 The application uses arm_register_metric() to inform the ARM library of
27 metadata about each metric the application provides.
28 ARM generates an ID that is passed in the metric binding sub-buffer to
30 arm_register_transaction().
31 app_id is an application ID returned from an arm_register_application()
33 call in the same process.
34 buffer4 is a pointer to the user data buffer, if any. If the pointer is
36 null, there is no buffer. No sub-buffer types are currently valid with
37 this function call, so the pointer should be null (ARM_BUF4_NONE).
38 flags contains 32-bit flags. No values are currently defined. The field
40 should be zero (ARM_FLAG_NONE).
41 format describes the data type. The value must be one of the following
43 values:
44 1 (ARM_METRIC_FORMAT_COUNTER32) = arm_int32_t counter
47 2 (ARM_METRIC_FORMAT_COUNTER64) = arm_int64_t counter
49 3 (ARM_METRIC_FORMAT_CNTRDIVR) = arm_int32_t counter + arm_int32_t
51 divisor
52 4 (ARM_METRIC_FORMAT_GAUGE32) = arm_int32_t gauge
54 5 (ARM_METRIC_FORMAT_GAUGE64) = arm_int64_t gauge
56 6 (ARM_METRIC_FORMAT_GAUGEDIVR32) = arm_int32_t gauge +
58 arm_int32_t divisor
59 7 (ARM_METRIC_FORMAT_NUMERICID32) = arm_int32_t numeric ID
61 8 (ARM_METRIC_FORMAT_NUMERICID64) = arm_int64_t numeric ID
63 9 deprecated
65 10 (ARM_METRIC_FORMAT_STRING32) = string (null-terminated) of a
67 maximum length of 32 characters (33 including the null termina‐
68 tion character)
69 input_metric_id is a pointer to an optional 128-bit ID (16 bytes) that
71 is unique and that can be treated as an alias for the other metadata.
72 It can be any value except all zeros or all ones. If the pointer is
73 null (ARM_ID_NONE), no ID is provided.
74 An ID is unique if the probability of the ID being associated with more
76 than one set of metadata is vanishingly small. The selection of 128-bit
77 IDs yields 3.4 x 10**38 unique IDs, so the objective is to select an ID
78 that makes use of all 128 bits and is reasonably likely to not be
79 selected by another person creating an ID of the same form. Two sug‐
80 gested algorithms that generate 128-bit values with these characteris‐
81 tics are:
82 1. The Universal Unique Identifier (UUID) algorithm that is part of
85 The Open Group specification: DCE 1.1: Remote Procedure Call. A
86 developer could use the algorithm at the time the application is
87 developed using a utility on his or her system, and be reason‐
88 ably certain that nobody else would generate the same 128-bit
89 ID.
90 2. The MD5 Message-Digest Algorithm, described in IETF RFC 1321.
93 Applying this algorithm to a concatenation of all the metadata
94 properties would almost certainly result in a value that would
95 not collide with any other ID created with a different set of
96 metadata properties.
97 If an ARM implementation is passed an ID that was previously registered
99 within this process, the implementation can ignore the other metadata
100 parameters and assume they are identical to the previously registered
101 metadata. The metric metadata consists of the following fields: app_id,
102 name, format, usage, and unit.
103 name is a pointer to a null-terminated string containing the name of
105 the metric. The maximum length of the string is 128 characters, includ‐
106 ing the termination character. It serves no purpose and is illegal to
107 make this call if the pointer is null. The name should not contain
108 trailing blank characters or consist of only blank characters.
109 The name can be any string, with one exception. Strings beginning with
111 the four characters "ARM:" are reserved for the ARM specification. The
112 specification will define names with known semantics using this prefix.
113 One name format is currently defined. Any name beginning with the eight
114 character prefix "ARM:CIM:" represents a name defined using the DMTF
115 CIM (Distributed Management Task Force Common Information Model) naming
116 rules. For example, "ARM:CIM:CIM_SoftwareElement.Name" indicates that
117 the metric value has the semantics of the Name property of the
118 CIM_SoftwareElement class. It is anticipated that additional naming
119 semantics are likely to be added in the future.
120 output_metric_id is a pointer to a 16-byte field. ARM will store a
122 16-byte value. There are no requirements on the value it is set to,
123 except that it must be possible to pass it in the metric binding sub-
124 buffer on the arm_register_transaction() call, without the application
125 needing to do any error checking.
126 unit is a pointer to a null-terminated string containing the units
128 (such as "files transferred") of the metric. The maximum length of the
129 string is 128 characters, including the termination character. The
130 pointer may be null.
131 usage describes how the metric is used. The value must be one of the
133 following values, or a negative value (any negative value is specific
134 to the application; the negative values are not expected to be widely
135 used).
136 0 (ARM_METRIC_USE_GENERAL) = a metric without a specified usage.
139 Most metrics are described with a GENERAL usage.
140 1 (ARM_METRIC_USE_TRAN_SIZE) = a metric that indicates the "size"
142 of a transaction. The "size" is something that would be expected
143 to affect the response time, such as the number of bytes in a
144 file transfer or the number of files backed up by a "backup"
145 transaction. ARM implementations can use this knowledge to bet‐
146 ter interpret the response time.
147 2 (ARM_METRIC_USE_TRAN_STATUS) = a metric that further explains
149 the transaction status passed on arm_stop_transaction(), such as
150 a sense code that explains why a transaction failed.
151
153 On success, the function returns ARM_SUCCESS. A non-zero value indi‐
154 cates an error.
155
157 If the return code is negative, an error occurred. If the return code
158 is not negative, an error may or may not have occurred - the determina‐
159 tion of what is an error and whether an error code is returned is at
160 the discretion of the ARM implementation. The application can test the
161 return code if it wants to provide its own error logging.
162 The following errors are recognized by this implementation, but may not
164 be portable to other implementations:
165 ARM_FAILURE_NULL_ARGUMENT
168 The output_metric_id pointer must not be null.
169 ARM_FAILURE_INVALID_ARGUMENT
171 One of name or unit is invalid.
172 ARM_FAILURE_BAD_ALIAS
175 The alias provided contains all 0's or all 1's.
176 ARM_FAILURE_DUPLICATE_ALIAS
178 The alias provided already refers to a metric with dif‐
179 ferent metadata. ARM_FAILURE_INTERNAL_ERROR An internal
180 error has occurred that prevented the operation from com‐
181 pleting. Check your system log for more details.
182
184 ARM Issue 4.0 C Language Bindings, Version 2
185
187 None.
188
190 arm_register_application(3), arm_register_transaction(3)
191arm4.org August 2008 arm_register_metric(3)