man/man5/mmv.5

   1 '\"! tbl | nroff \-man
   2 '\"macro stdmacro
   3 .\"
   4 .\" Copyright (c) 2009 Max Matveev
   5 .\" Copyright (c) 2009 Aconex.  All Rights Reserved.
   6 .\"
   7 .\" This program is free software; you can redistribute it and/or modify it
   8 .\" under the terms of the GNU General Public License as published by the
   9 .\" Free Software Foundation; either version 2 of the License, or (at your
  10 .\" option) any later version.
  11 .\"
  12 .\" This program is distributed in the hope that it will be useful, but
  13 .\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14 .\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 .\" for more details.
  16 .\"
  17 .\"
  18 .TH MMV 5 "" "Performance Co-Pilot"
  19 .SH NAME
  20 \f3mmv\f1 \- Memory Mapped Values for Performance Co-Pilot
  21 .SH SYNOPSIS
  22 .I $PCP_TMP_DIR/mmv/<file>
  23 .SH DESCRIPTION
  24 The files in \f2$PCP_TMP_DIR/mmv\f1 are generated by
  25 \f2mmv_stats_init\f1() function from \f3libpcp_mmv\f1 library. There could
  26 be multiple files in this directory, each file representing a single source
  27 of the performance metrics. The metrics are harvested by the \f2mmv\f1 PMDA
  28 which exports them to the rest of the Performance Co-Pilot infrastructure.
  29 .SH FILE FORMAT
  30 Each file starts with the following header:
  31 .TS
  32 box,center;
  33 c | c | c
  34 n | n | l.
  35 Offset  Length  Name
  36 _
  37 0       4       tag == "MMV\\0"
  38 _
  39 4       4       Version
  40 _
  41 8       8       Generation 1
  42 _
  43 16      8       Generation 2
  44 _
  45 24      4       Number of TOC entries
  46 _
  47 28      4       Flags
  48 _
  49 32      4       Process identifier (PID)
  50 _
  51 36      4       Cluster identifier
  52 .TE
  53 .PP
  54 .PP
  55 The generation numbers are timestamps at the time of file
  56 creation, and must match for the file to be considered by
  57 the MMV PMDA.
  58 .PP
  59 The flags can specify ways in which the client would like
  60 the MMV PMDA to behave - e.g. the MMV_FLAG_PROCESS flag
  61 specifies that only if the process identified by PID is
  62 currently running should those values be exported.
  63 .PP
  64 Finally, if set, the cluster identifier is a hint to the MMV
  65 PMDA as to what cluster should be used with this application
  66 when forming the individual metric identifiers.
  67 A performance metric identifier (see \f2PMDA\f1(3)) consists of
  68 the PMDA domain number, the cluster number, and the individual
  69 item numbers described in the Metrics section.
  70 .PP
  71 The header is followed by at least 2 TOC sections:
  72 one section for metrics and another for values.
  73 The TOC section has the following format:
  74 .TS
  75 box,center;
  76 c | c | c
  77 n | n | l.
  78 Offset  Length  Value
  79 _
  80 0       4       Section Type (see \f2mmv_stats.h\f1)
  81 _
  82 4       4       Number of entries in the section
  83 _
  84 8       8       Section's offset from the start of the file
  85 .TE
  86 .PP
  87 .PP
  88 The section types are:
  89 .IP
  90 1:
  91 Indoms (instance domain definitions)
  92 .IP
  93 2:
  94 Instances
  95 .IP
  96 3:
  97 Metrics (metric definitions)
  98 .IP
  99 4:
 100 Values
 101 .IP
 102 5:
 103 String
 104 .PP
 105 The only mandatory sections are Metrics and Values.
 106 Indoms and Instances sections only appear if there are metrics with
 107 multiple instances.
 108 String sections only appear if there are metrics with string values,
 109 or when Metrics or Indoms are defined with help text.
 110 .PP
 111 The entries in the Indoms section have the following format:
 112 .TS
 113 box,center;
 114 c | c | c
 115 n | n | l.
 116 Offset  Length  Value
 117 _
 118 0       4       Unique serial number for this domain
 119 _
 120 4       4       Number of entries in the domain
 121 _
 122 8       8       Offset to first instance
 123 _
 124 16      8       Short help text offset
 125 _
 126 24      8       Long help text offset
 127 .TE
 128 .PP
 129 .PP
 130 The entries in the Instances section have the following format:
 131 .TS
 132 box,center;
 133 c | c | c
 134 n | n | l.
 135 Offset  Length  Value
 136 _
 137 0       8       Offset into the indom section
 138 _
 139 8       4       Unused padding (zero filled)
 140 _
 141 12      4       Internal instance identifier
 142 _
 143 16      64      External instance identifier
 144 .TE
 145 .PP
 146 .PP
 147 The entries in the Metrics section have the following format:
 148 .TS
 149 box,center;
 150 c | c | c
 151 n | n | l.
 152 Offset  Length  Value
 153 _
 154 0       64      Metric Name
 155 _
 156 64      4       Metric Item (see \f2PMDA\f1(3))
 157 _
 158 68      4       Metric Type (see \f2mmv_stats.h\f1)
 159 _
 160 72      4       Semantics (see \f2PMAPI\f1(3))
 161 _
 162 76      4       Dimensions (see \f2PMAPI\f1(3))
 163 _
 164 80      4       Instance Domain ID
 165 _
 166 84      4       Unused padding (zero filled)
 167 _
 168 88      8       Short help text offset
 169 _
 170 96      8       Long help text offset
 171 .TE
 172 .PP
 173 .PP
 174 The entries in the Values section have the following format:
 175 .TS
 176 box,center;
 177 c | c | c
 178 n | n | l.
 179 Offset  Length  Value
 180 _
 181 0       8       \f3pmAtomValue\f1 (see \f2PMAPI\f1(3))
 182 _
 183 8       8       Extra space for STRING and ELAPSED
 184 _
 185 16      8       Offset into the Metrics section
 186 _
 187 24      8       Offset into the Instances section
 188 .TE
 189 .PP
 190 .PP
 191 Each entry in the strings section is a 256 byte character array,
 192 containing a single NULL-terminated character string.
 193 So each string has a maximum length of 256 bytes, which includes
 194 the terminating NULL.
 195 .PP
 196 .SH SEE ALSO
 197 .BR PCPIntro (1),
 198 .BR PMAPI (3),
 199 .BR mmv_stats_init (3),
 200 .BR pcp.conf (5)
 201 and
 202 .BR pcp.env (5).