mas(3mas) mas(3mas)
NAME
mas - introduction to Metric Access Support (MAS)
SYNOPSIS
cc [options] file -lmas
#include <mas.h>
DESCRIPTION
The Metric Access Support (MAS) functions allow applications
to advertise and gather performance metrics. MAS removes
machine dependencies from user level raw metric gathering by
providing a common programming interface for metric
information from both the system and user applications.
Overview
Metric data are supplied by a provider, which can be either an
application or the operating system, and are collected by a
consumer application. Metric identification is primarily
based on ID numbers. Providers are responsible for
registering the ID numbers and other pertinent information
about metrics into MAS. Consumers then access a metric
registration file with the MAS library functions and can
access the registered information and metrics. Raw metric
data is file based. Access to metrics is provided by either a
read/write interface or through memory mapping.
Function Overview
The MAS functions are broken into several categories:
MAS Provider Functions are called by systems or
applications that want to make metrics available. If
user programs want to make metrics available via memory
mapping, they are responsible for allocating their
metrics within the address space of a memory mapped
file.
MAS Consumer Functions are called by applications that
want to use metric data. Applications can request
either read or memory mapped access to metric data. If
memory mapped access is used, MAS automatically sets up
a mapping of the metrics data in the consumer's address
space.
MAS Type-Specific Functions have been separated from the
rest of the libraries because they have some notion of
the layout of particular data types. These are kept
Copyright 1994 Novell, Inc. Page 1
mas(3mas) mas(3mas)
separate for ease of porting and continuing development.
MAS Error Functions are common to both the consumers and
providers, and are used to record and report error
conditions.
Data Overview
In order to allow data structures to be extensible in future
releases, the metric registration information is separated
into several areas:
The MAS header contains information necessary to get and
interpret all of the other registration information.
Essentially it is a bootstrap data structure. It
contains a magic number, status information, word size,
byte ordering, access methods, and information about the
locations of the remaining data structures.
The metric registration table header contains the size
of the metric registration table, as well as the sizes
of elementary objects such as ID numbers and units
fields. These elementary objects are referred to as
metadata.
The metric registration table is the table of registered
metrics. Each entry has the following information:
a status word
the size of a metric object
the number of objects ( > 1 implies the metric is
an array)
the number of instances of the metric; for example
usr time on a 4-CPU system would have 4 instances
a pointer to the ID number (which is kept in
metadata)
a pointer the name string (which is kept in
strings)
a pointer to the units of the metric (which is
kept in metadata)
Copyright 1994 Novell, Inc. Page 2
mas(3mas) mas(3mas)
a pointer the units string (which is kept in
strings)
a pointer to the list of resources (which is kept
in metadata); for example usr time would have one
resource, which would be the ID number for the
number of CPUs on the system. Avg dsk wait queue
would have the number of disks on the system as
the resource. A metric that was kept per file
system and per CPU would have two resources: the
number of CPUs and the number of file systems.
a pointer to the list of metric data segment
numbers (which are kept in metadata); MAS allows
many metric files to be mapped in as metric
segments, since a provider may not have all of its
metrics collected into a common area. The list of
segment numbers identifies in which segment a
particular instance of a resides.
a pointer to the list of metrics addresses (which
are kept in metadata); the metric addresses kept
in metadata point to the actual metrics which
reside in the various metric data segments.
Metadata holds all of the things that MAS may not know
the size of before it reads the various headers and
tables. Because these things may be different sizes on
different architectures, they are not specified as
having particular sizes in mas.h. Instead they are
referred to by pointer, with their sizes bound at run
time.
The strings table contains all of the text strings
associated with the metric and units names. Eventually
the string handling will be expanded to encompass
internationalization support.
The metrics data segments contain the actual metric
data. Because a provider may have several files and/or
several ranges of addresses from which it would like to
provide metrics, MAS allows a provider to specify
multiple metric segments. Each segment is identified
by:
Copyright 1994 Novell, Inc. Page 3
mas(3mas) mas(3mas)
file name
the start offset within the file
segment size
Provider Functions
There are only four provider functions. One to initialize,
one to register an instance of metric data, one to make
everything available after some registration has taken place,
and one to write the metrics if memory mapping is not being
used. These functions are:
mas_init initializes the MAS header structures, sets
dynamic vs. static registration, and sets file names for
the various MAS structs.
mas_register_met registers a single instance of a
metric.
mas_put, on first invocation, creates the registration
file(s) and writes the registration information. On
subsequent calls, it updates the registration files with
newly registered metrics.
mas_write_mets is called to write the metrics data
segments to their appropriate files when memory mapped
access is not being used. If memory mapping is being
used, it does not need to be called.
Consumer Functions
The consumer functions fall into several categories. The MAS
management functions are used for accessing a registration
file and capturing the metrics. The MAS get metric functions
are used to access the metric registration data and to
determine the addresses at which the metrics resides. The MAS
get MAS header and get metric registration table (mrt) header
functions return information about the configuration of MAS on
the system that performed the metric registration.
There are three MAS management functions:
mas_open opens a metric registration file.
Copyright 1994 Novell, Inc. Page 4
mas(3mas) mas(3mas)
mas_snap takes a snapshot of the metrics.
mas_close closes the metric registration file.
The MAS get metric functions functions return information
about individual metrics. A few of the more important
functions are:
mas_get_met_id, which returns the ID number of the
metric in a particular slot of the metric
registration table, and can be used to list the
contents of a registration file.
mas_get_met and mas_get_met_snap, which return the
address of an instance of a metric within its
memory mapped metric data segment and within the
snap shot buffer, respectively.
The remaining MAS get metric functions return the
name, status word, units, units name, object size,
number of objects, total possible instances, and
the resource list for a particular metric. For
more information about these functions, see
mas_get_metadata(3mas).
The MAS get metric registration table header
functions and MAS get MAS header functions return
information that is contained within the metric
registration table (mrt) header and the top level
MAS header structure. The mrt header contains the
size of the header structure, the size of an mrt
entry, the number of mrt entries, the size of an
ID number, the size of a units field, and the size
of a resource. The MAS header contains
information about how MAS was configured on the
system that registered the metrics, including the
magic number, bytes per word, byte ordering
information, the size of the MAS header structure
and the access methods supported. The MAS header
structure also contains filename and addressing
information about the following data areas: the
top level MAS header, the metric registration
table header, the metric registration table, the
strings table, the metadata, and the metric data
segments.
Copyright 1994 Novell, Inc. Page 5
mas(3mas) mas(3mas)
It is unlikely that consumer applications would
ever need to access most of the structure elements
that the MAS get header functions return.
However, they are provided should such a need
occur. Portable metric applications should make no
assumptions whatsoever about the size and layout
of the MAS data structures, and should only access
structure elements through these functions. For
more information, see mas_get_header(3mas).
Type-Specific Interface Functions
The MAS type-specific functions are used to manipulate
metadata objects. These are needed because metadata objects
may change size between various systems and platforms, or in
future releases. These functions fall into several
categories. There are comparative functions, copy functions,
name size functions, and sanity checks. For more information
about the type-specific functions, see mas_type(3mas).
Error Functions
The MAS error functions report error codes and error strings.
For more information about the MAS error functions, see
mas_error(3mas).
REFERENCES
mas_close(3mas), mas_error(3mas), mas_get_header(3mas),
mas_get_met(3mas), mas_get_metadata(3mas),
mas_get_met_id(3mas), mas_init(3mas), mas_open(3mas),
mas_put(3mas), mas_register_met(3mas), mas_snap(3mas),
mas_type(3mas)
Copyright 1994 Novell, Inc. Page 6