Skip to content

Commit c6d5b0d

Browse files
author
Dave
authored
DOCS-15046 BACKPORT (#751)
* DOCS-15046 BACKPORT * Server versions * Term update
1 parent 70091af commit c6d5b0d

File tree

2 files changed

+161
-54
lines changed

2 files changed

+161
-54
lines changed

‎source/reference/command/dbStats.txt‎

Lines changed: 86 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ Definition
2424

2525
db.runCommand( {
2626
dbStats: 1,
27-
scale: <number> // Optional
27+
scale: <number>,
28+
freeStorage: 0
2829
} )
2930

3031
The :dbcommand:`dbStats` command takes the following fields:
@@ -33,16 +34,13 @@ Definition
3334
:header-rows: 1
3435
:widths: 20 80
3536

36-
* - Parameter
37-
37+
* - Fields
3838
- Description
3939

40-
* - ``dbStats``
41-
40+
* - :dbcommand:`dbStats`
4241
- 1
4342

4443
* - :ref:`scale <dbStats-scale>`
45-
4644
- .. _dbStats-scale:
4745

4846
Optional. The scale factor for the various size data. The
@@ -57,6 +55,17 @@ Definition
5755

5856
.. include:: /includes/extracts/4.2-changes-stats-scaleFactor.rst
5957

58+
* - :ref:`freeStorage <dbStats-freeStorage>`
59+
- .. _dbStats-freeStorage:
60+
61+
Optional. To return details on free space allocated to
62+
collections, set ``freeStorage`` to 1.
63+
64+
If the instance has a large number of collections or indexes,
65+
obtaining free space usage data may cause processing delays.
66+
To gather :dbcommand:`dbStats` information without free space
67+
details, either set ``freeStorage`` to 0 or do not include
68+
the field.
6069

6170
In :binary:`~bin.mongosh`, the :method:`db.stats()` function
6271
provides a wrapper around :dbcommand:`dbStats`.
@@ -151,9 +160,10 @@ Output
151160
allocated to indexes. See :data:`~dbStats.indexFreeStorageSize` for
152161
the total free index size.
153162

154-
This value is always included in the :dbcommand:`dbStats` output.
163+
To include this value in the :dbcommand:`dbStats` output, set
164+
:ref:`freeStorage <dbStats-freeStorage>` to 1.
155165

156-
.. versionadded:: 5.0
166+
*Updated in version 5.2.1, and 5.0.6.*
157167

158168
.. data:: dbStats.indexes
159169

@@ -174,7 +184,10 @@ Output
174184
allocated to document storage. See :data:`~dbStats.freeStorageSize`
175185
for the total free document storage size.
176186

177-
.. versionadded:: 5.0
187+
To include this value in the :dbcommand:`dbStats` output, set
188+
:ref:`freeStorage <dbStats-freeStorage>` to 1.
189+
190+
*Updated in version 5.2.1, and 5.0.6.*
178191

179192
.. data:: dbStats.totalSize
180193

@@ -192,7 +205,10 @@ Output
192205
:data:`~dbStats.freeStorageSize` and
193206
:data:`~dbStats.indexFreeStorageSize`.
194207

195-
.. versionadded:: 5.0
208+
To include this value in the :dbcommand:`dbStats` output, set
209+
:ref:`freeStorage <dbStats-freeStorage>` to 1.
210+
211+
*Updated in version 5.2.1, and 5.0.6.*
196212

197213
.. data:: dbStats.scaleFactor
198214

@@ -224,12 +240,66 @@ Output
224240
Examples
225241
--------
226242

227-
If you are only interested in one field, the output of the
228-
:dbcommand:`dbStats` command can be limited to just that field. For
229-
example, the following command returns the current total free
230-
storage size.
243+
The following examples demonstrate :dbcommand:`dbStats` usage.
244+
245+
Limit Data Returned
246+
~~~~~~~~~~~~~~~~~~~
247+
248+
To limit the data returned to a single field, append the field name to
249+
the :dbcommand:`dbStats` command. This example returns the
250+
:data:`~dbStats.indexSize` value:
231251

232252
.. code-block:: javascript
233253

234-
db.runCommand( { dbStats: 1 } ).freeStorageSize
235-
254+
db.runCommand( { dbStats: 1 } ).indexSize
255+
256+
View Free Space Allocated to Collections
257+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
258+
259+
To view free storage usage, set :ref:`freeStorage
260+
<dbStats-freeStorage>` to 1.
261+
262+
.. code-block:: javascript
263+
264+
db.runCommand( { dbStats: 1, scale: 1024, freeStorage: 1 } )
265+
266+
Example output:
267+
268+
.. code-block:: javascript
269+
:copyable: false
270+
:emphasize-lines: 9, 12, 14
271+
272+
{
273+
db: 'test',
274+
collections: 2,
275+
views: 0,
276+
objects: 1689,
277+
avgObjSize: 52.56542332741267,
278+
dataSize: 86.7021484375,
279+
storageSize: 100,
280+
freeStorageSize: 32,
281+
indexes: 2,
282+
indexSize: 116,
283+
indexFreeStorageSize: 36,
284+
totalSize: 216,
285+
totalFreeStorageSize: 68,
286+
scaleFactor: 1024,
287+
fsUsedSize: 60155820,
288+
fsTotalSize: 61255492,
289+
ok: 1,
290+
'$clusterTime': {
291+
clusterTime: Timestamp({ t: 1646085664, i: 1 }),
292+
signature: {
293+
hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
294+
keyId: Long("0")
295+
}
296+
},
297+
operationTime: Timestamp({ t: 1646085664, i: 1 })
298+
}
299+
300+
The :ref:`freeStorage <dbStats-freeStorage>` field enables
301+
the collection and display of the highlighted metrics.
302+
303+
The :ref:`scale <dbStats-scale>` field sets the displayed values to
304+
kilobytes.
305+

‎source/reference/method/db.stats.txt‎

Lines changed: 75 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -20,25 +20,21 @@ Description
2020
The :method:`db.stats()` method is a wrapper around the
2121
:dbcommand:`dbStats` database command.
2222

23-
Parameters
23+
Fields
2424
~~~~~~~~~~
2525

26-
The :method:`db.stats()` method has the following optional parameter:
26+
The :method:`db.stats()` method has the following optional fields:
2727

2828
.. list-table::
2929
:header-rows: 1
3030
:widths: 20 20 80
3131

32-
* - Parameter
33-
32+
* - Field
3433
- Type
35-
3634
- Description
3735

3836
* - :ref:`scale <db.stats-scale>`
39-
4037
- number
41-
4238
- .. _db.stats-scale:
4339

4440
Optional. The scale factor for the various size data. The
@@ -53,36 +49,57 @@ The :method:`db.stats()` method has the following optional parameter:
5349

5450
.. include:: /includes/extracts/4.2-changes-stats-scaleFactor.rst
5551

52+
* - :ref:`freeStorage <db.stats-freeStorage>`
53+
- number
54+
- .. _db.stats-freeStorage:
55+
56+
Optional. To return information on free space allocated to
57+
collections, set ``freeStorage`` to 1.
58+
59+
If the instance has a large number of collections or indexes,
60+
obtaining free space usage data may cause processing delays. To
61+
gather :method:`db.stats()` data without free space details,
62+
either set ``freeStorage`` to 0 or do not include the field.
63+
5664
Output
5765
~~~~~~
5866

59-
The :method:`db.stats()` method returns a :term:`document` with statistics reflecting
60-
the database system's state. For example:
67+
The :method:`db.stats()` method returns a :term:`document` with
68+
statistics about the database system's state. A complete listing,
69+
including :ref:`freeStorage <db.stats-freeStorage>` details, resembles
70+
the following:
6171

6272
.. code-block:: javascript
6373

6474
{
65-
"db" : "admin",
66-
"collections" : 2,
67-
"views" : 0,
68-
"objects" : 5,
69-
"avgObjSize" : 336.8,
70-
"dataSize" : 1684,
71-
"storageSize" : 69632,
72-
"freeStorageSize" : 28672,
73-
"indexes" : 3,
74-
"indexSize" : 106496,
75-
"indexFreeStorageSize" : 45056,
76-
"totalSize" : 176128,
77-
"totalFreeStorageSize" : 73728,
78-
"scaleFactor" : 1,
79-
"fsUsedSize" : 47881682944,
80-
"fsTotalSize" : 62725623808,
81-
"ok" : 1
75+
db: 'test',
76+
collections: 2,
77+
views: 0,
78+
objects: 1689,
79+
avgObjSize: 52.56542332741267,
80+
dataSize: 86.7021484375,
81+
storageSize: 100,
82+
freeStorageSize: 32,
83+
indexes: 2,
84+
indexSize: 116,
85+
indexFreeStorageSize: 36,
86+
totalSize: 216,
87+
totalFreeStorageSize: 68,
88+
scaleFactor: 1024,
89+
fsUsedSize: 60155820,
90+
fsTotalSize: 61255492,
91+
ok: 1,
92+
'$clusterTime': {
93+
clusterTime: Timestamp({ t: 1646085664, i: 1 }),
94+
signature: {
95+
hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
96+
keyId: Long("0")
97+
}
98+
},
99+
operationTime: Timestamp({ t: 1646085664, i: 1 })
82100
}
83101

84-
For an explanation of the
85-
output, see :ref:`dbstats-output`.
102+
For an explanation of the output, see :ref:`dbstats-output`.
86103

87104
Behavior
88105
--------
@@ -102,10 +119,14 @@ Replica Set Member State Restriction
102119

103120
.. |operations| replace:: :dbcommand:`dbStats`
104121

105-
Example
106-
-------
122+
Examples
123+
--------
107124

108-
The following example returns various size values in kilobytes:
125+
Scale Output Values
126+
~~~~~~~~~~~~~~~~~~~
127+
128+
To to return values in kilobytes, set the :ref:`scale <db.stats-scale>`
129+
to ``1024``:
109130

110131
.. code-block:: javascript
111132

@@ -115,19 +136,35 @@ The following example returns various size values in kilobytes:
115136

116137
The scale factor rounds values to whole numbers.
117138

118-
You can also use ``db.stats()`` to return a single value, such as the
119-
``freeStorageSize``.
139+
Return a Single Value
140+
~~~~~~~~~~~~~~~~~~~~~
141+
142+
To return a single value, such as :data:`~dbStats.indexSize`, append
143+
the field name to ``db.stats()``.
120144

121145
.. code-block:: javascript
122146

123-
db.stats().freeStorageSize
124-
db.stats(1024).freeStorageSize
147+
db.stats().indexSize
148+
db.stats(1024).indexSize
125149

126-
The output shows the difference between the raw and scaled values.
150+
The output shows the difference between the original and scaled values.
127151

128152
.. code-block:: javascript
129153
:copyable: false
130154

131-
28672
132-
28
155+
118784
156+
116
157+
158+
Return Information on Free Space Allocated to Collections
159+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160+
161+
To return information on free space allocated to collections, pass the
162+
:ref:`freeStorage <dbStats-freeStorage>` field to ``db.stats()``.
163+
164+
The following example returns the :data:`~dbStats.indexFreeStorageSize`
165+
in kilobytes:
166+
167+
.. code-block::
168+
169+
db.stats( { freeStorage: 1, scale: 1024 } ).indexFreeStorageSize
133170

0 commit comments

Comments
 (0)