MMV(5)

🎀 NAME 🎀

mmv — Memory Mapped Values for Performance Co-Pilot. Bestie, this is the MMV(5) File Formats Manual, and we're about to get intimate with some binary layout 💖

---

✨ SYNOPSIS ✨

$PCP_TMP_DIR/mmv/<file>

---

🌸 DESCRIPTION 🌸

okay so picture this: a whole little directory of files living at $PCP_TMP_DIR/mmv, and every single one of them is a whole vibe. These files get 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 — like Parfait (Java), Speed (Golang), or Hornet (Rust). pick your fighter, they all eat 💅

There could be multiple files in this directory, and each file is representing a single source of the performance metrics. No cap, one file = one source.

So who's collecting all this? That would be pmdammv(1), the main character, which harvests the metrics and exports them to the rest of the Performance Co-Pilot infrastructure. she's doing the most, fr fr ✨

---

🦋 FILE FORMAT 🦋

Every file opens with this exact header, no exceptions:

• Offset 0, Length 4 — tag == "MMV\0"
• Offset 4, Length 4 — Version (1 or 2)
• Offset 8, Length 8 — Generation 1
• Offset 16, Length 8 — Generation 2
• Offset 24, Length 4 — Number of TOC entries
• Offset 28, Length 4 — Flags
• Offset 32, Length 4 — Process identifier (PID)
• Offset 36, Length 4 — Cluster identifier

The version number specifies which mapping layout format is in use. There are two, and 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. So here's the tea: if names longer than MMV_NAMEMAX are not in use, it is best to use MMV version 1 format, because that lets older versions of PCP also consume the data. Iconic behaviour, honestly. 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 they must match for the file to be considered by the MMV PMDA. if they don't match? the MMV PMDA is not looking at you, bestie 💀

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. like, if you're not alive, your metrics aren't either 🙈

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. got it? got it. 👑

---

🍓 The TOC Sections 🍓

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 0, Length 4 — Section Type (see mmv_stats.h)
• Offset 4, Length 4 — Number of entries in the section
• Offset 8, Length 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 — everyone else is optional, they show up when they feel like it ✨

• 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 Indoms Section 🧚

The entries in the Indoms sections have the following format:

• Offset 0, Length 4 — Unique serial number for this domain
• Offset 4, Length 4 — Number of entries in the domain
• Offset 8, Length 8 — Offset to first Instance or Instance2
• Offset 16, Length 8 — Short help text offset
• Offset 24, Length 8 — Long help text offset

---

💜 The Instances (v1) Section 💜

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

• Offset 0, Length 8 — Offset into the indom section
• Offset 8, Length 4 — Unused padding (zero filled)
• Offset 12, Length 4 — Internal instance identifier
• Offset 16, Length 64 — External instance identifier

---

🌈 The Instances (v2) Section 🌈

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

• Offset 0, Length 8 — Offset into the indom section
• Offset 8, Length 4 — Unused padding (zero filled)
• Offset 12, Length 4 — Internal instance identifier
• Offset 16, Length 8 — External instance identifier string offset

---

okay that's the layout dump for now bestie, but we are SO not done — part 2 is pulling up any second and there's more of this file format to devour 🫶✨

🎀 Metrics (v1) entries

okay so if you're reading the Metrics (v1) section, every single entry is laid out exactly like this — the offset is in bytes from the start of the entry, and length is how many bytes that lil field takes up 💅

• Offset 0, length 64 — Metric Name 🌸
• Offset 64, length 4 — Metric Item (see PMDA(3))
• Offset 68, length 4 — Metric Type (see mmv_stats.h)
• Offset 72, length 4 — Semantics (see PMAPI(3))
• Offset 76, length 4 — Dimensions (see PMAPI(3))
• Offset 80, length 4 — Instance Domain ID
• Offset 84, length 4 — Unused padding (zero filled)
• Offset 88, length 8 — Short help text offset
• Offset 96, length 8 — Long help text offset

---

🦋 Metrics (v2) entries

and the Metrics (v2) section? same idea, slightly different drip ✨

• Offset 0, length 8 — Metric Name string offset
• Offset 8, length 4 — Metric Item (see PMDA(3))
• Offset 12, length 4 — Metric Type (see mmv_stats.h)
• Offset 16, length 4 — Semantics (see PMAPI(3))
• Offset 20, length 4 — Dimensions (see PMAPI(3))
• Offset 24, length 4 — Instance Domain ID
• Offset 28, length 4 — Unused padding (zero filled)
• Offset 32, length 8 — Short help text offset
• Offset 40, length 8 — Long help text offset

---

💖 Values entries

the Values section is giving very "four fields and a dream", and honestly? iconic:

• Offset 0, length 8 — pmAtomValue (see PMAPI(3))
• Offset 8, length 8 — Extra space for STRING and ELAPSED
• Offset 16, length 8 — Offset into the Metrics section
• Offset 24, length 8 — Offset into the Instances section

---

🌈 the strings section

each entry in the strings section is a 256 byte character array, holding one single NULL-terminated character string. so yeah, every string maxes out at 256 bytes, and that count includes the terminating NULL. no sneaking extra characters in there, bestie 🙈

---

👑 Labels (v3) entries

the Labels (v3) section entries go like this:

• Offset 0, length 4 — Flags — PM_LABEL_ CLUSTER, ITEM, INDOM, INSTANCES and OPTIONAL
• Offset 4, length 4 — Identifier for given type (indom, cluster or item)
• Offset 8, length 4 — Internal Instance or PM_IN_NULL
• Offset 12, length 244 — Payload (Name and Value JSONB String)

---

🧚 the payload

every entry in the payload is a 244 byte (maximum) character array, holding one single NULL-terminated name:value pair in JSON format.

Insignificant whitespace must not be present. that's not a vibe, that's a rule 💀

label names are made up of only alphanumeric characters or underscores, and they have to begin with an alphabetic. also, upper and lower case characters are considered distinct — so Name and name are two completely different girls, periodt.

---

💜 SEE ALSO

• PCPIntro(1)
• pmdammv(1)
• PMAPI(3)
• PMDA(3)
• mmv_stats_registry(3)
• pcp.conf(5)
• pcp.env(5)

---

and that's the whole page, bestie 🫶 this one came to you straight from Performance Co-Pilot, and it's MMV(5) — go forth and slay those metrics 💅✨