1MMV(5)                        File Formats Manual                       MMV(5)
2
3
4

NAME

6       mmv - Memory Mapped Values for Performance Co-Pilot
7

SYNOPSIS

9       $PCP_TMP_DIR/mmv/<file>
10

DESCRIPTION

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
17       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-
20       Pilot infrastructure.
21

FILE FORMAT

23       Each file starts with the following header:
24
25                    ┌───────┬────────┬──────────────────────────┐
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
52       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
55       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
60       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
62       individual  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
66       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
69           ┌───────┬────────┬─────────────────────────────────────────────┐
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
80              1: Indoms (instance domain definitions)
81
82              2: Instances
83
84              3: Metrics (metric definitions)
85
86              4: Values
87
88              5: String
89
90              6: Labels
91
92       The only  mandatory  sections  are  Metrics  and  Values.   Indoms  and
93       Instances  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
102       The entries in the Indoms sections have the following format:
103
104              ┌───────┬────────┬───────────────────────────────────────┐
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
119                  ┌───────┬────────┬───────────────────────────────┐
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
132           ┌───────┬────────┬────────────────────────────────────────────┐
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
145                  ┌───────┬────────┬───────────────────────────────┐
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
168                  ┌───────┬────────┬───────────────────────────────┐
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
191               ┌───────┬────────┬────────────────────────────────────┐
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
206       The entries in the Labels (v3) section have the following format:
207
208     ┌───────┬────────┬──────────────────────────────────────────────────────────┐
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.
221       Insignificant whitespace must not be present.  Label names consist only
222       of  alphanumeric  characters  or  underscores,  and  must begin with an
223       alphabetic.  Upper and lower case characters are considered distinct.
224

SEE ALSO

226       PCPIntro(1), pmdammv(1), PMAPI(3), mmv_stats_init(3),  pcp.conf(5)  and
227       pcp.env(5).
228
229
230
231Performance Co-Pilot                                                    MMV(5)
Impressum