# mmv

## NAME



           **mmv** - Memory Mapped Values for Performance Co-Pilot
    


## SYNOPSIS



           _$PCP_TMP_DIR/mmv/ <file>_
    


## DESCRIPTION



           The files in _$PCP_TMP_DIR/mmv_ are generated either by the
           _mmv_stats_init_(3) and _mmv_stats2_init_(3) functions from the
           **libpcp_mmv** library, or by a native language module such as Parfait
           (Java), Speed (Golang) or Hornet (Rust).
    
           There could be multiple files in this directory, each file
           representing a single source of the performance metrics.  The
           metrics are harvested by pmdammv(1) which exports them to the rest
           of the Performance Co-Pilot infrastructure.
    


## FILE FORMAT



           Each file starts with the following header:
                    ┌────────┬────────┬──────────────────────────┐
                    │ Offset │ Length │           Name           │
                    ├────────┼────────┼──────────────────────────┤
                    │    0   │   4    │ tag == "MMV\0"           │
                    ├────────┼────────┼──────────────────────────┤
                    │    4   │   4    │ Version (1 or 2)         │
                    ├────────┼────────┼──────────────────────────┤
                    │    8   │   8    │ Generation 1             │
                    ├────────┼────────┼──────────────────────────┤
                    │   16   │   8    │ Generation 2             │
                    ├────────┼────────┼──────────────────────────┤
                    │   24   │   4    │ Number of TOC entries    │
                    ├────────┼────────┼──────────────────────────┤
                    │   28   │   4    │ Flags                    │
                    ├────────┼────────┼──────────────────────────┤
                    │   32   │   4    │ Process identifier (PID) │
                    ├────────┼────────┼──────────────────────────┤
                    │   36   │   4    │ Cluster identifier       │
                    └────────┴────────┴──────────────────────────┘
    
           The version number specifies which mapping layout format is in
           use.  There are two, both are very similar, as described below.
           The sole purpose of the MMV version 2 format is to allow the use
           of longer metric and instance names.  If names longer than
           MMV_NAMEMAX are not in use, it is best to use MMV version 1 format
           as this allows older versions of PCP to also consume the data.
           Support for v2 format was added in the pcp-3.11.4 release.
    
           The generation numbers are timestamps at the time of file
           creation, and must match for the file to be considered by the MMV
           PMDA.
    
           The flags can specify ways in which the client would like the MMV
           PMDA to behave - e.g. the MMV_FLAG_PROCESS flag specifies that
           only if the process identified by PID is currently running should
           those values be exported.
    
           Finally, if set, the cluster identifier is a hint to the MMV PMDA
           as to what cluster should be used with this application when
           forming the individual metric identifiers.  A performance metric
           identifier (see _PMDA_(3)) consists of the PMDA domain number, the
           cluster number, and the individual item numbers described in the
           Metrics section.
    
           The header is followed by at least 2 TOC sections: one section for
           metrics and another for values.  The TOC section has the following
           format:
           ┌────────┬────────┬─────────────────────────────────────────────┐
           │ Offset │ Length │                    Value                    │
           ├────────┼────────┼─────────────────────────────────────────────┤
           │   0    │   4    │ Section Type (see _mmv_stats.h_)              │
           ├────────┼────────┼─────────────────────────────────────────────┤
           │   4    │   4    │ Number of entries in the section            │
           ├────────┼────────┼─────────────────────────────────────────────┤
           │   8    │   8    │ Section's offset from the start of the file │
           └────────┴────────┴─────────────────────────────────────────────┘
    
           The section types are:
    
                  1: Indoms (instance domain definitions)
    
                  2: Instances
    
                  3: Metrics (metric definitions)
    
                  4: Values
    
                  5: String
    
                  6: Labels
    
           The only mandatory sections are Metrics and Values.  Indoms and
           Instances sections of either version only appear if there are
           metrics with multiple instances.  String sections only appear if
           there are metrics with string values, when Metrics or Indoms are
           defined with help text, or in v2 MMV format where metric names and
           instance names are stored in string sections (providing
           significantly more space than v1 MMV format for these names).
           Label sections only appear if there are metrics annotated with
           labels (name/value pairs).  Labels are supported in v3 MMV format.
    
           The entries in the Indoms sections have the following format:
              ┌────────┬────────┬───────────────────────────────────────┐
              │ Offset │ Length │                 Value                 │
              ├────────┼────────┼───────────────────────────────────────┤
              │    0   │   4    │ Unique serial number for this domain  │
              ├────────┼────────┼───────────────────────────────────────┤
              │    4   │   4    │ Number of entries in the domain       │
              ├────────┼────────┼───────────────────────────────────────┤
              │    8   │   8    │ Offset to first Instance or Instance2 │
              ├────────┼────────┼───────────────────────────────────────┤
              │   16   │   8    │ Short help text offset                │
              ├────────┼────────┼───────────────────────────────────────┤
              │   24   │   8    │ Long help text offset                 │
              └────────┴────────┴───────────────────────────────────────┘
    
           The entries in the Instances (v1) section have the following
           format:
                  ┌────────┬────────┬───────────────────────────────┐
                  │ Offset │ Length │             Value             │
                  ├────────┼────────┼───────────────────────────────┤
                  │    0   │    8   │ Offset into the indom section │
                  ├────────┼────────┼───────────────────────────────┤
                  │    8   │    4   │ Unused padding (zero filled)  │
                  ├────────┼────────┼───────────────────────────────┤
                  │   12   │    4   │ Internal instance identifier  │
                  ├────────┼────────┼───────────────────────────────┤
                  │   16   │   64   │ External instance identifier  │
                  └────────┴────────┴───────────────────────────────┘
    
           The entries in the Instances (v2) section have the following
           format:
           ┌────────┬────────┬────────────────────────────────────────────┐
           │ Offset │ Length │                   Value                    │
           ├────────┼────────┼────────────────────────────────────────────┤
           │    0   │   8    │ Offset into the indom section              │
           ├────────┼────────┼────────────────────────────────────────────┤
           │    8   │   4    │ Unused padding (zero filled)               │
           ├────────┼────────┼────────────────────────────────────────────┤
           │   12   │   4    │ Internal instance identifier               │
           ├────────┼────────┼────────────────────────────────────────────┤
           │   16   │   8    │ External instance identifier string offset │
           └────────┴────────┴────────────────────────────────────────────┘
    
           The entries in the Metrics (v1) section have the following format:
                  ┌────────┬────────┬───────────────────────────────┐
                  │ Offset │ Length │             Value             │
                  ├────────┼────────┼───────────────────────────────┤
                  │    0   │   64   │ Metric Name                   │
                  ├────────┼────────┼───────────────────────────────┤
                  │   64   │    4   │ Metric Item (see _PMDA_(3))     │
                  ├────────┼────────┼───────────────────────────────┤
                  │   68   │    4   │ Metric Type (see _mmv_stats.h_) │
                  ├────────┼────────┼───────────────────────────────┤
                  │   72   │    4   │ Semantics (see _PMAPI_(3))      │
                  ├────────┼────────┼───────────────────────────────┤
                  │   76   │    4   │ Dimensions (see _PMAPI_(3))     │
                  ├────────┼────────┼───────────────────────────────┤
                  │   80   │    4   │ Instance Domain ID            │
                  ├────────┼────────┼───────────────────────────────┤
                  │   84   │    4   │ Unused padding (zero filled)  │
                  ├────────┼────────┼───────────────────────────────┤
                  │   88   │    8   │ Short help text offset        │
                  ├────────┼────────┼───────────────────────────────┤
                  │   96   │    8   │ Long help text offset         │
                  └────────┴────────┴───────────────────────────────┘
    
           The entries in the Metrics (v2) section have the following format:
                  ┌────────┬────────┬───────────────────────────────┐
                  │ Offset │ Length │             Value             │
                  ├────────┼────────┼───────────────────────────────┤
                  │    0   │   8    │ Metric Name string offset     │
                  ├────────┼────────┼───────────────────────────────┤
                  │    8   │   4    │ Metric Item (see _PMDA_(3))     │
                  ├────────┼────────┼───────────────────────────────┤
                  │   12   │   4    │ Metric Type (see _mmv_stats.h_) │
                  ├────────┼────────┼───────────────────────────────┤
                  │   16   │   4    │ Semantics (see _PMAPI_(3))      │
                  ├────────┼────────┼───────────────────────────────┤
                  │   20   │   4    │ Dimensions (see _PMAPI_(3))     │
                  ├────────┼────────┼───────────────────────────────┤
                  │   24   │   4    │ Instance Domain ID            │
                  ├────────┼────────┼───────────────────────────────┤
                  │   28   │   4    │ Unused padding (zero filled)  │
                  ├────────┼────────┼───────────────────────────────┤
                  │   32   │   8    │ Short help text offset        │
                  ├────────┼────────┼───────────────────────────────┤
                  │   40   │   8    │ Long help text offset         │
                  └────────┴────────┴───────────────────────────────┘
    
           The entries in the Values section have the following format:
               ┌────────┬────────┬────────────────────────────────────┐
               │ Offset │ Length │               Value                │
               ├────────┼────────┼────────────────────────────────────┤
               │    0   │   8    │ **pmAtomValue**(see _PMAPI_(3))         │
               ├────────┼────────┼────────────────────────────────────┤
               │    8   │   8    │ Extra space for STRING and ELAPSED │
               ├────────┼────────┼────────────────────────────────────┤
               │   16   │   8    │ Offset into the Metrics section    │
               ├────────┼────────┼────────────────────────────────────┤
               │   24   │   8    │ Offset into the Instances section  │
               └────────┴────────┴────────────────────────────────────┘
    
           Each entry in the strings section is a 256 byte character array,
           containing a single NULL-terminated character string.  So each
           string has a maximum length of 256 bytes, which includes the
           terminating NULL.
    
           The entries in the Labels (v3) section have the following format:
     ┌────────┬────────┬──────────────────────────────────────────────────────────┐
     │ Offset │ Length │                          Value                           │
     ├────────┼────────┼──────────────────────────────────────────────────────────┤
     │    0   │    4   │ Flags (PM_LABEL_[CLUSTER|ITEM|INDOM|INSTANCES]|OPTIONAL) │
     ├────────┼────────┼──────────────────────────────────────────────────────────┤
     │    4   │    4   │ Identifier for given type (indom, cluster or item)       │
     ├────────┼────────┼──────────────────────────────────────────────────────────┤
     │    8   │    4   │ Internal Instance or PM_IN_NULL                          │
     ├────────┼────────┼──────────────────────────────────────────────────────────┤
     │   12   │  244   │ Payload (Name and Value JSONB String)                    │
     └────────┴────────┴──────────────────────────────────────────────────────────┘
    
           Each entry in the payload is a 244 byte (maximum) character array,
           containing a single NULL-terminated _name_ :_value_ pair in JSON
           format.  Insignificant whitespace must not be present.  Label
           names consist only of alphanumeric characters or underscores, and
           must begin with an alphabetic.  Upper and lower case characters
           are considered distinct.
    


* * *