From 9f107e4c8f3f7a21bb4f27c8cc5b3a47becaf7b8 Mon Sep 17 00:00:00 2001 From: kay Date: Fri, 3 May 2013 17:32:36 -0400 Subject: [PATCH] DOCS-845 sharding status output --- bin/htaccess.yaml | 7 + .../param-verbose-printShardingStatus.rst | 4 + source/reference.txt | 3 +- .../method/db.printShardingStatus.txt | 10 +- source/reference/method/sh.status.txt | 13 +- source/reference/sharding-status.txt | 193 ++++++++++++++++++ 6 files changed, 223 insertions(+), 7 deletions(-) create mode 100644 source/includes/param-verbose-printShardingStatus.rst create mode 100644 source/reference/sharding-status.txt diff --git a/bin/htaccess.yaml b/bin/htaccess.yaml index 5704d65614a..13f050fea8d 100644 --- a/bin/htaccess.yaml +++ b/bin/htaccess.yaml @@ -1433,4 +1433,11 @@ code: 301 outputs: - 'after-v2.2' - 'manual' +--- +redirect-path: '/reference/sharding-status' +url-base: '/sharding' +type: 'redirect' +code: 301 +outputs: + - 'v2.2' ... diff --git a/source/includes/param-verbose-printShardingStatus.rst b/source/includes/param-verbose-printShardingStatus.rst new file mode 100644 index 00000000000..03d49f9f7e2 --- /dev/null +++ b/source/includes/param-verbose-printShardingStatus.rst @@ -0,0 +1,4 @@ +:param boolean verbose: + Optional. If ``true``, the method displays details of the + document distribution across chunks when you have 20 or more + chunks. diff --git a/source/reference.txt b/source/reference.txt index 99577839676..b649203d46f 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -43,7 +43,8 @@ Status and Reporting reference/database-profiler reference/explain reference/exit-codes - + reference/sharding-status + Internal Metadata ----------------- diff --git a/source/reference/method/db.printShardingStatus.txt b/source/reference/method/db.printShardingStatus.txt index ecbe678cdc8..369c5916c53 100644 --- a/source/reference/method/db.printShardingStatus.txt +++ b/source/reference/method/db.printShardingStatus.txt @@ -6,13 +6,17 @@ db.printShardingStatus() .. method:: db.printShardingStatus() - Provides a formatted report of the sharding configuration and the - information regarding existing chunks in a :term:`sharded cluster`. + Prints a formatted report of the sharding configuration and the + information regarding existing chunks in a :term:`sharded cluster`. Only use :method:`db.printShardingStatus()` when connected to a :program:`mongos` instance. - .. |method| replace:: :method:`db.printCollectionStats()` + .. include:: /includes/param-verbose-printShardingStatus.rst + + See :doc:`/reference/sharding-status` for details of the output. + + .. |method| replace:: :method:`db.printShardingStatus()` .. |method-alternative| replace:: :doc:`/reference/config-database/` .. include:: /includes/note-method-does-not-return-json.rst diff --git a/source/reference/method/sh.status.txt b/source/reference/method/sh.status.txt index 4780e4bbc86..f87e5e69936 100644 --- a/source/reference/method/sh.status.txt +++ b/source/reference/method/sh.status.txt @@ -6,6 +6,13 @@ sh.status() .. method:: sh.status() - :returns: a formatted report of the status of the :term:`sharded - cluster`, including data regarding the distribution of - chunks. + Prints a formatted report of the sharding configuration and the + information regarding existing chunks in a :term:`sharded cluster`. + The default behavior suppresses the detailed chunk information if + the total number of chunks is greater than or equal to 20. + + .. include:: /includes/param-verbose-printShardingStatus.rst + + See :doc:`/reference/sharding-status` for details of the output. + + .. seealso:: :method:`db.printShardingStatus()` diff --git a/source/reference/sharding-status.txt b/source/reference/sharding-status.txt new file mode 100644 index 00000000000..a5d4bbd7215 --- /dev/null +++ b/source/reference/sharding-status.txt @@ -0,0 +1,193 @@ +=============== +Sharding Status +=============== + +.. default-domain:: mongodb + +This document explains the output of the :program:`mongo` shell method +:method:`sh.status()`. + +Sharding Status Output +---------------------- + +The :method:`sh.status()` methods display sharding information. + +The :ref:`sharding-status-version-fields` section displays information on the +:term:`config database`: + +.. code-block:: javascript + + --- Sharding Status --- + sharding version: { + "_id" : , + "version" : , + "minCompatibleVersion" : , + "currentVersion" : , + "clusterId" : + } + +The :ref:`sharding-status-shards-fields` section lists information on +the shard(s). For each shard, the section displays the name, host, and +the associated tags, if any. + +.. code-block:: javascript + + shards: + { "_id" : , + "host" : , + "tags" : [ ... ] + } + { "_id" : , + "host" : , + "tags" : [ ... ] + } + ... + +The :ref:`sharding-status-databases-fields` section lists information +on the database(s). For each database, the section displays the name, +whether the database has sharding enabled, and the :term:`primary +shard` for the database. + +.. code-block:: javascript + + databases: + { "_id" : , + "partitioned" : , + "primary" : + } + { "_id" : , + "partitioned" : , + "primary" : + } + ... + +The :ref:`sharding-status-collection-fields` section provides +information on the sharding details for sharded collection(s). For each +sharded collection, the section displays the shard key, the number of +chunks per shard(s), the distribution of documents across chunks +[#chunk-details]_, and the tag information, if any, for shard key +range(s). + +.. code-block:: javascript + + . + shard key: { : <1 or hashed> } + chunks: + + + ... + { : } -->> { : } on : + { : } -->> { : } on : + ... + tag: { : } -->> { : } + ... + +Sharding Status Fields +---------------------- + +.. _sharding-status-version-fields: + +Sharding Version +~~~~~~~~~~~~~~~~ + +.. data:: shardingStatus.sharding-version._id + + The :data:`~shardingStatus.sharding-version._id` is an identifier + for the version details. + +.. data:: shardingStatus.sharding-version.version + + The :data:`~shardingStatus.sharding-version.version` is the version + of the :term:`config server ` for the sharded + cluster. + +.. data:: shardingStatus.sharding-version.minCompatibleVersion + + The :data:`~shardingStatus.sharding-version.minCompatibleVersion` is + the minimum compatible version of the config server. + +.. data:: shardingStatus.sharding-version.currentVersion + + The :data:`~shardingStatus.sharding-version.currentVersion` is + the current version of the config server. + +.. data:: shardingStatus.sharding-version.clusterId + + The :data:`~shardingStatus.sharding-version.clusterId` is the + identification for the sharded cluster. + +.. _sharding-status-shards-fields: + +Shards +~~~~~~ + +.. data:: shardingStatus.shards._id + + The :data:`~shardingStatus.shards._id` displays the name of the shard. + +.. data:: shardingStatus.shards.host + + The :data:`~shardingStatus.shards.host` displays the host location + of the shard. + +.. data:: shardingStatus.shards.tags + + The :data:`~shardingStatus.shards.tags` displays all the tags for + the shard. The field only displays if the shard has tags. + +.. _sharding-status-databases-fields: + +Databases +~~~~~~~~~ + +.. data:: shardingStatus.databases._id + + The :data:`~shardingStatus.databases._id` displays the name of the database. + +.. data:: shardingStatus.databases.partitioned + + The :data:`~shardingStatus.databases.partitioned` displays whether + the database has sharding enabled. If ``true``, the database has + sharding enabled. + +.. data:: shardingStatus.databases.primary + + The :data:`~shardingStatus.databases.primary` displays the + :term:`primary shard` for the database. + +.. _sharding-status-collection-fields: + +Sharded Collection +~~~~~~~~~~~~~~~~~~ + +.. data:: shardingStatus.databases.shard-key + + The :data:`~shardingStatus.databases.shard-key` displays the shard + key specification document. + +.. data:: shardingStatus.databases.chunks + + The :data:`~shardingStatus.databases.chunks` lists all the shards + and the number of chunks that reside on each shard. + +.. data:: shardingStatus.databases.chunk-details + + The :data:`~shardingStatus.databases.chunk-details` lists the details + of the chunks [#chunk-details]_: + + - The range of shard key values that define the chunk, + + - The shard where the chunk resides, and + + - The last modified timestamp for the chunk. + +.. data:: shardingStatus.databases.tag + + The :data:`~shardingStatus.databases.tag` lists the details of + the tags associated with a range of shard key values. + +.. [#chunk-details] The sharded collection section, by default, + displays the chunk information if the total number of chunks is less + than 20. To display the information when you have 20 or more chunks, + call the the :method:`sh.status()` methods with the ``verbose`` + parameter set to ``true``, i.e. ``sh.status(true)``.