LDB Tool

Ozone heavily uses RocksDB for storing metadata. This tool helps parse the contents of RocksDB belonging to Ozone Roles. Supported DB's : Ozone Manager (om.db) , StorageContainerManager (scm.db), Datanode/Container (container.db) Below is the usage:

Usage: ozone debug ldb --db=<dbPath> [COMMAND]
Parse rocksdb file content
      --db=<dbPath>   Database File Path
Commands:
  scan                      Parse specified metadataTable
  list_column_families, ls  list all column families in db.
  value-schema              Schema of value in metadataTable
  checkpoint                Create checkpoint for specified db

list_column_families command

list_column_families command lists all the column families in the db provided.

$ ozone debug ldb --db=/path/to/scm.db ls
default
sequenceId
revokedCertsV2
pipelines
crls
crlSequenceId
meta
containers
validCerts
validSCMCerts
scmTransactionInfos
deletedBlocks
statefulServiceConfig
revokedCerts
move

scan command

scan command parses a particular column family of a RocksDB provided and prints the records.

Usage: ozone debug ldb scan [--compact] [--count] [--with-keys]
                            [--batch-size=<batchSize>] --cf=<tableName>
                            [--cid=<containerId>] [-d=<dnDBSchemaVersion>]
                            [-e=<endKey>] [--fields=<fieldsFilter>]
                            [--filter=<filter>] [-l=<limit>] [-o=<fileName>]
                            [-s=<startKey>] [--thread-count=<threadCount>]
Parse specified metadataTable
      --batch-size=<batchSize>
                          Batch size for processing DB data.
      --cf, --column_family, --column-family=<tableName>
                          Table name
      --cid, --container-id=<containerId>
                          Container ID. Applicable if datanode DB Schema is V3
      --compact           disable the pretty print the output
      --count, --show-count
                          Get estimated key count for the given DB column family
                            Default: false
  -d, --dnSchema, --dn-schema=<dnDBSchemaVersion>
                          Datanode DB Schema Version: V1/V2/V3
  -e, --ek, --endkey=<endKey>
                          Key at which iteration of the DB ends
      --fields=<fieldsFilter>
                          Comma-separated list of fields needed for each value.
                            eg.) "name,acls.type" for showing name and type
                            under acls.
      --filter=<filter>   Comma-separated list of "<field>:<operator>:<value>"
                            where <field> is any valid field of the record,
                            <operator> is [EQUALS,LESSER, GREATER or REGEX].
                            (EQUALS compares the exact string, REGEX compares
                            with a valid regular expression passed, and
                            LESSER/GREATER works with numeric values), <value>
                            is the value of the field.
                          eg.) "dataSize:equals:1000" for showing records
                            having the value 1000 for dataSize,
                               "keyName:regex:^key.*$" for showing records
                            having keyName that matches the given regex.
  -l, --limit, --length=<limit>
                          Maximum number of items to list.
  -o, --out=<fileName>    File to dump table scan data
  -s, --sk, --startkey=<startKey>
                          Key from which to iterate the DB
      --thread-count=<threadCount>
                          Thread count for concurrent processing.
      --with-keys         Print a JSON object of key->value pairs (default)
                            instead of a JSON array of only values.

By default, the contents are printed on the console, but it can be redirected to a file using the --out option.

--length can be used to limit the number of records being printed.
--count doesn't print the records, it shows the approximate number of records. This is not accurate.
ozone debug ldb scan command provides many filtering options to make debugging easier, elaborated below:

tip

Multiple filtering options can be used together in a single command.

`--startkey` and `--endkey`

As the names suggest, these options specify the keys from/until which the iteration needs to happen.

--startkey specifies which key to start iterating from, it is inclusive.
--endkey specifies which key to stop iterating at, it is exclusive.

ozone debug ldb --db=/path/to/om.db scan --cf=volumeTable --startkey=vol3 --endkey=vol5

{
  "/vol3": {
    "metadata": {},
    "objectID": -9999,
    "updateID": 4000,
    "adminName": "om",
    "ownerName": "om",
    "volume": "vol3",
    "creationTime": 1707192335309,
    "modificationTime": 1714057412205,
    "quotaInBytes": 22854448694951936,
    "quotaInNamespace": 100000000,
    "usedNamespace": 1,
    "acls": [
      {
        "type": "USER",
        "name": "om",
        "aclScope": "ACCESS"
      }
    ],
    "refCount": 0
  },
  "/vol4": {
    "metadata": {},
    "objectID": -888,
    "updateID": 5000,
    "adminName": "om",
    "ownerName": "om",
    "volume": "vol4",
    "creationTime": 1696280979907,
    "modificationTime": 1696280979907,
    "quotaInBytes": 2251799813685250,
    "quotaInNamespace": 100000000,
    "usedNamespace": 2,
    "acls": [
      {
        "type": "USER",
        "name": "om",
        "aclScope": "ACCESS"
      }
    ],
    "refCount": 0
  }
}

`--fields`

There are multiple fields in each record. --fields option allows us to choose the specific fields to display.

ozone debug ldb --db=/path/to/om.db scan --cf=keyTable -l=1 --fields="volumeName,bucketName,keyName,keyLocationVersions.version,acls.name"

{
  "/vol1/ozone-legacy-bucket/10T-1-terasort-input/": {
    "keyLocationVersions": [
      {
        "version": 0
      }
    ],
    "keyName": "10T-1-terasort-input/",
    "bucketName": "ozone-legacy-bucket",
    "acls": [
      {
        "name": "om"
      },
      {
        "name": "scm"
      },
      {
        "name": "testuser"
      }
    ],
    "volumeName": "vol1"
  }
}

`--filter`

--filter can be used to select records whose value matches a given condition. The filter is given in this format: <field>:<operator>:<value>, where <field> is any valid field from the value of the record, <operator> is one of the 4 supported operations [equals, regex, lesser, greater], <value> is the value used for the comparison.

'Equals' and 'regex' work with string, bool and numerical fields, 'lesser' and 'greater' work only with numerical values.
Multiple filters can also be given in one command, they need to be separated by commas.

Using equals operator:

ozone debug ldb --db=/path/to/om.db scan --cf=volumeTable --filter="usedNamespace:equals:2"

{
  "/vol4": {
    "metadata": {},
    "objectID": -888,
    "updateID": 5000,
    "adminName": "om",
    "ownerName": "om",
    "volume": "vol4",
    "creationTime": 1696280979907,
    "modificationTime": 1696280979907,
    "quotaInBytes": 2251799813685250,
    "quotaInNamespace": 100000000,
    "usedNamespace": 2,
    "acls": [
      {
        "type": "USER",
        "name": "om",
        "aclScope": "ACCESS"
      }
    ],
    "refCount": 0
  },
  "/vol5": {
    "metadata": {},
    "objectID": -956599,
    "updateID": 45600,
    "adminName": "om",
    "ownerName": "om",
    "volume": "vol5",
    "creationTime": 1807192332309,
    "modificationTime": 1914057410005,
    "quotaInBytes": 7785494951936,
    "quotaInNamespace": 100000000,
    "usedNamespace": 2,
    "acls": [
      {
        "type": "USER",
        "name": "om",
        "aclScope": "ACCESS"
      }
    ],
    "refCount": 0
  }
}

Using lesser operator (greater operator can also be used in the same way):

ozone debug ldb --db=/path/to/om.db scan --cf=volumeTable --filter="usedNamespace:lesser:2"

{
  "/vol2": {
    "metadata": {},
    "objectID": -73548,
    "updateID": 2384,
    "adminName": "om",
    "ownerName": "om",
    "volume": "vol2",
    "creationTime": 11980979907,
    "modificationTime": 1296280979900,
    "quotaInBytes": 417913685250,
    "quotaInNamespace": 100000000,
    "usedNamespace": 1,
    "acls": [
      {
        "type": "USER",
        "name": "om",
        "aclScope": "ACCESS"
      }
    ],
    "refCount": 0
  }
}

Using regex operator:

ozone debug ldb --db=/path/to/om.db scan --cf=volumeTable --filter="volume:regex:^v.*2$"

{
  "/vol2": {
    "metadata": {},
    "objectID": -73548,
    "updateID": 2384,
    "adminName": "om",
    "ownerName": "om",
    "volume": "vol2",
    "creationTime": 11980979907,
    "modificationTime": 1296280979900,
    "quotaInBytes": 417913685250,
    "quotaInNamespace": 100000000,
    "usedNamespace": 1,
    "acls": [
      {
        "type": "USER",
        "name": "om",
        "aclScope": "ACCESS"
      }
    ],
    "refCount": 0
  }
}

Using multiple filters:

ozone debug ldb --db=/path/to/om.db scan --cf=volumeTable --filter="usedNamespace:equals:2,volume:regex:^.*4$"

{
  "/vol4": {
    "metadata": {},
    "objectID": -888,
    "updateID": 5000,
    "adminName": "om",
    "ownerName": "om",
    "volume": "vol4",
    "creationTime": 1696280979907,
    "modificationTime": 1696280979907,
    "quotaInBytes": 2251799813685250,
    "quotaInNamespace": 100000000,
    "usedNamespace": 2,
    "acls": [
      {
        "type": "USER",
        "name": "om",
        "aclScope": "ACCESS"
      }
    ],
    "refCount": 0
  }
}

value-schema command

value-schema command shows the schema of the value stored in a column-family of a RocksDB, i.e., it shows the fields stored in the value and it's datatype. --depth can be used optionally to limit the level until which the fields are fetched.

ozone debug ldb --db=/data/metadata/om.db value-schema --cf=keyTable --depth=1

{
  "OmKeyInfo": {
    "bucketName": "String",
    "metadata": "struct",
    "fileName": "String",
    "creationTime": "long",
    "isFile": "boolean",
    "acls": "struct",
    "keyName": "String",
    "replicationConfig": "struct",
    "encInfo": "struct",
    "dataSize": "long",
    "tags": "struct",
    "keyLocationVersions": "struct",
    "updateID": "long",
    "ownerName": "String",
    "modificationTime": "long",
    "parentObjectID": "long",
    "volumeName": "String",
    "fileChecksum": "struct",
    "objectID": "long"
  }
}

ozone debug ldb --db=/data/metadata/om.db value-schema --cf=keyTable

{
  "OmKeyInfo": {
    "bucketName": "String",
    "metadata": {},
    "fileName": "String",
    "creationTime": "long",
    "isFile": "boolean",
    "acls": {
      "toStringMethod": {},
      "hashCodeMethod": {},
      "name": "String",
      "type": {
        "name": "String",
        "value": "String",
        "ordinal": "int"
      },
      "aclScope": {
        "name": "String",
        "ordinal": "int"
      },
      "aclBits": "int"
    },
    "keyName": "String",
    "replicationConfig": {},
    "encInfo": {
      "ezKeyVersionName": "String",
      "keyName": "String",
      "edek": {},
      "cipherSuite": {
        "unknownValue": {
          "value": "int"
        },
        "name": "String",
        "algoBlockSize": "int",
        "ordinal": "int"
      },
      "version": {
        "unknownValue": {
          "value": "int"
        },
        "name": "String",
        "description": "String",
        "version": "int",
        "ordinal": "int"
      },
      "iv": {}
    },
    "dataSize": "long",
    "tags": {},
    "keyLocationVersions": {
      "isMultipartKey": "boolean",
      "locationVersionMap": {},
      "version": "long"
    },
    "updateID": "long",
    "ownerName": "String",
    "modificationTime": "long",
    "parentObjectID": "long",
    "volumeName": "String",
    "fileChecksum": {},
    "objectID": "long"
  }
}

checkpoint command

checkpoint command takes a checkpoint of a RocksDB, at a provided path.

ozone debug ldb --db=/data/metadata/om.db checkpoint --output=/tmp/om-checkpoint

Next >>