mmv man page

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) or Speed (Golang).

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:

OffsetLengthName
04tag == "MMV\0"
44Version (1 or 2)
88Generation 1
168Generation 2
244Number of TOC entries
284Flags
324Process identifier (PID)
364Cluster 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:

OffsetLengthValue
04Section Type (see mmv_stats.h)
44Number of entries in the section
88Section'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:

OffsetLengthValue
04Unique serial number for this domain
44Number of entries in the domain
88Offset to first Instance or Instance2
168Short help text offset
248Long help text offset

The entries in the Instances (v1) section have the following format:

OffsetLengthValue
08Offset into the indom section
84Unused padding (zero filled)
124Internal instance identifier
1664External instance identifier

The entries in the Instances (v2) section have the following format:

OffsetLengthValue
08Offset into the indom section
84Unused padding (zero filled)
124Internal instance identifier
168External instance identifier string offset

The entries in the Metrics (v1) section have the following format:

OffsetLengthValue
064Metric Name
644Metric Item (see PMDA(3))
684Metric Type (see mmv_stats.h)
724Semantics (see PMAPI(3))
764Dimensions (see PMAPI(3))
804Instance Domain ID
844Unused padding (zero filled)
888Short help text offset
968Long help text offset

The entries in the Metrics (v2) section have the following format:

OffsetLengthValue
08Metric Name string offset
84Metric Item (see PMDA(3))
124Metric Type (see mmv_stats.h)
164Semantics (see PMAPI(3))
204Dimensions (see PMAPI(3))
244Instance Domain ID
284Unused padding (zero filled)
328Short help text offset
408Long help text offset

The entries in the Values section have the following format:

OffsetLengthValue
08pmAtomValue (see PMAPI(3))
88Extra space for STRING and ELAPSED
168Offset into the Metrics section
248Offset 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

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

Referenced By

mmv_inc_value(3), mmv_lookup_value_desc(3), mmv_stats2_init(3), pmdammv(1).

Performance Co-Pilot