arm4
index
/usr/lib64/python2.4/site-packages/arm4.so

Python language bindings for the Application Response Measurement (ARM) Version 4.0 standard.
 
This module provides a Python language implementation of the ARM 4.0
standard. At it's simplest, it's a straight exposure of the C language
bindings with enough concessions to make it fit the Python language.
 
Usage:
 
  import arm4
 
  # Register
  app_id = arm4.register_application ("Python test")
  tran_id = arm4.register_transaction (app_id, "Python hello world")
 
  # Start our application and transaction measurements
  app_handle = arm4.start_application (app_id, "Example")
  tran_handle = arm4.start_transaction (app_handle, tran_id)
 
  # Do our work
  print 'Hello, world!'
 
  # Stop our measurements
  arm4.stop_transaction (tran_handle) # Default status is arm4.ARM_STATUS_GOOD
  arm4.stop_application (app_handle)
 
  # Finish up
  arm4.destroy_application (app_id)
 
This is a simple example that doesn't make use of ARM's advanced
correlators or metrics. More examples can be found at http://www.arm4.org
 
This module is based on the ARM Issue 4.0, Version 2 - C Binding standard. More information
can be found at http://www.opengroup.org/management/arm.htm

 
Classes
       
__builtin__.object
ArmArrivalTime
ArmBuffer
ArmCorrelator
ArmHandle
ArmID
ArmSubbufferAppContext
ArmSubbufferAppIdentity
ArmSubbufferArrivalTime
ArmSubbufferCharset
ArmSubbufferDiagDetail
ArmSubbufferMetricBindings
ArmSubbufferMetricValues
ArmSubbufferSystemAddress
ArmSubbufferTranContext
ArmSubbufferTranIdentity
ArmSubbufferUser
exceptions.Exception
error

 
class ArmArrivalTime(__builtin__.object)
    Opaque wrapper for an ARM 4 arrival time structure.
This is created by calling get_arrival_time ()
 
 

 
class ArmBuffer(__builtin__.object)
    Many of the ARM function calls provide a way for the application and ARM implementation to
exchange optional data, in addition to the required data in other function parameters. This buffer
describes the format of the exchanged data.
 
Almost all functions define a ArmBuffer parameter. When the value is provided, the value points to
a buffer containing a number of sub-buffers. It differs from the ARM 2.0 format in that the buffer
contains  pointers to sub-buffers, rather than inline contiguous data. The sub-buffers contain the
meaningful data. The internals of this buffer are hidden in the ArmBuffer object.
 
Each sub-buffer may be in the user data buffer once. If there is more than one instance of a sub-
buffer in the buffer, all instances after the first will be ignored.
 
  Methods defined here:
add_subbuffer(...)
add_subbuffer(sub_buffer): add a sub-buffer
 
DESCRIPTION
  Adds a sub-buffer object to the user data buffer. This can then be passed to any of the arm4
  methods as required and appropriate.
 
  This abstracts the ARM 4 arm_buffer4_t internals
PARAMETERS
  sub_buffer   A valid ArmSubbuffer* object
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmCorrelator(__builtin__.object)
    Opaque wrapper for an ARM 4 correlator structure.
 
  Methods defined here:
__str__(...)
x.__str__() <==> str(x)
from_string(...)
from_string (hex): Set the user name
 
DESCRIPTION
  Sets correlator value from its hexadecimal representation.
 
  This is useful for correlators passed into the application from an external source, such as
  the Apache web server.
PARAMETERS
  hex   A string containing a hexadecimal representation of a correlator. This is the same
        as produced by str().
RETURN VALUE
  None
get_flags(...)
get_flags(flags): get value of flag
 
DESCRIPTION
  get_flags() returns the value of a specified flag in the correlator.
 
  A correlator contains bit flags, and get_flags() is used to test the value of
  those flags. See generate_correlator() for a description of a correlator.
PARAMETERS
  flags     An enumerated value that indicates which flag's value is requested. The
            enumerated values are:
            ARM_CORR_FLAGNUM_APP_TRACE = Application trace flag
            ARM_CORR_FLAGNUM_AGENT_TRACE = Agent trace flag
RETURN VALUE
  Boolean object indicating whether the flag is set.
length(...)
length(): get length of correlator
 
DESCRIPTION
  length() returns the length of a correlator, based on the length field within
  the correlator header. Note that this length is not necessarily the length of the
  buffer containing the correlator.
 
  A correlator header contains a length field. length() is used to return the length. The function
  handles any required conversion from the network byte order used in the header and the endian
  (big versus little) of the platform. See generate_correlator() for a description of a correlator.
PARAMETERS
  None
RETURN VALUE
  The length of the correlator

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmHandle(__builtin__.object)
    Opaque wrapper for an ARM 4 handle structure.
 
  Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmID(__builtin__.object)
    Opaque wrapper for an ARM 4 ID structure.
 
  Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferAppContext(__builtin__.object)
    Applications are identified by a name and an optional set of identity attribute (name,value) pairs.
Application instances are further identified by an optional set of context (name,value) pairs.
These properties could indicate something about the runtime instance of the application, such as
the instance identifier and the name of a configuration file used.
 
The optional context property names are provided in the application identity sub-buffer on the
register_application() call. The optional context property values are provided in this sub-
buffer on the start_application() call. The sub-buffer is ignored if it is passed on any other
call.
 
Context Values
  The values in the array are position-sensitive; each must align with the corresponding context
  property name in the application identity sub-buffer. If the corresponding property name string
  is zero-length, the value is ignored.
 
  Each array element contains:
  o   Value: A string representing the value part of the (name,value) pair. Each string has a maximum
          length of 255 characters. If any string is zero-length, the meaning is that there is no value
          for this instance. The value should not contain trailing blank characters or consist of only
          blank characters.
 
  Methods defined here:
set_context_value(...)
set_context_value(index, value): Set an application context value
 
DESCRIPTION
  set_context_value() sets the value in the specified index.
PARAMETERS
  index     The array index of a property value between 0 and 19
 
            The values in the array are position-sensitive; each must align with the corresponding context
            property name in the application identity sub-buffer. If the corresponding property name string
            is zero-length, the value is ignored.
  name      A string representing the name part of the (name,value) pair. Each string has a maximum
            length of 255 characters. If any string is zero-length, the meaning is that there is no value
            for this instance. The value should not contain trailing blank characters or consist of only
            blank characters.
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferAppIdentity(__builtin__.object)
    Applications are identified by a name and an optional set of identity attribute (name,value) pairs.
Application instances are further identified by an optional set of context (name,value) pairs. The
optional context property names are provided in this sub-buffer on the
register_application() call. The optional context property values are provided on the
start_application() call. The sub-buffer is ignored if it is passed on any other call.
 
The names of identity and context properties 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 property 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.
 
Identity Properties
  The array index of a property value in the value array is bound to the property name at the
  same index in the name array. Moving the (name,value) pair to a different index does not
  affect the identity of the application. For example, if an application registers once with a
  name A and a value X in array indices 0 and once with the same name and value in array
  indices 1, the registered identity has not changed.
 
  If a name is repeated in the array, the name and its corresponding value are ignored, and
  the first instance of the name and value in the array is used. The implementation may
  return an error code but is not obliged to do so.
 
  Each structure contains:
  o   Name: A string representing the name part of the (name,value) pair. Each string has a maximum
          length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.
          Names should not contain trailing blank characters or consist of only blank characters.
  o   Value: A string representing the value part of the (name,value) pair. Each string has a maximum
          length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.
          Values should not contain trailing blank characters or consist of only blank characters.
 
Context Properties
  If a name is repeated in the array, the name and its corresponding value (in the application
  context sub-buffer) are ignored, and the first instance of the name in the array (and its
  corresponding value) is used. The implementation may return an error code but is not
  obliged to do so.
 
  Each array element contains:
  o   Name: A string representing the name part of the (name,value) pair. Each string has a maximum
              length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.
              The values are provided in the ArmSubbufferApplicationContext object. Names should not contain
              trailing blank characters or consist of only blank characters.
 
  Methods defined here:
set_context_name(...)
set_context_name(index, name): Set an application context name
 
DESCRIPTION
  set_context_name() sets the name in the specified index.
PARAMETERS
  index     The array index of a property value between 0 and 19
 
            If a name is repeated in the array, the name and its corresponding value (in the application
            context sub-buffer) are ignored, and the first instance of the name in the array (and its
            corresponding value) is used.
  name      A string representing the name part of the (name,value) pair. Each string has a maximum
            length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.
            The values are provided in the ArmSubbufferApplicationContext object. Names should not contain
            trailing blank characters or consist of only blank characters.
RETURN VALUE
  None
set_property(...)
set_property(index, name, value): Set an application identity name/value pair
 
DESCRIPTION
  set_property() sets the name/value pair in the specified index.
PARAMETERS
  index     The array index of a property value between 0 and 19
            The array index of a property value in the value array is bound to the property name at the
            same index in the name array. Moving the (name,value) pair to a different index does not
            affect the identity of the application. For example, if an application registers once with a
            name A and a value X in array indices 0 and once with the same name and value in array
            indices 1, the registered identity has not changed.
  name      A string representing the name part of the (name,value) pair. Each string has a maximum
            length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.
            Names should not contain trailing blank characters or consist of only blank characters.
  value     A string representing the value part of the (name,value) pair. Each string has a maximum
            length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.
            Values should not contain trailing blank characters or consist of only blank characters.
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferArrivalTime(__builtin__.object)
    Some applications may start processing a transaction before all the context information that
identifies the transaction is known. For example, it might by necessary to retrieve the context
information as the first step in processing the transaction. For these cases, the application can
call get_arrival_time() to receive a timestamp value for the current time from the ARM
implementation. This timestamp value is known as the "arrival time". When the transaction
context data is all known, start_transaction() is called, passing the optional arrival time
value in a sub-buffer, to indicate when the transaction actually started executing. The arrival
time is provided in this sub-buffer.
 
The arrival time field is an ArmArrivalTime object containing the value returned by the
get_arrival_time() function.
 
  Methods defined here:
set_arrival_time(...)
set_arrival_time(arrival_time): Sets the transaction arrival time
 
DESCRIPTION
  set_arrival_time() sets the arrival time for the transaction.
PARAMETERS
  arrival_time  an ArmArrivalTime object containing the value returned by the
                get_arrival_time() function.
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferCharset(__builtin__.object)
    Applications may specify on register_application() the character set encoding for all
strings passed by the application. An ARM library must support certain encodings, depending on
the platform (see Table 1). The application may always use one of the mandatory encodings.
This module defines names of the form ARM_CHARSET_* for all the mandatory
encodings. The application may optionally ask the ARM library if another encoding is supported
using is_charset_supported().
 
When the application registers with register_application(), it may optionally provide the
character set encoding sub-buffer. In the sub-buffer, the application specifies the MIBenum
value of a character set encoding that has been assigned by the IANA (Internet Assigned
Numbers Authority - see www.iana.org). The MIBenum value in the sub-buffer should only be
either a mandatory encoding for the platform or a MIBenum value for which support has been
verified using is_charset_supported().
 
The list of supported encodings must restrict itself to those that do not contain any embedded
null bytes. Exceptions are permitted for character sets that have fixed-length characters (e.g.,
two bytes) and that do not allow a character of all zeros (e.g., 0x0000). These include UTF-
16LE, UTF-16BE, and UTF-16 (MIBenum values 1013, 1014, 1015). For these encodings, there
will be a convention that a character of all zeros is the null-termination character.
 
  Methods defined here:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferDiagDetail(__builtin__.object)
    When a transaction completion is reported with stop_transaction() or report_transaction(),
and the transaction status is not ARM_STATUS_GOOD, the application may provide a character
string containing any arbitrary diagnostic data. The string may not be longer than 4095 characters.
For example,the application might provide the SQL query text for a failing database transaction.
 
  Methods defined here:
set_detail(...)
set_detail (detail): Set the diagnostic detail string
 
DESCRIPTION
  set_detail() sets the diagnostic detail string.
PARAMETERS
  detail    A string containing the diagnostic data. Each string has a maximum length
            of 4095 characters.
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferMetricBindings(__builtin__.object)
    Applications may provide additional data about a transaction when the transaction starts, while it
is executing, and/or after it has stopped. This additional data may serve several purposes, such as
indicating the size of a transaction (e.g., the number of bytes in a file for a file transfer
transaction), the state of the system (e.g., the number of queued up transactions when this
transaction arrived), or an error code. The metadata describing each metric is provided with the
register_metric() function.
 
Each transaction definition may define zero to seven metrics for which data values may be
provided on start_transaction(), update_transaction(), stop_transaction(), or
report_transaction(). Each metric is assigned to an array slot numbered 0 to 6 (they were
numbered 1 to 7 in ARM 2.0). This sub-buffer is passed on the register_transaction()
function to indicate which metrics are assigned to which slots.
 
Metric Bindings
  An array of ArmID objects containing the metric bindings.
 
  Each structure contains:
  o   Slot number: A byte slot number. Valid values are 0 to 6. If a slot number is repeated,
          the first time it appears is the only one processed; all others are ignored.
  o   ID: An ArmID object for this metric definition. The ID must have been previously returned from
          register_metric().
 
  Methods defined here:
bind(...)
bind(index, metric_id): Set a transaction context value
 
DESCRIPTION
  bind() binds a metric to the specified index.
PARAMETERS
  index     The array index of a metric between 0 and 7
  metric_id An ArmID object for this metric definition. The ID must have been previously returned from
            register_metric().
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferMetricValues(__builtin__.object)
    The buffer is used to pass metric values on any of start_transaction(),
update_transaction(), stop_transaction(), and report_transaction().
 
Metric Values
  Each structure is in the following format:
  o   Slot number: A single-byte slot number. Valid values are 0 to 6. The slot number
          must be the same as the corresponding entry in the metric bindings sub-buffer. Each
          slot number should be used at most once; if a slot number is reused, the first entry is
          used and all others are ignored.
  o   Metric format: A single-byte format indicator. Valid values are 1 to 10 and are the
          same as ARM 2.0. Only values 1 to 8 are valid in slots 0-5. Only value 10 is valid in
          slot 6. This is a carry-over from ARM 2.0. The format must be the same as the
          corresponding entry in the metric bindings sub-buffer.
 
          1 (ARM_METRIC_FORMAT_COUNTER32) = arm_int32_t counter
          2 (ARM_METRIC_FORMAT_COUNTER64) = arm_int64_t counter
          3 (ARM_METRIC_FORMAT_CNTRDIVR32) = arm_int32_t counter + arm_int32_t divisor
          4 (ARM_METRIC_FORMAT_GAUGE32) = arm_int32_t gauge
          5 (ARM_METRIC_FORMAT_GAUGE64) = arm_int64_t gauge
          6 (ARM_METRIC_FORMAT_GAUGEDIVR32) = arm_int32_t gauge + arm_int32_t divisor
          7 (ARM_METRIC_FORMAT_NUMERICID32) = arm_int32_t numeric ID
          8 (ARM_METRIC_FORMAT_NUMERICID64) = arm_int64_t numeric ID
          9 = (DEPRECATED)
          10 (ARM_METRIC_FORMAT_STRING32) = string of a maximum length of 32 characters
  o   Usage: An arm_metric_usage_t indicating how the metric is used. The usage must
          be the same as the usage parameter passed on the register_metric() call that
          registered the metric ID with the same slot number that is in the metric bindings sub-
          buffer.
 
          0 (ARM_METRIC_USE_GENERAL) = no usage is declared
          1 (ARM_METRIC_USE_TRAN_SIZE) = the metric indicates the transaction size (e.g., the size
                of a file or the number of jobs in a network backup operation)
          2 (ARM_METRIC_USE_TRAN_STATUS) = the metric is a status code (numeric ID) or text message
                (string). It would typically be used with stop_transaction() or report_transaction()
                to provide additional details about a transaction status of Failed.
          3:32767 = Reserved.
          -32768:-1 = available for implementation-defined purposes.
  o   Valid flag: A boolean that indicates whether the data in the metric value field is
          currently valid.
  o   Metric value: A metric value where the data type matches the metric format indicator (above).
 
  Methods defined here:
set_value(...)
set_value(slot, format, usage, value): Set a single numeric value
set_value(slot, format, usage, value, divisor): Set a value with a divisor
set_value(slot, usage, string_value): Set a string value
 
DESCRIPTION
  set_value() sets a metric value for the specified slot.
PARAMETERS
  slot      The array index of a metric between 0 and 7
  format    A single-byte format indicator. Valid values are 1 to 8 and are the
            same as ARM 2.0. Only values 1 to 8 are valid in slots 0-5. Only value 10 is valid in
            slot 6. This is a carry-over from ARM 2.0. The format must be the same as the
            corresponding entry in the metric bindings sub-buffer. This is not required for a string
            value.
 
            1 (ARM_METRIC_FORMAT_COUNTER32) = arm_int32_t counter
            2 (ARM_METRIC_FORMAT_COUNTER64) = arm_int64_t counter
            3 (ARM_METRIC_FORMAT_CNTRDIVR32) = arm_int32_t counter + arm_int32_t divisor
            4 (ARM_METRIC_FORMAT_GAUGE32) = arm_int32_t gauge
            5 (ARM_METRIC_FORMAT_GAUGE64) = arm_int64_t gauge
            6 (ARM_METRIC_FORMAT_GAUGEDIVR32) = arm_int32_t gauge + arm_int32_t divisor
            7 (ARM_METRIC_FORMAT_NUMERICID32) = arm_int32_t numeric ID
            8 (ARM_METRIC_FORMAT_NUMERICID64) = arm_int64_t numeric ID
  usage     An arm_metric_usage_t indicating how the metric is used. The usage must
            be the same as the usage parameter passed on the register_metric() call that
            registered the metric ID with the same slot number that is in the metric bindings sub-
            buffer.
 
            0 (ARM_METRIC_USE_GENERAL) = no usage is declared
            1 (ARM_METRIC_USE_TRAN_SIZE) = the metric indicates the transaction size (e.g., the size
                of a file or the number of jobs in a network backup operation)
            2 (ARM_METRIC_USE_TRAN_STATUS) = the metric is a status code (numeric ID) or text message
                (string). It would typically be used with stop_transaction() or report_transaction()
                to provide additional details about a transaction status of Failed.
            3:32767 = Reserved.
            -32768:-1 = available for implementation-defined purposes.
  value     A metric value where the data type matches the metric format indicator (above).
  divisor   A divisor as required by the ARM_METRIC_FORMAT_CNTRDIVR and ARM_METRIC_FORMAT_GAUGEDIVR32 formats.
  string_value
            A 32 character string. For this value type, a format of ARM_METRIC_FORMAT_STRING32 is assumed.
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferSystemAddress(__builtin__.object)
    The system address sub-buffer is used with start_application() when the transactions that
will be reported execute on a different system than the one on which they will be reported.
 
  o   If no system address sub-buffer is provided on start_application(), all transactions
          reported by this application instance execute in the current process.
  o   If a system address sub-buffer is provided on start_application(), all transactions
          execute in a different process.
  o   If a system address sub-buffer is provided in which the system address length is zero, or
          the system address pointer is null, the system is the local system, as determined by the
          ARM implementation.
  o   If a system address sub-buffer is provided in which there is a non-null system address and
          length, the system may be the local system or a remote system. Interpretation of what is
          local versus remote is at the discretion of the ARM implementation.
 
Address Formats
  The following formats are defined:
  o   0 = Reserved.
  o   1 (ARM_SYSADDR_FORMAT_IPV4) = IPv4
          Bytes 0:3 = 4-byte IP address
  o   2 (ARM_SYSADDR_FORMAT_IPV4PORT) = IPv4 + port number
          Bytes 0:3 = 4-byte IP address
          Bytes 4:5 = 2-byte IP port number
  o   3 (ARM_SYSADDR_FORMAT_IPV6) = IPv6
          Bytes 0:15 = 16-byte IP address
  o   4 (ARM_SYSADDR_FORMAT_IPV6PORT) = IPv6 + port number
          Bytes 0:15 = 16-byte IP address
          Bytes 16:17 = 2-byte IP port number
  o   5 (ARM_SYSADDR_FORMAT_SNA) = SNA
          Bytes 0:7 = EBCDIC-encoded network ID
          Bytes 8:15 = EBCDIC-encoded network accessible unit (control point or LU)
  o   6 (ARM_SYSADDR_FORMAT_X25) = X.25
          Bytes 0:15 = The X.25 address (also referred to as an X.121 address). This is up to 16
          ASCII character digits ranging from 0-9.
  o   7 (ARM_SYSADDR_FORMAT_HOSTNAME) = hostname (characters, not null-terminated)
          Bytes 0:?? = hostname
  o   8 (ARM_SYSADDR_FORMAT_UUID) = Universally-unique ID
          Bytes 0:15 = UUID in binary. This is useful for applications that define their system
          by a UUID rather than a network address or hostname or some other address form.
  o   9:32767 = Reserved.
  o   -32768:-1 = Available for implementation-defined use.
 
          There are no semantics associated with the address format. It will be an unusual
          situation where a new format is needed, but this provides a solution if this is needed.
          The preferred approach is to get a new format defined that is in the 0-32767 range.
          There is a risk that two different agent developers will choose the same ID, but this
          risk is deemed small.
 
Address Length
  An 16 bit integer length of system address in bytes.
  o   There is no maximum length.
  o   A length of zero refers to the local system.
 
  Methods defined here:
set_hostname(...)
set_hostname (name): Set the system hostname
 
DESCRIPTION
  set_hostname() sets the system address with a host name.
PARAMETERS
  name   A string giving the hostname.
RETURN VALUE
  None
set_local(...)
set_local (): Set the system address to be the local host
 
DESCRIPTION
  set_local() sets the system address to be the local host.
PARAMETERS
  None
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferTranContext(__builtin__.object)
    In addition to the identity properties, a transaction may be described with additional context
properties. Context properties differ from identity properties in that although the name is
provided when the transaction is registered [register_transaction()], the values are
provided when a transaction is measured [start_transaction() or report_transaction()].
The value of an identity property never changes, whereas the value of a context property may
change every time a transaction executes.
 
Context properties are of two forms. There may be one URI value and up to twenty (name,value)
pairs. No name may duplicate the name of a transaction identity property.
 
Context Values
  An array strings containing the property values. The values in the array are position-sensitive;
  each must align with the corresponding context property name in the ArmSubbufferTranIdentity
  object. If the corresponding property name is a zero-length string, the value is ignored.
 
  Each array element contains:
  o   Value: A string representing the value part of the (name,value) pair. Each string has a maximum
          length of 255 characters. If any string is zero-length, the meaning is that there is no value
          for this instance. Values should not contain trailing blank characters or consist of only
          blank characters.
 
URI
  A string containing a URI, with a maximum of 4095 characters.
 
  If a URI is provided in both the transaction identity sub-buffer and in the transaction
  context sub-buffer, the URI in the transaction identity sub-buffer must be the same as the
  URI provided in the transaction context sub-buffer, or a truncated subset.
 
  Methods defined here:
set_context_value(...)
set_context_value(index, value): Set a transaction context value
 
DESCRIPTION
  set_context_value() sets the value in the specified index.
PARAMETERS
  index     The array index of a property value between 0 and 19
 
            If a value is repeated in the array, the value and its corresponding value (in the transaction
            context sub-buffer) are ignored, and the first instance of the value in the array (and its
            corresponding value) is used.
  value     A string representing the value part of the (name,value) pair. Each string has a maximum
            length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.
RETURN VALUE
  None
set_uri(...)
set_uri(uri): Set a transaction uri
 
DESCRIPTION
  set_uri() sets the uri for the transaction.
PARAMETERS
  uri       A string representing the the uri of the transaction. This string has a maximum
            length of 4095 characters. If the string is zero-length, the uri is ignored.
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferTranIdentity(__builtin__.object)
    Transactions are identified by a name, an optional URI value, and an optional set of attribute
(name,value) pairs. The URI and optional (name,value) pairs are provided in this sub-buffer on
the register_transaction() call. The sub-buffer is ignored if it is passed on any other call.
The identity is scoped to a single application.
 
The names of identity and context properties 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 property 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.
 
Idenitity Properties
  The array index of a property value in the value array is bound to the property name at the
  same index in the name array. Moving the (name,value) pair to a different index does not
  affect the identity of the transaction. For example, if an application is registered once with
  a name A and a value X in array indices 0 and once with the same name and value in array
  indices 1, the registered identity has not changed.
 
  If a name is repeated in the array, the name and its corresponding value (in the transaction
  context sub-buffer) are ignored, and the first instance of the name in the array (and its
  corresponding value) is used. The implementation may return an error code but is not
  obliged to do so.
 
  Each structure contains:
  o   Name: A string representing the name part of the (name,value) pair. Each string has a maximum
          length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.
          Names should not contain trailing blank characters or consist of only blank characters.
  o   Value: A string representing the value part of the (name,value) pair. Each string has a maximum
          length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.
          Values should not contain trailing blank characters or consist of only blank characters.
 
Context Properties
  An array of strings, each containing a context property name. Each array element is a string
  representing the name part of the (name,value) pair. Each string has a maximum length of 127
  characters. The name is passed on register_transaction().
 
  If a name is repeated in the array, the name and its corresponding value (in the transaction
  context sub-buffer) are ignored, and the first instance of the name in the array (and its
  corresponding value) is used
 
  Each array element contains:
  o   Name: A string representing the name part of the (name,value) pair. Each string has a maximum
              length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.
          The values are provided in the ArmSubbufferTransactionContext object. Names should not
          contain trailing blank characters or consist of only blank characters.
 
URI
  A string containing a URI, with a maximum of 4095 characters.
 
  Methods defined here:
set_context_name(...)
set_context_name(index, name): Set a transaction context name
 
DESCRIPTION
  set_context_name() sets the name in the specified index.
PARAMETERS
  index     The array index of a property value between 0 and 19
 
            If a name is repeated in the array, the name and its corresponding value (in the transaction
            context sub-buffer) are ignored, and the first instance of the name in the array (and its
            corresponding value) is used.
  name      A string representing the name part of the (name,value) pair. Each string has a maximum
            length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.
            The values are provided in the ArmSubbufferTranContext object. Names should not contain
            trailing blank characters or consist of only blank characters.
RETURN VALUE
  None
set_property(...)
set_property(index, name, value): Set a transaction identity name/value pair
 
DESCRIPTION
  set_property() sets the name/value pair in the specified index.
PARAMETERS
  index     The array index of a property value between 0 and 19
 
            The array index of a property value in the value array is bound to the property name at the
            same index in the name array. Moving the (name,value) pair to a different index does not
            affect the identity of the transaction. For example, if a transaction registers once with a
            name A and a value X in array indices 0 and once with the same name and value in array
            indices 1, the registered identity has not changed.
  name      A string representing the name part of the (name,value) pair. Each string has a maximum
            length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.
            Names should not contain trailing blank characters or consist of only blank characters.
  value     A string representing the value part of the (name,value) pair. Each string has a maximum
            length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.
            Values should not contain trailing blank characters or consist of only blank characters.
RETURN VALUE
  None
set_uri(...)
set_uri(uri): Set a transaction uri
 
DESCRIPTION
  set_uri() sets the uri for the transaction.
PARAMETERS
  uri       A string representing the the uri of the transaction. This string has a maximum
            length of 4095 characters. If the string is zero-length, the uri is ignored.
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class ArmSubbufferUser(__builtin__.object)
    A user name and/or ID may be optionally associated with each transaction instance. A name is a
character string. An ID is a 16-byte binary value, such as a UUID. Either or both
may be provided.
 
  Methods defined here:
set_user(...)
set_user (name): Set the user name
 
DESCRIPTION
  Sets the user name.
PARAMETERS
  name   A string with a maximum length of 127 characters.
RETURN VALUE
  None

Data and other attributes defined here:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

 
class error(exceptions.Exception)
     Methods inherited from exceptions.Exception:
__getitem__(...)
__init__(...)
__str__(...)

 
Functions
       
bind_thread(...)
bind_thread(tran_handle): bind thread
 
DESCRIPTION
  bind_thread() indicates that the thread from which it is called is performing on behalf of
  the transaction identified by the start handle.
  The thread binding could be useful for managing computing resources at a finer level of
  granularity than a process. There can be any number of threads simultaneously bound to the
  same transaction.
  A transaction remains bound to a thread until either a _discard_transaction(),
  stop_transaction(), or unbind_thread() is executed passing the same start handle.
  bind_thread() and block_transaction() are used independently of each other.
PARAMETERS
  tran_handle   A handle returned a start_transaction() call in the same process.
RETURN VALUE
  None.
block_transaction(...)
block_transaction(tran_handle): block transaction
 
DESCRIPTION
  block_transaction() is used to indicate that the transaction instance is blocked waiting on
  an external transaction (which may or may not be instrumented with ARM) or some other event
  to complete. It has been found useful to separate out this blocked time from the elapsed time
  between the start_transaction() and stop_transaction().
  A transaction remains blocked until unblock_transaction() is executed passing the same
  block_handle, or either a discard_transaction() or stop_transaction() is executed passing the
  same tran_handle.
  The blocking conditions of most interest are those that could result in a significant and/or
  variable length delay relative to the response time of the transaction. For example, a remote
  procedure call would be a good situation to indicate with block_transaction() or
  unblock_transaction(), whereas a disk I/O would not.
  A transaction may be blocked by multiple conditions simultaneously. In many application
  architectures block_transaction() would be called just prior to a thread suspending, because
  the thread is waiting to be signaled that an event has occurred. In other application architectures
  there would not be a tight relationship between the thread behavior and the blocking conditions.
  bind_thread() and block_transaction() are used independently of each other.
PARAMETERS
  tran_handle   An ArmHandle object returned from an start_transaction() call in the same process.
RETURN VALUE
  block_handle  An ArmHandle object that is passed on to unblock_transaction() calls in the same
                process.
destroy_application(...)
destroy_application(app_id): destroy application data
 
DESCRIPTION
  destroy_application() indicates that the registration data about an application previously
  registered with register_application() is no longer needed.
  The purpose of this call is to signal the ARM implementation so it can release any storage it is
  holding. Ending a process or unloading the ARM library results in an implicit
  destroy_application() for any previously registered applications.
  It is possible for multiple register_application() calls to be made in the same process with
  identical identity data. When this is done, destroy_application() is assumed to be paired
  with one register_application(). For example, if register_application() is executed
  twice with the same output ID, and destroy_application() is executed once using this ID, it
  is assumed that an instance of the application is still active and it is not safe to discard the
  application registration data associated with the ID.
PARAMETERS
  app_id        ArmID object returned from a register_application() call in the same
                process.
RETURN VALUE
  None
discard_transaction(...)
discard_transaction(tran_handle): discard transaction
 
DESCRIPTION
  discard_transaction() signals that the referenced start_transaction() should be
  ignored and treated as if it never happened. Measurements associated with a transaction that is
  processing should be discarded. Either discard_transaction() or stop_transaction() is
  used - never both.
  An example of when a transaction would be discarded could happen is if proxy instrumentation
  believes a transaction is starting, but then learns that it did not. It can be called from any thread
  in the process that executed the start_transaction(). In general, the use of
  discard_transaction() is discouraged, but experience has shown a few use cases that
  require the functionality.
  discard_transaction() clears any thread bindings [bind_thread()] and blocking
  conditions [block_transaction()].
PARAMETERS
  tran_handle   A handle returned from an start_transaction() call in the same process.
RETURN VALUE
  None
enable_exceptions(...)
enable_exceptions(enable): enable exception generation
 
DESCRIPTION
  enable_exceptions() is used to control the generation of exceptions by the arm4 module. One of
  the key principles of the ARM standard is that errors in the measurement of applications shouldn't
  affect the applications themselves. In the Python world, this means that no exceptions should
  be generated when the ARM routines encounter an error. Unfortunately this can make debugging
  difficult.
 
  To give the programmer/developer the best of both worlds, exception processing can be turned on
  or off programatically. When debugging the instrumentation, it is best to have the exceptions
  turned on, while production dictates that no exceptions be generated.
 
  By default, exception generation is turned off.
PARAMETERS
  enable       A integer boolean value indicating wether exceptions should be generated.
RETURN VALUE
  None.
generate_correlator(...)
generate_correlator(app_handle, tran_id, [parent, flags, buffer]): generate a correlator
 
DESCRIPTION
  generate_correlator() is used to generate a correlator for use with report_transaction().
 
  A correlator is a correlation token passed from a calling transaction to a called transaction. The
  correlation token may be used to establish a calling hierarchy across processes and systems.
  Applications do not need to understand correlator internals.
 
  It is useful to think about its use in the context of what start_transaction() and
  stop_transaction() do:
  o      start_transaction() performs two functions. It establishes the identity of a transaction
         instance (encapsulated in the current correlator) and begins the measurements of the
         instance. stop_transaction() causes the measurements to be captured. The start
         handle links a start_transaction() and a stop_transaction().
  o      generate_correlator() establishes the identity of a transaction instance, like
         start_transaction(), also encapsulating it in a correlator. It has no relationship to
         measurements about the transaction instance. report_transaction() combines the
         measurement function of both start_transaction() and stop_transaction().
 
  Based on this positioning, it should be clear that generate_correlator() can be used
  whenever an start_transaction() can be used. More specifically, the following calls must
  have been executed first: register_application(), register_transaction(), and
  start_application(). The same parameters are also used, except there's no need for a start
  handle, and there's no need for the arrival time or metric values sub-buffers. The other sub-
  buffers may be used. The correlator that is returned can be used in the same way that a correlator
  returned from start_transaction() is used.
PARAMETERS
  app_handle The ArmHandle object returned from a start_application() call in the same process. The
             ARM implementation may use this handle to access application instance data that
             may become part of the correlator; e.g., the ArmSubbufferSystemAddress object.
  buffer     The ArmBuffer object, if any. The sub-buffers that may be used are
             ArmSubbufferTranContext, and ArmSubbufferUser.
  flags      Contains 32-bit flags. The may be or'ed together as required.
             ARM_FLAG_TRACE_REQUEST is specified if the application requests/suggests a trace.
             ARM_FLAG_CORR_IN_PROCESS is specified if the application is stating that it will not
                    send the correlator outside the current process. An ARM implementation may be
                    able to optimize correlator handling if it knows this, because it may be able
                    to avoid serialization to create the correlator.
  parent_correlator
             An ArmCorrelator object refferring to the parent correlator, if any.
  tran_id    An ArmID transaction ID returned from a register_transaction() call in the same process.
RETURN VALUE
             A ArmCorrelator object which contains a correlator for the transaction instance.
get_arrival_time(...)
get_arrival_time(): store current time
 
DESCRIPTION
  get_arrival_time() stores an opaque representation of the current time.
 
  There are situations in which there is a significant delay between the time when processing of a
  transaction begins and when all the context property values that are needed before
  start_transaction() can be executed are known. In order to get a more accurate response
  time, get_arrival_time() can be used to capture an implementation-defined representation
  of the current time. This value is later stored in the ArmSubbufferArrivalTime sub-buffer when
  start_transaction() executes. The ARM library will use the arrival time as the start time
  rather than the moment when start_transaction() executes.
PARAMETERS
  None
RETURN VALUE
  An ArmArrivalTime object that will contain the arrival time value. Note that the
  value is implementation-defined so the application should not make any
  conclusions based on its contents.
is_charset_supported(...)
is_charset_supported(charset): check character encoding
 
DESCRIPTION
  is_charset_supported() indicates whether an ARM library supports a specified character
  encoding.
 
  The default encoding for all strings provided by the application on all operating systems is
  UTF-8. An application may specify an alternate encoding when executing register_application(),
  and then use it for all strings it provides on all calls including register_application(), but
  should never do so without first issuing is_charset_supported() to test whether the value is
  supported.
 
  An ARM library on the operating systems listed in Table 1 must support the specified
  encodings. Applications are encouraged to use one of these encodings to ensure that any ARM
  implementation will support the application's ARM instrumentation. Another alternative is to
  use one of these encodings along with a preferred encoding. If the ARM library supports the
  preferred encoding, it is used; otherwise, one of the mandatory encodings is used.
 
  IANA                                  Character Set Common       UNIX     Microsoft   IBM      IBM
  MIBenum                                      Name                 and      Windows   OS/400    zOS
                                                                   Linux
 
   3       ARM_CHARSET_ASCII             ASCII-7 (US-ASCII)         Yes      Yes         Yes      Yes
 
   106     ARM_CHARSET_UTF8              UTF-8                      Yes      Yes         Yes      Yes
                                         (UCS-2 characters only)
 
   1014    ARM_CHARSET_UTF16LE           UTF-16 Little Endian                Yes
                                         (UCS-2 characters only)
 
   2028    ARM_CHARSET_IBM037            IBM037                                          Yes
 
   2102    ARM_CHARSET_IBM1047           IBM1047                                                  Yes
 
PARAMETERS
  charset      An IANA (Internet Assigned Numbers Authority - see http://www.iana.org) MIBenum
               value. Support for some values is mandatory by any ARM implementation on a
               specified platform, as shown in the table.
RETURN VALUE
  Boolean object that is set to true or false to indicate whether charset is a supported encoding.
register_application(...)
register_application(app_name, [buffer]): describe application
 
DESCRIPTION
  register_application() describes metadata about an application.
 
  The application uses register_application() to inform the ARM library of metadata about
  the application. This metadata does not change from one application instance to another. It
  contains part of the function of the ARM 2.0 call arm_init(); start_application() contains
  the other part.
 
  ARM generates an ID that is passed in register_transaction() and start_application().
PARAMETERS
  app_name     Pointer to a null-terminated string containing the name of the application. The
               maximum length of the name is 128 characters, including the termination character.
               It serves no purpose and is illegal to make this call if the pointer is null. A name
               should be chosen that is unique, so generic names that might be used by a different
               development team, such as "Payroll Application", should not be used. The name
               should not contain trailing blank characters or consist of only blank characters. If
               the application has a copyrighted product name, the copyrighted name would be a
               good choice.
  buffer       An ArmBuffer object, if any. The sub-buffer formats that might be used are
               ArmSubbufferAppIdentity and ArmSubbufferEncoding.
RETURN VALUE
  An ArmID object app_id.
register_metric(...)
register_metric(app_id, name, format, usage, [units]): describe metrics
 
DESCRIPTION
  register_metric() describes metadata about a metric.
 
  The application uses register_metric() to inform the ARM library of metadata about each
  metric the application provides.
 
  ARM generates an ArmID object that is passed in the ArmSubbufferMetricBindings object
  to register_transaction().
PARAMETERS
  app_id       ArmID object returned from a register_application() call in the same process.
  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 divisor
                     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_int32_t divisor
                     ARM_METRIC_FORMAT_NUMERICID32) = arm_int32_t numeric ID
                     ARM_METRIC_FORMAT_NUMERICID64) = arm_int64_t numeric ID
                     ARM_METRIC_FORMAT_STRING32) = string of a maximum length of 32 characters
  name         A string containing the name of the metric. The maximum length of the string is
               127 characters. The name should not contain trailing blank characters or consist
               of only blank characters.
 
  &