From 53d23d95d86e8b6e61408481a6cc847c0287386c Mon Sep 17 00:00:00 2001 From: Jon Fu Date: Mon, 4 Jan 2021 15:26:48 -0500 Subject: [PATCH] initial commit in adding more documentation to special keys --- fdbclient/SystemData.cpp | 4 ---- fdbclient/SystemData.h | 43 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 42 insertions(+), 5 deletions(-) diff --git a/fdbclient/SystemData.cpp b/fdbclient/SystemData.cpp index b402ad99a7..26b8ca50b5 100644 --- a/fdbclient/SystemData.cpp +++ b/fdbclient/SystemData.cpp @@ -203,10 +203,6 @@ const KeyRangeRef writeConflictRangeKeysRange = LiteralStringRef("\xff\xff/transaction/write_conflict_range/\xff\xff")); // "\xff/cacheServer/[[UID]] := StorageServerInterface" -// This will be added by the cache server on initialization and removed by DD -// TODO[mpilman]: We will need a way to map uint16_t ids to UIDs in a future -// versions. For now caches simply cache everything so the ids -// are not yet meaningful. const KeyRangeRef storageCacheServerKeys(LiteralStringRef("\xff/cacheServer/"), LiteralStringRef("\xff/cacheServer0")); const KeyRef storageCacheServersPrefix = storageCacheServerKeys.begin; diff --git a/fdbclient/SystemData.h b/fdbclient/SystemData.h index 20091a8045..3104aa53bb 100644 --- a/fdbclient/SystemData.h +++ b/fdbclient/SystemData.h @@ -45,6 +45,9 @@ extern const KeyRangeRef specialKeys; // [FF][FF] to [FF][FF][FF], some client f extern const KeyRef afterAllKeys; // "\xff/keyServers/[[begin]]" := "[[vector, vector]|[vector, vector]]" +// An internal mapping of where shards are located in the database. [[begin]] is the start of the shard range +// and the result is a list of serverIDs or Tags where these shards are located. These values can be changed +// as data movement occurs. extern const KeyRangeRef keyServersKeys, keyServersKeyServersKeys; extern const KeyRef keyServersPrefix, keyServersEnd, keyServersKeyServersKey; const Key keyServersKey( const KeyRef& k ); @@ -63,6 +66,10 @@ void decodeKeyServersValue( std::map const& tag_uid, const ValueRef& v std::vector& src, std::vector& dest ); // "\xff/storageCacheServer/[[UID]] := StorageServerInterface" +// This will be added by the cache server on initialization and removed by DD +// TODO[mpilman]: We will need a way to map uint16_t ids to UIDs in a future +// versions. For now caches simply cache everything so the ids +// are not yet meaningful. extern const KeyRangeRef storageCacheServerKeys; extern const KeyRef storageCacheServersPrefix, storageCacheServersEnd; const Key storageCacheServerKey(UID id); @@ -76,6 +83,10 @@ const Value storageCacheValue( const std::vector& serverIndices ); void decodeStorageCacheValue( const ValueRef& value, std::vector& serverIndices ); // "\xff/serverKeys/[[serverID]]/[[begin]]" := "" | "1" | "2" +// An internal mapping of what shards any given server currently has ownership of +// Using the serverID as a prefix, then followed by the beginning of the shard range +// as the key, the value indicates whether the shard does or does not exist on the server. +// These values can be changed as data movement occurs. extern const KeyRef serverKeysPrefix; extern const ValueRef serverKeysTrue, serverKeysFalse; const Key serverKeysKey( UID serverID, const KeyRef& keys ); @@ -103,6 +114,8 @@ const Key cacheChangeKeyFor( uint16_t idx ); uint16_t cacheChangeKeyDecodeIndex( const KeyRef& key ); // "\xff/serverTag/[[serverID]]" = "[[Tag]]" +// Provides the Tag for the given serverID. Used to access a +// storage server's corresponding TLog in order to apply mutations. extern const KeyRangeRef serverTagKeys; extern const KeyRef serverTagPrefix; extern const KeyRangeRef serverTagMaxKeys; @@ -122,6 +135,8 @@ Tag decodeServerTagValue( ValueRef const& ); const Key serverTagConflictKeyFor( Tag ); // "\xff/tagLocalityList/[[datacenterID]]" := "[[tagLocality]]" +// Provides the tagLocality for the given datacenterID +// See "FDBTypes.h" struct Tag for more details on tagLocality extern const KeyRangeRef tagLocalityListKeys; extern const KeyRef tagLocalityListPrefix; const Key tagLocalityListKeyFor( Optional dcID ); @@ -130,6 +145,8 @@ Optional decodeTagLocalityListKey( KeyRef const& ); int8_t decodeTagLocalityListValue( ValueRef const& ); // "\xff\x02/datacenterReplicas/[[datacenterID]]" := "[[replicas]]" +// Provides the number of replicas for the given datacenterID. +// Used in the initialization of the Data Distributor. extern const KeyRangeRef datacenterReplicasKeys; extern const KeyRef datacenterReplicasPrefix; const Key datacenterReplicasKeyFor( Optional dcID ); @@ -138,6 +155,8 @@ Optional decodeDatacenterReplicasKey( KeyRef const& ); int decodeDatacenterReplicasValue( ValueRef const& ); // "\xff\x02/tLogDatacenters/[[datacenterID]]" +// The existence of an empty string as a value signifies that the datacenterID is valid +// (as opposed to having no value at all) extern const KeyRangeRef tLogDatacentersKeys; extern const KeyRef tLogDatacentersPrefix; const Key tLogDatacentersKeyFor( Optional dcID ); @@ -170,20 +189,34 @@ ProcessClass decodeProcessClassValue( ValueRef const& ); UID decodeProcessClassKeyOld( KeyRef const& key ); // "\xff/conf/[[option]]" := "value" +// An umbrella prefix for options mostly used by the DatabaseConfiguration class. +// See DatabaseConfiguration.cpp ::setInternal for more examples. extern const KeyRangeRef configKeys; extern const KeyRef configKeysPrefix; +// The differences between excluded and failed can be found in "command-line-interface.rst" +// and in the help message of the fdbcli command "exclude". + // "\xff/conf/excluded/1.2.3.4" := "" // "\xff/conf/excluded/1.2.3.4:4000" := "" // These are inside configKeysPrefix since they represent a form of configuration and they are convenient // to track in the same way by the tlog and recovery process, but they are ignored by the DatabaseConfiguration // class. +// The existence of an empty string as a value signifies that the provided IP has been excluded. +// (as opposed to having no value at all) extern const KeyRef excludedServersPrefix; extern const KeyRangeRef excludedServersKeys; extern const KeyRef excludedServersVersionKey; // The value of this key shall be changed by any transaction that modifies the excluded servers list const AddressExclusion decodeExcludedServersKey( KeyRef const& key ); // where key.startsWith(excludedServersPrefix) std::string encodeExcludedServersKey( AddressExclusion const& ); +// "\xff/conf/failed/1.2.3.4" := "" +// "\xff/conf/failed/1.2.3.4:4000" := "" +// These are inside configKeysPrefix since they represent a form of configuration and they are convenient +// to track in the same way by the tlog and recovery process, but they are ignored by the DatabaseConfiguration +// class. +// The existence of an empty string as a value signifies that the provided IP has been marked as failed. +// (as opposed to having no value at all) extern const KeyRef failedServersPrefix; extern const KeyRangeRef failedServersKeys; extern const KeyRef failedServersVersionKey; // The value of this key shall be changed by any transaction that modifies the failed servers list @@ -201,6 +234,8 @@ Key decodeWorkerListKey( KeyRef const& ); ProcessData decodeWorkerListValue( ValueRef const& ); // "\xff\x02/backupProgress/[[workerID]]" := "[[WorkerBackupStatus]]" +// Provides the progress for the given backup worker. +// See "FDBTypes.h" struct WorkerBackupStatus for more details on the return type value. extern const KeyRangeRef backupProgressKeys; extern const KeyRef backupProgressPrefix; const Key backupProgressKeyFor(UID workerID); @@ -214,10 +249,16 @@ extern const KeyRef backupStartedKey; Value encodeBackupStartedValue(const std::vector>& ids); std::vector> decodeBackupStartedValue(const ValueRef& value); -// The key to signal backup workers that they should pause or resume. +// The key to signal backup workers that they should resume or pause. // "\xff\x02/backupPaused" := "[[0|1]]" +// 0 = Send a signal to resume/already resumed. +// 1 = Send a signal to pause/already paused. extern const KeyRef backupPausedKey; +// "\xff/coordinators = [[ClusterConnectionString]]" +// Set to the encoded structure of the cluster's current set of coordinators. +// Changed when performing quorumChange. +// See "CoordinationInterface.h" struct ClusterConnectionString for more details extern const KeyRef coordinatorsKey; extern const KeyRef logsKey; extern const KeyRef minRequiredCommitVersionKey;