--- title: backendstat description: backendstat — gather PingDS backend debugging information component: pingds version: 8.1 page_id: pingds:tools-reference:backendstat canonical_url: https://docs.pingidentity.com/pingds/8.1/tools-reference/backendstat.html section_ids: synopsis: Synopsis backendstat-description: Description backendstat-options: Options backendstat-subcommands: Subcommands backendstat_dump_index: backendstat dump-index options: Options backendstat_dump_raw_db: backendstat dump-raw-db options_2: Options backendstat_list_base_dns: backendstat list-base-dns backendstat_list_indexes: backendstat list-indexes options_3: Options backendstat_list_raw_dbs: backendstat list-raw-dbs options_4: Options backendstat_show_index_status: backendstat show-index-status options_5: Options exit_codes: Exit codes --- # backendstat `backendstat` — gather PingDS backend debugging information ## Synopsis `backendstat {subcommand} {options}` ## Description This utility can be used to debug a backend. ## Options The `backendstat` command takes the following options: * `-V | --version` Display Directory Server version information. Default: false * `-H | --help` Display this usage information. Default: false ## Subcommands The `backendstat` command supports the following subcommands: ### backendstat dump-index `backendstat dump-index {options} {indexName}` Dump records from an index, decoding keys and values. Depending on index size, this subcommand can generate lots of output. When you run the `show-index-status` subcommand, the result is a table, followed by a "Total", which is the total number of indexes, followed by a list of indexes with "Over index-entry-limit keys" to show the values for which the number of entries exceeded the index entry limit. The table has the following columns: * (No label) If the index needs rebuilding, its row starts with `!` . Otherwise, its row starts with a space. * Index Name Name of the index, where the format depends on the index. For example, `givenName.caseIgnoreSubstringsMatch:6` : * Attribute indexes: *attr.type* . *type* * Big indexes: *attr.type* .big. *type* * VLV indexes: vlv. *type* * Secure `+` means confidentiality is enabled for the index. `-` means confidentiality is disabled. * Size The size on disk. * Key Count Number of indexed keys. Use the `backendstat dump-tree` command to see how many entry IDs correspond to each key. * Over Number of keys for which there are too many values to maintain an index, based on the `index-entry-limit` . This is recorded as `-` for VLV indexes. In other words, with the default index entry limit of 4000, if every user in your large directory has an email address ending in `@example.com` , and a substring index with default substring length of 6 is maintained for `mail` , then the directory server does not maintain indexes for keys corresponding to substrings in `@example.com` . As a result, an LDAP search with the filter `"(mail=*@example.com)"` becomes an unindexed search even though a substring index exists for the mail attribute. By default, the directory server does not allow unindexed searches except by privileged users. This is usually exactly the behavior you want in order to prevent client applications from sending searches that return every user in the directory for example. Clients should refine their search filters instead. * Entry Limit The `index-entry-limit` setting that applies to this index. Default: `4000` * Mean Average number of values per key for this index. * Median Median number of values per key for this index. * 80th, 95th, 99th Percentage of keys having at most the specified number of values. This is a measure of how full the entry ID lists are. #### Options In addition to the global `backendstat` options, the `backendstat dump-index` subcommand takes the following options: * `-b | --baseDn {baseDN}` The base DN. * `-k | --minKeyValue {minKeyValue}` Only show records with keys that should be ordered after the provided value using the comparator for the database container. * `-K | --maxKeyValue {maxKeyValue}` Only show records with keys that should be ordered before the provided value using the comparator for the database container. * `-p | --skipDecode` Do not try to decode backend data to their appropriate types. Default: false * `-q | --statsOnly` Do not display backend data, just statistics. Default: false * `-s | --minDataSize {minDataSize}` Only show records whose data is no smaller than the provided value. Default: -1 * `-S | --maxDataSize {maxDataSize}` Only show records whose data is no larger than the provided value. Default: -1 * `-x | --minHexKeyValue {minKeyValue}` Only show records with keys that should be ordered after the provided value using the comparator for the database container. * `-X | --maxHexKeyValue {maxKeyValue}` Only show records with keys that should be ordered before the provided value using the comparator for the database container. ### backendstat dump-raw-db `backendstat dump-raw-db {options} {databaseName}` Dump the raw records in hexadecimal format for a low-level database within the pluggable backend's storage engine. Depending on index size, this subcommand can generate lots of output. When you run the `show-index-status` subcommand, the result is a table, followed by a "Total", which is the total number of indexes, followed by a list of indexes with "Over index-entry-limit keys" to show the values for which the number of entries exceeded the index entry limit. The table has the following columns: * (No label) If the index needs rebuilding, its row starts with `!` . Otherwise, its row starts with a space. * Index Name Name of the index, where the format depends on the index. For example, `givenName.caseIgnoreSubstringsMatch:6` : * Attribute indexes: *attr.type* . *type* * Big indexes: *attr.type* .big. *type* * VLV indexes: vlv. *type* * Secure `+` means confidentiality is enabled for the index. `-` means confidentiality is disabled. * Size The size on disk. * Key Count Number of indexed keys. Use the `backendstat dump-tree` command to see how many entry IDs correspond to each key. * Over Number of keys for which there are too many values to maintain an index, based on the `index-entry-limit` . This is recorded as `-` for VLV indexes. In other words, with the default index entry limit of 4000, if every user in your large directory has an email address ending in `@example.com` , and a substring index with default substring length of 6 is maintained for `mail` , then the directory server does not maintain indexes for keys corresponding to substrings in `@example.com` . As a result, an LDAP search with the filter `"(mail=*@example.com)"` becomes an unindexed search even though a substring index exists for the mail attribute. By default, the directory server does not allow unindexed searches except by privileged users. This is usually exactly the behavior you want in order to prevent client applications from sending searches that return every user in the directory for example. Clients should refine their search filters instead. * Entry Limit The `index-entry-limit` setting that applies to this index. Default: `4000` * Mean Average number of values per key for this index. * Median Median number of values per key for this index. * 80th, 95th, 99th Percentage of keys having at most the specified number of values. This is a measure of how full the entry ID lists are. #### Options In addition to the global `backendstat` options, the `backendstat dump-raw-db` subcommand takes the following options: * `-b | --baseDn {baseDN}` The base DN. * `-k | --minKeyValue {minKeyValue}` Only show records with keys that should be ordered after the provided value using the comparator for the database container. * `-K | --maxKeyValue {maxKeyValue}` Only show records with keys that should be ordered before the provided value using the comparator for the database container. * `-l | --singleLine` Write hexadecimal data on a single line instead of pretty format. Default: false * `-n | --backendId {backendName}` The backend ID of the backend. * `-q | --statsOnly` Do not display backend data, just statistics. Default: false * `-s | --minDataSize {minDataSize}` Only show records whose data is no smaller than the provided value. Default: -1 * `-S | --maxDataSize {maxDataSize}` Only show records whose data is no larger than the provided value. Default: -1 * `-x | --minHexKeyValue {minKeyValue}` Only show records with keys that should be ordered after the provided value using the comparator for the database container. * `-X | --maxHexKeyValue {maxKeyValue}` Only show records with keys that should be ordered before the provided value using the comparator for the database container. ### backendstat list-base-dns `backendstat list-base-dns` List the base DNs in a backend. ### backendstat list-indexes `backendstat list-indexes {options}` List the indexes associated with a pluggable backend. This subcommand may take a long time to complete depending on the size of the backend. #### Options In addition to the global `backendstat` options, the `backendstat list-indexes` subcommand takes the following options: * `-b | --baseDn {baseDN}` The base DN. ### backendstat list-raw-dbs `backendstat list-raw-dbs {options}` List the low-level databases within a pluggable backend's storage engine. This subcommand may take a long time to complete depending on the size of the backend. #### Options In addition to the global `backendstat` options, the `backendstat list-raw-dbs` subcommand takes the following options: * `-n | --backendId {backendName}` The backend ID of the backend. * `-u | --useSiUnits` Uses SI Units for printing sizes. Default: false ### backendstat show-index-status `backendstat show-index-status {options}` Shows the status of indexes for a backend base DN. This subcommand can take a long time to complete, as it reads all indexes of the backend. When you run the `show-index-status` subcommand, the result is a table, followed by a "Total", which is the total number of indexes, followed by a list of indexes with "Over index-entry-limit keys" to show the values for which the number of entries exceeded the index entry limit. The table has the following columns: * (No label) If the index needs rebuilding, its row starts with `!` . Otherwise, its row starts with a space. * Index Name Name of the index, where the format depends on the index. For example, `givenName.caseIgnoreSubstringsMatch:6` : * Attribute indexes: *attr.type* . *type* * Big indexes: *attr.type* .big. *type* * VLV indexes: vlv. *type* * Secure `+` means confidentiality is enabled for the index. `-` means confidentiality is disabled. * Size The size on disk. * Key Count Number of indexed keys. Use the `backendstat dump-tree` command to see how many entry IDs correspond to each key. * Over Number of keys for which there are too many values to maintain an index, based on the `index-entry-limit` . This is recorded as `-` for VLV indexes. In other words, with the default index entry limit of 4000, if every user in your large directory has an email address ending in `@example.com` , and a substring index with default substring length of 6 is maintained for `mail` , then the directory server does not maintain indexes for keys corresponding to substrings in `@example.com` . As a result, an LDAP search with the filter `"(mail=*@example.com)"` becomes an unindexed search even though a substring index exists for the mail attribute. By default, the directory server does not allow unindexed searches except by privileged users. This is usually exactly the behavior you want in order to prevent client applications from sending searches that return every user in the directory for example. Clients should refine their search filters instead. * Entry Limit The `index-entry-limit` setting that applies to this index. Default: `4000` * Mean Average number of values per key for this index. * Median Median number of values per key for this index. * 80th, 95th, 99th Percentage of keys having at most the specified number of values. This is a measure of how full the entry ID lists are. #### Options In addition to the global `backendstat` options, the `backendstat show-index-status` subcommand takes the following options: * `-b | --baseDn {baseDN}` The base DN. ## Exit codes * 0 The command completed successfully. * \> 0 An error occurred.