llog.txt

   1 The Lustre Log Facility
   2 ~~~~~~~~~~~~~~~~~~~~~~~
   3 [[llog]]
   4
   5 The Lustre log (llog) file may contain a number of different types of
   6 data structures, including redo records for uncommitted distributed
   7 transactions such as unlink or ownership changes, configuration records
   8 for targets and clients, or ChangeLog records to track changes to the
   9 filesystem for external consumption, among others.
  10
  11 Each llog file begins with an 'llog_log_hdr' that describes the llog
  12 file itself, followed by a series of log records that are appended
  13 sequentially to the file.  Each record, including the header itself,
  14 begins with an 'llog_rec_hdr' and ends with an 'llog_rec_tail'.
  15
  16 LLOG Log ID
  17 ^^^^^^^^^^^
  18 [[struct-llog-logid]]
  19
  20 ----
  21 struct llog_logid {
  22         struct ost_id           lgl_oi;
  23         __u32                   lgl_ogen;
  24 };
  25 ----
  26
  27 The 'llog_logid' structure is used to identify a single Lustre log file.
  28 It holds a <<struct-ost-id>> in 'lgl_oi', which is typically a FID.
  29
  30 LLog Information
  31 ^^^^^^^^^^^^^^^^
  32 [[struct-llogd-body]]
  33 ----
  34 struct llogd_body {
  35         struct llog_logid  lgd_logid;
  36         __u32 lgd_ctxt_idx;
  37         __u32 lgd_llh_flags;
  38         __u32 lgd_index;
  39         __u32 lgd_saved_index;
  40         __u32 lgd_len;
  41         __u64 lgd_cur_offset;
  42 };
  43 ----
  44
  45 The lgd_llh_flags are:
  46 ----
  47 enum llog_flag {
  48         LLOG_F_ZAP_WHEN_EMPTY   = 0x1,
  49         LLOG_F_IS_CAT           = 0x2,
  50         LLOG_F_IS_PLAIN         = 0x4,
  51 };
  52 ----
  53
  54 LLog Record Header
  55 ^^^^^^^^^^^^^^^^^^
  56 [[struct-llog-rec-hdr]]
  57 ----
  58 struct llog_rec_hdr {
  59         __u32   lrh_len;
  60         __u32   lrh_index;
  61         __u32   lrh_type;
  62         __u32   lrh_id;
  63 };
  64 ----
  65
  66 The 'llog_rec_hdr' is at the start of each llog record and describes
  67 the log record.  'lrh_len' holds the record size in bytes, including
  68 the header and tail.  'lrh_index' is the record index within the llog
  69 file and is sequentially increasing for each subsequent record.  It
  70 can be used to determine the offset within the llog file when searching
  71 for an arbitrary record within the file. 'lrh_type' describes the type
  72 of data stored in this record.
  73
  74 ----
  75 enum llog_op_type {
  76         LLOG_PAD_MAGIC          = LLOG_OP_MAGIC | 0x00000,
  77         OST_SZ_REC              = LLOG_OP_MAGIC | 0x00f00,
  78         MDS_UNLINK64_REC        = LLOG_OP_MAGIC | 0x90000 | (MDS_REINT << 8) |
  79                                   REINT_UNLINK,
  80         MDS_SETATTR64_REC       = LLOG_OP_MAGIC | 0x90000 | (MDS_REINT << 8) |
  81                                   REINT_SETATTR,
  82         OBD_CFG_REC             = LLOG_OP_MAGIC | 0x20000,
  83         LLOG_GEN_REC            = LLOG_OP_MAGIC | 0x40000,
  84         CHANGELOG_REC           = LLOG_OP_MAGIC | 0x60000,
  85         CHANGELOG_USER_REC      = LLOG_OP_MAGIC | 0x70000,
  86         HSM_AGENT_REC           = LLOG_OP_MAGIC | 0x80000,
  87         UPDATE_REC              = LLOG_OP_MAGIC | 0xa0000,
  88         LLOG_HDR_MAGIC          = LLOG_OP_MAGIC | 0x45539,
  89         LLOG_LOGID_MAGIC        = LLOG_OP_MAGIC | 0x4553b,
  90 };
  91 ----
  92
  93 LLog Record Tail
  94 ^^^^^^^^^^^^^^^^
  95 [[struct-llog-rec-tail]]
  96 ----
  97 struct llog_rec_tail {
  98         __u32   lrt_len;
  99         __u32   lrt_index;
 100 };
 101 ----
 102
 103 The 'llog_rec_tail' is at the end of each llog record.  The 'lrt_len'
 104 and 'lrt_index' fields must be the same as 'lrh_len' and 'lrh_index'
 105 in the header.  They can be used to verify record integrity, as well
 106 as allowing processing the llog records in reverse order.
 107
 108 LLog Log Header Information
 109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 110 [[struct-llog-log-hdr]]
 111 ----
 112 struct llog_log_hdr {
 113         struct llog_rec_hdr     llh_hdr;
 114         obd_time                llh_timestamp;
 115         __u32                   llh_count;
 116         __u32                   llh_bitmap_offset;
 117         __u32                   llh_size;
 118         __u32                   llh_flags;
 119         __u32                   llh_cat_idx;
 120         /* for a catalog the first plain slot is next to it */
 121         struct obd_uuid         llh_tgtuuid;
 122         __u32                   llh_reserved[LLOG_HEADER_SIZE/sizeof(__u32) - 23];
 123         __u32                   llh_bitmap[LLOG_BITMAP_BYTES/sizeof(__u32)];
 124         struct llog_rec_tail    llh_tail;
 125 };
 126 ----
 127
 128 The llog records start and end on a record size boundary, typically
 129 8192 bytes, or as stored in 'llh_size', which allows some degree of
 130 random access within the llog file, even with variable record sizes.
 131 It is possible to interpolate the offset of an arbitrary record
 132 within the file by estimating the byte offset of a particular record
 133 index using 'llh_count' and the llog file size and aligning it to
 134 the chunk boundary 'llh_size'.  The record index in the 'llog_rec_hdr'
 135 of the first record in that chunk can be used to further refine the
 136 estimate of the offset of the desired index down to a single chunk,
 137 and then sequential access can be used to find the actual record.
 138