Provided by: libpcp-mmv1-dev_6.0.5-1_amd64 bug

NAME

       mmv_stats_registry,  mmv_stats_start,  mmv_stats_stop - Initialize the Memory Mapped Value
       file

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/mmv_stats.h>

       mmv_registry_t *mmv_stats_registry(const char *file, int cluster,
                                           mmv_stats_flags_t flags);

       void *mmv_stats_start(mmv_registry_t *registry);
       void  mmv_stats_stop(const char *fname, void *addr);

       cc ... -lpcp_mmv -lpcp

DESCRIPTION

       mmv_stats_registry initializes an opaque structure  that  defines  various  aspects  of  a
       memory  mapped file.  This file is used for lightweight interprocess communication between
       an instrumented application and pmdammv(1).

       The mmv_stats_registry interface is used to allocate a registry, and allows  the  name  of
       the  MMV(5)  file,  the cluster identifier and the flags (if any) to be set.  It returns a
       handle that is used in subsequent MMV API calls when adding metrics, indoms, instances and
       labels to the registry - before actually creating the file.

       mmv_stats_start  is  the  call  that  creates the MMV(5) file with the handle that returns
       mmv_stats_registry.  It returns the mapped memory handle used in subsequent MMV API calls,
       such as mmv_inc_value(3).

       mmv_stats_stop  performs  an orderly shutdown of the mapping handle returned by an earlier
       initialization call and also frees the registry structure.

       The combination of mmv_stats_registry and mmv_stats_start do the same  as  the  deprecated
       calls  mmv_stats(2)_init.  However, now, one should first call mmv_stats_registry and then
       the API calls that add instances, indoms, metrics and labels.  In this way,  there  is  no
       need  to  know  in  advance  which version of the MMV(1|2|3) mapping will be used as it is
       calculated automatically.

       The file is created in the $PCP_TMP_DIR/mmv directory, the name argument is expected to be
       a  basename  of  the  file,  not the full path.  The metadata content of the file does not
       change after the file has been created.

       The old file is removed unconditionally unless there was an error.

       cluster is the preferred MMV PMDA cluster ID to be used for the metrics the originates the
       call  mmv_stats_start.  The flags provide additional control over the behaviour of the MMV
       PMDA - e.g. use of  MMV_FLAG_PROCESS  will  ensure  values  are  only  exported  when  the
       instrumented application is running - this is verified on each request for new values.

       The next sections explain how to add metrics, indoms, instances and labels.

ADD METRICS

       int mmv_stats_add_metric(mmv_registry_t *registry, const char *name, int item,
                               mmv_metric_type_t type, mmv_metric_sem_t sem, pmUnits units,
                               int serial, const char *shorthelp, const char *longhelp);

       When  adding a metric, internally it is being handled using the next struct.  sem match in
       the struct is semantics. units match in the struct  is  dimension.  serial  match  in  the
       struct is indom.

               typedef struct {
                   char *name;                 /* Name of the metric */
                   __uint32_t item;            /* Item component of PMID */
                   mmv_metric_type_t type;     /* Type of the metric */
                   mmv_metric_sem_t semantics; /* Semantics of the metric */
                   pmUnits dimension;          /* Dimensions (TIME,SPACE,etc) */
                   __uint32_t indom;           /* Instance domain identifier */
                   char *shorttext;            /* Optional, one-line help */
                   char *helptext;             /* Optional, full help text */
               } mmv_metric2_t;

ADD INDOMS

       int mmv_stats_add_indom(mmv_registry_t *registry, int serial,
                               const char *shorthelp, const char *longhelp);

       When adding an indom, internally it is being handled using the next struct.

               typedef struct {
                   __uint32_t serial;           /* Unique serial number */
                   __uint32_t count;            /* Number of instances */
                   mmv_instances2_t *instances; /* Internal/external IDs */
                   char *shorttext;             /* Short help text */
                   char *helptext;              /* Long help text */
               } mmv_indom2_t;

ADD INSTANCES

       int mmv_stats_add_instance(mmv_registry_t *registry, int serial,
                                  int instid, const char *instname);

       When  adding  an  instance,  internally it is being handled using the next struct.  instid
       match in the struct is internal while instname is external.

               typedef struct {
                   __int32_t internal;
                   char *external;
               } mmv_instances2_t;

       It is worth mentioning that if the indom of the instance is not found it returns an error.

ADD LABELS

       int mmv_stats_add_registry_label(mmv_registry_t *registry,
                                        const char *name, const char *value,
                                        mmv_value_type_t type, int optional);

       int mmv_stats_add_indom_label(mmv_registry_t *registry, int serial,
                                     const char *name, const char *value,
                                     mmv_value_type_t type, int optional);

       int mmv_stats_add_metric_label(mmv_registry_t *registry, int item,
                                      const char *name, const char *value,
                                      mmv_value_type_t type, int optional);

       int mmv_stats_add_instance_label(mmv_registry_t *registry, int serial,
                                        int instid, const char *name, const char *value,
                                        mmv_value_type_t type, int optional);

       registry is the handle obtained from mmv_stats_registry. name and value are the strings
               that will form the label.

       type specifies the value type that can be: MMV_STRING_TYPE, MMV_NUMBER_TYPE,
       MMV_BOOLEAN_TYPE, MMV_NULL_TYPE, MMV_ARRAY_TYPE and MMV_MAP_TYPE.

       At the moment there is a simple check of the correctness of the value.  After adding a
       label, it is called a function to verify if it is correct.

       Additionally, if optional is set, it is added the flag PM_LABEL_OPTIONAL.

       serial is the serial of the indom when adding an indom or instance label.  item is the
       metric identifier when adding a metric label. Finally, when adding a registry label it is
       not necessary to give the cluster id because it will be taken from the internal registry
       struct already created.

       mmv_stats_add_registry_label adds a PM_LABEL_CLUSTER.

       mmv_stats_add_indom_label adds a PM_LABEL_INDOM.

       mmv_stats_add_metric_label adds a PM_LABEL_ITEM.

       mmv_stats_add_instance_label adds a PM_LABEL_INSTANCES.

RETURN VALUES

        When adding metrics, indoms, instances and labels, if correct returns 0
        and if not it returns an errno code. The other functions return the address
        of the memory mapped region on success. On failure, NULL is returned and
        errno is set to a value suitable for decoding with strerror(3).

SEE ALSO

       mmv_inc_value(3), mmv_lookup_value_desc(3), strerror(3) and mmv(5).