github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/storage/enginepb/mvcc.proto

// Copyright 2014 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

// Cannot be proto3 because we depend on absent-vs-empty distinction.
syntax = "proto2";
package cockroach.storage.enginepb;
option go_package = "enginepb";

import "storage/enginepb/mvcc3.proto";
import "util/hlc/legacy_timestamp.proto";
import "gogoproto/gogo.proto";

// MVCCMetadata holds MVCC metadata for a key. Used by storage/mvcc.go.
// An MVCCMetadata is stored for a versioned key while there is an intent on
// that key.
message MVCCMetadata {
  option (gogoproto.goproto_stringer) = false;
  option (gogoproto.equal) = true;
  option (gogoproto.populate) = true;

  // The transaction metadata. Present for intents, but not for inline
  // values (e.g. timeseries data). Also not present for
  // "reconstructed" metadata that is used during MVCC processing when
  // no intent exists on disk.
  optional TxnMeta txn = 1;
  // The timestamp of the most recent versioned value if this is a
  // value that may have multiple versions. For values which may have
  // only one version, the data is stored inline (via raw_bytes), and
  // timestamp is set to zero.
  optional util.hlc.LegacyTimestamp timestamp = 2 [(gogoproto.nullable) = false];
  // Is the most recent value a deletion tombstone?
  optional bool deleted = 3 [(gogoproto.nullable) = false];
  // The size in bytes of the most recent encoded key.
  optional int64 key_bytes = 4 [(gogoproto.nullable) = false];
  // The size in bytes of the most recent versioned value.
  optional int64 val_bytes = 5 [(gogoproto.nullable) = false];
  // Inline value, used for non-versioned values with zero
  // timestamp. This provides an efficient short circuit of the normal
  // MVCC metadata sentinel and subsequent version rows. If timestamp
  // == (0, 0), then there is only a single MVCC metadata row with
  // value inlined, and with empty timestamp, key_bytes, and
  // val_bytes.
  optional bytes raw_bytes = 6;
  // SequencedIntent stores a value at a given key and the sequence number it was
  // written at - to be stored in an IntentHistory of a key during a transaction.
  message SequencedIntent {
    option (gogoproto.goproto_stringer) = false;
    option (gogoproto.equal) = true;
    option (gogoproto.populate) = true;
    // Sequence is a one-indexed number which is increased on each request
    // set as part of a transaction. It uniquely identifies a value from
    // the IntentHistory.
    optional int32 sequence = 1 [(gogoproto.nullable) = false, (gogoproto.casttype) = "TxnSeq"];
    // Value is the value written to the key as part of the transaction at
    // the above Sequence.
    optional bytes value = 2;
  }

  // IntentHistory of the transaction stores the older values the txn wrote
  // for the key along with each values corresponding Sequence. It doesn't
  // contain the latest intent value but rather stores all the values that have
  // been overwritten by the transaction.
  // IntentHistory will be empty for non-transactional requests.
  repeated SequencedIntent intent_history = 8 [(gogoproto.nullable) = false];
  // This provides a measure of protection against replays caused by
  // Raft duplicating merge commands.
  optional util.hlc.LegacyTimestamp merge_timestamp = 7;
}

// A mirror of MVCCMetadata intended for serializing non-MVCC data that is
// merged within the RocksDB or Pebble engines. Such data only populates
// raw_bytes and optionally merge_timestamp. The C++ serialization of
// MVCCMetadata does not serialize any of the missing optional fields, but
// the Go serialization treats the optional fields annotated with
// [(gogoproto.nullable) = false] in a manner that cannot distinguish
// between the default and missing value, and causes them to serialized
// (e.g. fields with tag 2, 3, 4, 5). By using the following proto in the
// Go merge code, the Go and C++ serialization match.
message MVCCMetadataSubsetForMergeSerialization {
  option (gogoproto.goproto_stringer) = false;
  option (gogoproto.equal) = true;
  option (gogoproto.populate) = true;

  optional bytes raw_bytes = 6;
  optional util.hlc.LegacyTimestamp merge_timestamp = 7;
}

// MVCCStats tracks byte and instance counts for various groups of keys,
// values, or key-value pairs; see the field comments for details.
//
// It also tracks two cumulative ages, namely that of intents and non-live
// (i.e. GC-able) bytes. This computation is intrinsically linked to
// last_update_nanos and is easy to get wrong. Updates happen only once every
// full second, as measured by last_update_nanos/1e9. That is, forward updates
// don't change last_update_nanos until an update at a timestamp which,
// truncated to the second, is ahead of last_update_nanos/1e9. Then, that
// difference in seconds times the base quantity (excluding the currently
// running update) is added to the age.
//
// To give an example, if an intent is around from `t=2.5s` to `t=4.1s` (the
// current time), then it contributes an intent age of two seconds (one second
// picked up when crossing `t=3s`, another one at `t=4s`). Similarly, if a
// GC'able kv pair is around for this amount of time, it contributes two seconds
// times its size in bytes.
//
// It gets more complicated when data is
// accounted for with a timestamp behind last_update_nanos. In this case, if
// more than a second has passed (computed via truncation above), the ages have
// to be adjusted to account for this late addition. This isn't hard: add the
// new data's base quantity times the (truncated) number of seconds behind.
// Important to keep in mind with those computations is that (x/1e9 - y/1e9)
// does not equal (x-y)/1e9 in most cases.
//
// Note that this struct must be kept at a fixed size by using fixed-size
// encodings for all fields and by making all fields non-nullable. This is
// so that it can predict its own impact on the size of the system-local
// kv-pairs.
message MVCCStats {
  option (gogoproto.equal) = true;
  option (gogoproto.populate) = true;

  // contains_estimates indicates that the MVCCStats object contains values
  // which have been estimated. This means that the stats should not be used
  // where complete accuracy is required, and instead should be recomputed
  // when necessary. See clusterversion.VersionContainsEstimatesCounter for
  // details about the migration from bool to int64.
  optional int64 contains_estimates = 14 [(gogoproto.nullable) = false];

  // last_update_nanos is a timestamp at which the ages were last
  // updated. See the comment on MVCCStats.
  optional sfixed64 last_update_nanos = 1 [(gogoproto.nullable) = false];
  // intent_age is the cumulative age of the tracked intents.
  // See the comment on MVCCStats.
  optional sfixed64 intent_age = 2 [(gogoproto.nullable) = false];
  // gc_bytes_age is the cumulative age of the non-live data (i.e.
  // data included in key_bytes and val_bytes, but not live_bytes).
  // See the comment on MVCCStats.
  optional sfixed64 gc_bytes_age = 3 [(gogoproto.nullable) = false, (gogoproto.customname) = "GCBytesAge"];
  // live_bytes is the number of bytes stored in keys and values which can in
  // principle be read by means of a Scan or Get in the far future, including
  // intents but not deletion tombstones (or their intents). Note that the
  // size of the meta kv pair (which could be explicit or implicit) is
  // included in this. Only the meta kv pair counts for the actual length of
  // the encoded key (regular pairs only count the timestamp suffix).
  optional sfixed64 live_bytes = 4 [(gogoproto.nullable) = false];
  // live_count is the number of meta keys tracked under live_bytes.
  optional sfixed64 live_count = 5 [(gogoproto.nullable) = false];
  // key_bytes is the number of bytes stored in all non-system
  // keys, including live, meta, old, and deleted keys.
  // Only meta keys really account for the "full" key; value
  // keys only for the timestamp suffix.
  optional sfixed64 key_bytes = 6 [(gogoproto.nullable) = false];
  // key_count is the number of meta keys tracked under key_bytes.
  optional sfixed64 key_count = 7 [(gogoproto.nullable) = false];
  // value_bytes is the number of bytes in all non-system version
  // values, including meta values.
  optional sfixed64 val_bytes = 8 [(gogoproto.nullable) = false];
  // val_count is the number of meta values tracked under val_bytes.
  optional sfixed64 val_count = 9 [(gogoproto.nullable) = false];
  // intent_bytes is the number of bytes in intent key-value
  // pairs (without their meta keys).
  optional sfixed64 intent_bytes = 10 [(gogoproto.nullable) = false];
  // intent_count is the number of keys tracked under intent_bytes.
  // It is equal to the number of meta keys in the system with
  // a non-empty Transaction proto.
  optional sfixed64 intent_count = 11 [(gogoproto.nullable) = false];

  // sys_bytes is the number of bytes stored in system-local kv-pairs.
  // This tracks the same quantity as (key_bytes + val_bytes), but
  // for system-local metadata keys (which aren't counted in either
  // key_bytes or val_bytes). Each of the keys falling into this group
  // is documented in keys/constants.go under the localPrefix constant
  // and is prefixed by either LocalRangeIDPrefix or LocalRangePrefix.
  optional sfixed64 sys_bytes = 12 [(gogoproto.nullable) = false];
  // sys_count is the number of meta keys tracked under sys_bytes.
  optional sfixed64 sys_count = 13 [(gogoproto.nullable) = false];
}