pmResult
After the archive log label record, an archive volume file
contains metric values corresponding to the pmResult set of one
pmFetch operation, which is almost identical to the form on disk.
The record size may vary according to number of PMIDs being
fetched, the number of instances for their domains. File size is
limited to 2GiB, due to storage of 32-bit offsets within the
temporal index.
┌────────┬────────┬───────────────────────────────────────────┐
│Offset │ Length │ Name │
├────────┼────────┼───────────────────────────────────────────┤
│ 0 │ 4 │ timestamp, seconds part (past UNIX epoch) │
│ 4 │ 4 │ timestamp, microseconds part │
│ 8 │ 4 │ number of PMIDs with data following │
│ 12 │ M │ pmValueSet #0 │
│ 12+M │ N │ pmValueSet #1 │
│12+M+N │ ... │ ... │
│ NOP │ X │ pmValueBlock #0 │
│ NOP+X │ Y │ pmValueBlock #1 │
│NOP+X+Y │ ... │ ... │
└────────┴────────┴───────────────────────────────────────────┘
Records with a number-of-PMIDs equal to zero are "mark records",
and represent interruptions, missing data, or time
discontinuities in logging.
pmValueSet
This subrecord represents the measurements for one metric.
┌───────┬────────┬────────────────────────────────────────────────┐
│Offset │ Length │ Name │
├───────┼────────┼────────────────────────────────────────────────┤
│ 0 │ 4 │ PMID │
│ 4 │ 4 │ number of values │
│ 8 │ 4 │ storage mode, PM_VAL_INSITU=0 or PM_VAL_DPTR=1 │
│ 12 │ M │ pmValue #0 │
│ 12+M │ N │ pmValue #1 │
│12+M+N │ ... │ ... │
└───────┴────────┴────────────────────────────────────────────────┘
The metric-description metadata for PMIDs is found in the .meta
files. These entries are not timestamped, so the metadata is
assumed to be unchanging throughout the archiving session.
pmValue
This subrecord represents one measurement for one instance of the
metric. It is a variant type, depending on the parent
pmValueSet's value-format field. This allows small numbers to be
encoded compactly, but retain flexibility for larger or variable-
length data to be stored later in the pmResult record.
┌───────┬────────┬───────────────────────────────────────────────┐
│Offset │ Length │ Name │
├───────┼────────┼───────────────────────────────────────────────┤
│ 0 │ 4 │ number in instance-domain (or PM_IN_NULL=-1) │
│ 4 │ 4 │ value (INSITU) or │
│ │ │ offset in pmResult to our pmValueBlock (DPTR) │
└───────┴────────┴───────────────────────────────────────────────┘
The instance-domain metadata for PMIDs is found in the .meta
files. Since the numeric mappings may change during the lifetime
of the logging session, it is important to match up the timestamp
of the measurement record with the corresponding instance-domain
record. That is, the instance-domain corresponding to a
measurement at time T are the records with largest timestamps T'
<= T.
pmValueBlock
Instances of this subrecord are placed at the end of the
pmValueSet, after all the pmValue subrecords. If (and only if)
needed, they are padded at the end to the next-higher 32-bit
boundary.
┌───────┬────────┬────────────────────────────────────────────────┐
│Offset │ Length │ Name │
├───────┼────────┼────────────────────────────────────────────────┤
│ 0 │ 1 │ value type (same as pmDesc.type) │
│ 1 │ 3 │ 4 + N, the length of the subrecord │
│ 4 │ N │ bytes that make up the raw value │
│ 4+N │ 0-3 │ padding (not included in the 4+N length field) │
└───────┴────────┴────────────────────────────────────────────────┘
Note that for PM_TYPE_STRING, the length includes an explicit
NULL terminator byte. For PM_TYPE_EVENT, the value bytestring is
further structured.
