1MMV(5) File Formats Manual MMV(5)
2
6 mmv - Memory Mapped Values for Performance Co-Pilot
7
9 $PCP_TMP_DIR/mmv/<file>
10
12 The files in $PCP_TMP_DIR/mmv are generated either by the
13 mmv_stats_init(3) and mmv_stats2_init(3) functions from the libpcp_mmv
14 library, or by a native language module such as Parfait (Java), Speed
15 (Golang) or Hornet (Rust).
16 There could be multiple files in this directory, each file representing
18 a single source of the performance metrics. The metrics are harvested
19 by pmdammv(1) which exports them to the rest of the Performance Co-Pi‐
20 lot infrastructure.
21
23 Each file starts with the following header:
24 ┌───────┬────────┬──────────────────────────┐
26 │Offset │ Length │ Name │
27 ├───────┼────────┼──────────────────────────┤
28 │ 0 │ 4 │ tag == "MMV\0" │
29 ├───────┼────────┼──────────────────────────┤
30 │ 4 │ 4 │ Version (1 or 2) │
31 ├───────┼────────┼──────────────────────────┤
32 │ 8 │ 8 │ Generation 1 │
33 ├───────┼────────┼──────────────────────────┤
34 │ 16 │ 8 │ Generation 2 │
35 ├───────┼────────┼──────────────────────────┤
36 │ 24 │ 4 │ Number of TOC entries │
37 ├───────┼────────┼──────────────────────────┤
38 │ 28 │ 4 │ Flags │
39 ├───────┼────────┼──────────────────────────┤
40 │ 32 │ 4 │ Process identifier (PID) │
41 ├───────┼────────┼──────────────────────────┤
42 │ 36 │ 4 │ Cluster identifier │
43 └───────┴────────┴──────────────────────────┘
44 The version number specifies which mapping layout format is in use.
45 There are two, both are very similar, as described below. The sole
46 purpose of the MMV version 2 format is to allow the use of longer met‐
47 ric and instance names. If names longer than MMV_NAMEMAX are not in
48 use, it is best to use MMV version 1 format as this allows older ver‐
49 sions of PCP to also consume the data. Support for v2 format was added
50 in the pcp-3.11.4 release.
51 The generation numbers are timestamps at the time of file creation, and
53 must match for the file to be considered by the MMV PMDA.
54 The flags can specify ways in which the client would like the MMV PMDA
56 to behave - e.g. the MMV_FLAG_PROCESS flag specifies that only if the
57 process identified by PID is currently running should those values be
58 exported.
59 Finally, if set, the cluster identifier is a hint to the MMV PMDA as to
61 what cluster should be used with this application when forming the in‐
62 dividual metric identifiers. A performance metric identifier (see
63 PMDA(3)) consists of the PMDA domain number, the cluster number, and
64 the individual item numbers described in the Metrics section.
65 The header is followed by at least 2 TOC sections: one section for met‐
67 rics and another for values. The TOC section has the following format:
68 ┌───────┬────────┬─────────────────────────────────────────────┐
70 │Offset │ Length │ Value │
71 ├───────┼────────┼─────────────────────────────────────────────┤
72 │ 0 │ 4 │ Section Type (see mmv_stats.h) │
73 ├───────┼────────┼─────────────────────────────────────────────┤
74 │ 4 │ 4 │ Number of entries in the section │
75 ├───────┼────────┼─────────────────────────────────────────────┤
76 │ 8 │ 8 │ Section's offset from the start of the file │
77 └───────┴────────┴─────────────────────────────────────────────┘
78 The section types are:
79 1: Indoms (instance domain definitions)
81 2: Instances
83 3: Metrics (metric definitions)
85 4: Values
87 5: String
89 6: Labels
91 The only mandatory sections are Metrics and Values. Indoms and In‐
93 stances sections of either version only appear if there are metrics
94 with multiple instances. String sections only appear if there are met‐
95 rics with string values, when Metrics or Indoms are defined with help
96 text, or in v2 MMV format where metric names and instance names are
97 stored in string sections (providing significantly more space than v1
98 MMV format for these names). Label sections only appear if there are
99 metrics annotated with labels (name/value pairs). Labels are supported
100 in v3 MMV format.
101 The entries in the Indoms sections have the following format:
103 ┌───────┬────────┬───────────────────────────────────────┐
105 │Offset │ Length │ Value │
106 ├───────┼────────┼───────────────────────────────────────┤
107 │ 0 │ 4 │ Unique serial number for this domain │
108 ├───────┼────────┼───────────────────────────────────────┤
109 │ 4 │ 4 │ Number of entries in the domain │
110 ├───────┼────────┼───────────────────────────────────────┤
111 │ 8 │ 8 │ Offset to first Instance or Instance2 │
112 ├───────┼────────┼───────────────────────────────────────┤
113 │ 16 │ 8 │ Short help text offset │
114 ├───────┼────────┼───────────────────────────────────────┤
115 │ 24 │ 8 │ Long help text offset │
116 └───────┴────────┴───────────────────────────────────────┘
117 The entries in the Instances (v1) section have the following format:
118 ┌───────┬────────┬───────────────────────────────┐
120 │Offset │ Length │ Value │
121 ├───────┼────────┼───────────────────────────────┤
122 │ 0 │ 8 │ Offset into the indom section │
123 ├───────┼────────┼───────────────────────────────┤
124 │ 8 │ 4 │ Unused padding (zero filled) │
125 ├───────┼────────┼───────────────────────────────┤
126 │ 12 │ 4 │ Internal instance identifier │
127 ├───────┼────────┼───────────────────────────────┤
128 │ 16 │ 64 │ External instance identifier │
129 └───────┴────────┴───────────────────────────────┘
130 The entries in the Instances (v2) section have the following format:
131 ┌───────┬────────┬────────────────────────────────────────────┐
133 │Offset │ Length │ Value │
134 ├───────┼────────┼────────────────────────────────────────────┤
135 │ 0 │ 8 │ Offset into the indom section │
136 ├───────┼────────┼────────────────────────────────────────────┤
137 │ 8 │ 4 │ Unused padding (zero filled) │
138 ├───────┼────────┼────────────────────────────────────────────┤
139 │ 12 │ 4 │ Internal instance identifier │
140 ├───────┼────────┼────────────────────────────────────────────┤
141 │ 16 │ 8 │ External instance identifier string offset │
142 └───────┴────────┴────────────────────────────────────────────┘
143 The entries in the Metrics (v1) section have the following format:
144 ┌───────┬────────┬───────────────────────────────┐
146 │Offset │ Length │ Value │
147 ├───────┼────────┼───────────────────────────────┤
148 │ 0 │ 64 │ Metric Name │
149 ├───────┼────────┼───────────────────────────────┤
150 │ 64 │ 4 │ Metric Item (see PMDA(3)) │
151 ├───────┼────────┼───────────────────────────────┤
152 │ 68 │ 4 │ Metric Type (see mmv_stats.h) │
153 ├───────┼────────┼───────────────────────────────┤
154 │ 72 │ 4 │ Semantics (see PMAPI(3)) │
155 ├───────┼────────┼───────────────────────────────┤
156 │ 76 │ 4 │ Dimensions (see PMAPI(3)) │
157 ├───────┼────────┼───────────────────────────────┤
158 │ 80 │ 4 │ Instance Domain ID │
159 ├───────┼────────┼───────────────────────────────┤
160 │ 84 │ 4 │ Unused padding (zero filled) │
161 ├───────┼────────┼───────────────────────────────┤
162 │ 88 │ 8 │ Short help text offset │
163 ├───────┼────────┼───────────────────────────────┤
164 │ 96 │ 8 │ Long help text offset │
165 └───────┴────────┴───────────────────────────────┘
166 The entries in the Metrics (v2) section have the following format:
167 ┌───────┬────────┬───────────────────────────────┐
169 │Offset │ Length │ Value │
170 ├───────┼────────┼───────────────────────────────┤
171 │ 0 │ 8 │ Metric Name string offset │
172 ├───────┼────────┼───────────────────────────────┤
173 │ 8 │ 4 │ Metric Item (see PMDA(3)) │
174 ├───────┼────────┼───────────────────────────────┤
175 │ 12 │ 4 │ Metric Type (see mmv_stats.h) │
176 ├───────┼────────┼───────────────────────────────┤
177 │ 16 │ 4 │ Semantics (see PMAPI(3)) │
178 ├───────┼────────┼───────────────────────────────┤
179 │ 20 │ 4 │ Dimensions (see PMAPI(3)) │
180 ├───────┼────────┼───────────────────────────────┤
181 │ 24 │ 4 │ Instance Domain ID │
182 ├───────┼────────┼───────────────────────────────┤
183 │ 28 │ 4 │ Unused padding (zero filled) │
184 ├───────┼────────┼───────────────────────────────┤
185 │ 32 │ 8 │ Short help text offset │
186 ├───────┼────────┼───────────────────────────────┤
187 │ 40 │ 8 │ Long help text offset │
188 └───────┴────────┴───────────────────────────────┘
189 The entries in the Values section have the following format:
190 ┌───────┬────────┬────────────────────────────────────┐
192 │Offset │ Length │ Value │
193 ├───────┼────────┼────────────────────────────────────┤
194 │ 0 │ 8 │ pmAtomValue (see PMAPI(3)) │
195 ├───────┼────────┼────────────────────────────────────┤
196 │ 8 │ 8 │ Extra space for STRING and ELAPSED │
197 ├───────┼────────┼────────────────────────────────────┤
198 │ 16 │ 8 │ Offset into the Metrics section │
199 ├───────┼────────┼────────────────────────────────────┤
200 │ 24 │ 8 │ Offset into the Instances section │
201 └───────┴────────┴────────────────────────────────────┘
202 Each entry in the strings section is a 256 byte character array, con‐
203 taining a single NULL-terminated character string. So each string has
204 a maximum length of 256 bytes, which includes the terminating NULL.
205 The entries in the Labels (v3) section have the following format:
207 ┌───────┬────────┬──────────────────────────────────────────────────────────┐
209 │Offset │ Length │ Value │
210 ├───────┼────────┼──────────────────────────────────────────────────────────┤
211 │ 0 │ 4 │ Flags (PM_LABEL_[CLUSTER|ITEM|INDOM|INSTANCES]|OPTIONAL) │
212 ├───────┼────────┼──────────────────────────────────────────────────────────┤
213 │ 4 │ 4 │ Identifier for given type (indom, cluster or item) │
214 ├───────┼────────┼──────────────────────────────────────────────────────────┤
215 │ 8 │ 4 │ Internal Instance or PM_IN_NULL │
216 ├───────┼────────┼──────────────────────────────────────────────────────────┤
217 │ 12 │ 244 │ Payload (Name and Value JSONB String) │
218 └───────┴────────┴──────────────────────────────────────────────────────────┘
219 Each entry in the payload is a 244 byte (maximum) character array, con‐
220 taining a single NULL-terminated name:value pair in JSON format. In‐
221 significant whitespace must not be present. Label names consist only
222 of alphanumeric characters or underscores, and must begin with an al‐
223 phabetic. Upper and lower case characters are considered distinct.
224
226 PCPIntro(1), pmdammv(1), PMAPI(3), PMDA(3), mmv_stats_registry(3),
227 pcp.conf(5) and pcp.env(5).
228Performance Co-Pilot MMV(5)