NAME | SYNOPSIS | DESCRIPTION | FILE FORMAT | SEE ALSO | COLOPHON

MMV(5)                       File Formats Manual                      MMV(5)

NAME         top

       mmv - Memory Mapped Values for Performance Co-Pilot

SYNOPSIS         top

       $PCP_TMP_DIR/mmv/<file>

DESCRIPTION         top

       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         top

       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

       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).

       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.

SEE ALSO         top

       PCPIntro(1), pmdammv(1), PMAPI(3), mmv_stats_init(3), pcp.conf(5) and
       pcp.env(5).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05.  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

Performance Co-Pilot                                                  MMV(5)

Pages that refer to this page: pmdammv(1)mmv_inc_value(3)mmv_lookup_value_desc(3)mmv_stats_init(3)