|
NAME | SYNOPSIS | DESCRIPTION | FILE FORMAT | SEE ALSO | COLOPHON |
MMV(5) File Formats Manual MMV(5)
mmv - Memory Mapped Values for Performance Co-Pilot
$PCP_TMP_DIR/mmv/<file>
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.
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.
PCPIntro(1), pmdammv(1), PMAPI(3), mmv_stats_init(3), pcp.conf(5) and
pcp.env(5).
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)