Skip to content

Commit 6e41109

Browse files
zach-carrzach-carr
authored
(DOCSP-11933) mongocli atlas|om metrics databases describe (#267)
* (DOCSP-11933) mongocli atlas|om metrics databases describe
1 parent f18611f commit 6e41109

File tree

4 files changed

+708
-0
lines changed

4 files changed

+708
-0
lines changed

‎source/reference/atlas/metric-commands.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Atlas ``metric`` Commands
1010
:titlesonly:
1111

1212
List Process Metrics </reference/atlas/metrics-process>
13+
Describe a Database </reference/atlas/metrics-databases-describe>
1314
List Available Databases for a Process </reference/atlas/metrics-databases-list>
1415
Describe Available Metrics </reference/atlas/metrics-disks-describe>
1516
List Available Partitions </reference/atlas/metrics-disks-list>

‎source/reference/atlas/metrics-databases-describe.txt

Lines changed: 342 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,342 @@
1+
.. _mcli-atlas-metrics-databases-describe-cmd:
2+
3+
=========================================
4+
mongocli atlas metrics databases describe
5+
=========================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. include:: /includes/styles/corrections.rst
16+
17+
The ``metrics databases describe`` command gets the measurements of the
18+
specified database for an |service| process.
19+
20+
You can get the hostnames associated with a particular |service| project
21+
with the :ref:`process list <mcli-atlas-process-list-cmd>` command.
22+
23+
Syntax
24+
------
25+
26+
.. code-block:: text
27+
28+
mongocli atlas metrics databases describe <hostname>:<port> <db-name>
29+
--granularity <time-interval>
30+
--period <time-period>
31+
--start <start-time>
32+
--end <end-time>
33+
[ --type <type-of-measurement> ]
34+
[ --limit <number-of-items-per-page> ]
35+
[ --output|-o <output-format> ]
36+
[ --page <page-number> ]
37+
[ --profile|-P <profile-name> ]
38+
[ --projectId <id-of-project> ]
39+
40+
.. include:: /includes/fact-command-line-help.rst
41+
42+
.. _mcli-atlas-metrics-databases-describe-options:
43+
44+
Options
45+
-------
46+
47+
.. list-table::
48+
:header-rows: 1
49+
:widths: 20 10 60 10
50+
51+
* - Option
52+
- Type
53+
- Description
54+
- Required?
55+
56+
* - ``<hostname>:<port>``
57+
- String
58+
- The hostname of the server running the |service| MongoDB process
59+
and the port to which the process listens.
60+
- yes
61+
62+
* - ``<db-name>``
63+
- String
64+
- Name of the database to describe.
65+
- yes
66+
67+
* - ``--granularity``
68+
- String
69+
- An |iso8601|-formatted time period that specifies the interval
70+
between measurement data points. For example, ``PT1M`` specifies
71+
1-minute granularity.
72+
73+
The following subset of |iso8601|-formatted time periods are
74+
supported:
75+
76+
- ``PT1M``
77+
- ``PT5M``
78+
- ``PT1H``
79+
- ``P1D``
80+
81+
When you specify ``granularity``, you must specify either
82+
``period`` *or* ``start`` and ``end``.
83+
- yes
84+
85+
* - ``--period``
86+
- String
87+
- An |iso8601|-formatted time period that specifies the length of
88+
time in the past to query. For example, to request the last 36
89+
hours, specify: ``--period P1DT12H``. Mutually exclusive with
90+
``start`` and ``end``.
91+
- yes
92+
93+
* - ``--start``
94+
- String
95+
- The time at which to start retrieving metrics, as specified by an
96+
|iso8601| timestamp string. If you specify ``start`` you must
97+
also specify ``end``. Mutually exclusive with ``period``.
98+
- yes
99+
100+
* - ``--end``
101+
- String
102+
- The time at which to stop retrieving metrics, as specified by an
103+
|iso8601| timestamp string. If you specify ``end`` you must also
104+
specify ``start``. Mutually exclusive with ``period``.
105+
- yes
106+
107+
* - ``--type``
108+
- String
109+
- Specifies which measurement to return. If ``type`` is not
110+
specified, all metrics are returned.
111+
112+
You must specify metrics that are valid for the host. |service|
113+
returns an error if any specified metrics are invalid.
114+
115+
The following measurement values are valid:
116+
117+
- ``DATABASE_AVERAGE_OBJECT_SIZE``
118+
- ``DATABASE_COLLECTION_COUNT``
119+
- ``DATABASE_DATA_SIZE``
120+
- ``DATABASE_STORAGE_SIZE``
121+
- ``DATABASE_INDEX_SIZE``
122+
- ``DATABASE_INDEX_COUNT``
123+
- ``DATABASE_EXTENT_COUNT``
124+
- ``DATABASE_OBJECT_COUNT``
125+
- ``DATABASE_VIEW_COUNT``
126+
127+
- no
128+
129+
* - ``--limit``
130+
- integer
131+
- Number of items per page, up to a maximum of 500. Defaults to
132+
``100`` if omitted.
133+
- no
134+
135+
* - ``--output``, ``-o``
136+
- string
137+
- .. include:: /includes/extracts/fact-basic-options-output.rst
138+
- no
139+
140+
* - ``--page``
141+
- integer
142+
- Page number (1-based). Defaults to ``1`` if not specified.
143+
- no
144+
145+
* - ``--profile``, ``-P``
146+
- string
147+
- Name of the profile where the public and private
148+
keys for the project are saved. If omitted, uses the
149+
{+default-profile+}. To learn more about creating a
150+
profile, see :ref:`mcli-configure`.
151+
- no
152+
153+
* - ``--projectId``
154+
- string
155+
- Unique identifier of the project that contains the
156+
alerts to retrieve. If omitted, uses the project ID in
157+
the profile or :ref:`environment variable <mcli-env-var>`.
158+
- no
159+
160+
.. _mcli-atlas-metrics-databases-describe-output:
161+
162+
Output
163+
------
164+
165+
.. include:: /includes/command-output-intro.rst
166+
167+
.. tabs::
168+
169+
.. tab:: Default
170+
:tabid: default
171+
172+
.. code-block:: none
173+
:copyable: false
174+
175+
NAME UNITS TIMESTAMP VALUE
176+
DATABASE_AVERAGE_OBJECT_SIZE BYTES 2020-10-06T14:47:03Z 691.96466
177+
DATABASE_COLLECTION_COUNT SCALAR 2020-10-06T14:47:03Z 5
178+
DATABASE_DATA_SIZE BYTES 2020-10-06T14:47:03Z 5.2300764e+07
179+
DATABASE_STORAGE_SIZE BYTES 2020-10-06T14:47:03Z 4.1414656e+07
180+
DATABASE_INDEX_SIZE BYTES 2020-10-06T14:47:03Z 2.0668416e+07
181+
DATABASE_INDEX_COUNT SCALAR 2020-10-06T14:47:03Z 9
182+
DATABASE_EXTENT_COUNT SCALAR 2020-10-06T14:47:03Z 0
183+
DATABASE_OBJECT_COUNT SCALAR 2020-10-06T14:47:03Z 75583
184+
DATABASE_VIEW_COUNT SCALAR 2020-10-06T14:47:03Z 0
185+
186+
.. tab:: JSON
187+
:tabid: json
188+
189+
The JSON response returns an object with the following fields for
190+
the database you specify:
191+
192+
.. list-table::
193+
:header-rows: 1
194+
:widths: 30 10 60
195+
196+
* - Name
197+
- Type
198+
- Description
199+
200+
* - ``databaseName``
201+
- string
202+
- The name of the database to which the measurements pertain.
203+
204+
* - ``end``
205+
- string
206+
- The end of the period for which to retrieve measurements,
207+
specified as an |iso8601| timestamp.
208+
209+
* - ``granularity``
210+
- string
211+
- An |iso8601|-formatted
212+
time period that specifies the size of the interval
213+
covered by each data point. For example, ``PT5M``
214+
specifies a 5-minute granularity.
215+
216+
* - ``groupId``
217+
- string
218+
- ID of the project that owns the |service| MongoDB process.
219+
220+
* - ``hostId``
221+
- string
222+
- The hostname of the machine running the |service| MongoDB
223+
process.
224+
225+
* - ``links``
226+
- array
227+
- An array of documents, representing a
228+
:ref:`link <api-linking>` to one or more sub-resources and/
229+
or related resources such as
230+
:ref:`list pagination <api-lists>`.
231+
See :ref:`api-linking` for more information.
232+
233+
* - ``measurements``
234+
- array of objects
235+
- An array of measurements and their data points.
236+
237+
* - ``measurements.dataPoints``
238+
- array of objects
239+
- An array of objects, where each object represents a single
240+
data point. If there is no data point available for a
241+
particular moment in time (i.e., a timestamp), the
242+
``value`` field is set to ``null``.
243+
244+
* - ``measurements.dataPoints.timestamp``
245+
- string
246+
- The timestamp of the beginning of the time interval
247+
represented by this data point.
248+
249+
* - ``measurements.dataPoints.value``
250+
- float
251+
- The value of the data point.
252+
253+
* - ``measurements.name``
254+
- string
255+
- The name of the measurement.
256+
257+
* - ``measurements.units``
258+
- string
259+
- How the measurement is quantified. Possible units are:
260+
261+
- ``PERCENT``
262+
- ``MILLISECONDS``
263+
- ``BYTES``
264+
- ``GIGABYTES``
265+
- ``BYTES_PER_SECOND``
266+
- ``MEGABYTES_PER_SECOND``
267+
- ``GIGABYTES_PER_HOUR``
268+
- ``SCALAR_PER_SECOND``
269+
- ``SCALAR``
270+
271+
* - ``processId``
272+
- string
273+
- The hostname and port of the machine running the |service|
274+
MongoDB process.
275+
276+
* - ``start``
277+
- string
278+
- The start of the period for which to retrieve measurements
279+
specified as an |iso8601| timestamp.
280+
281+
.. _mcli-atlas-metrics-databases-describe-example:
282+
283+
Example
284+
-------
285+
286+
The following example uses the ``mongocli atlas metrics databases
287+
describe`` command to retrieve the ``DATABASE_AVERAGE_OBJECT_SIZE`` for
288+
the database ``sample_db``, running on
289+
``atlas-111xxx-shard-00-00.111xx.mongodb.net``.
290+
It uses the {+default-profile+} for accessing |service| and specifying
291+
a project.
292+
293+
.. code-block:: json
294+
295+
mongocli atlas metrics databases describe cluster0-shard-00-00.111xx.mongodb.net:27017 sample_db --granularity PT5M --period PT1H --type DATABASE_AVERAGE_OBJECT_SIZE -o json
296+
297+
The command prints the following fields to the terminal in JSON format.
298+
To learn more about these fields, see
299+
:ref:`mcli-atlas-metrics-databases-describe-output`.
300+
301+
.. code-block:: json
302+
:copyable: false
303+
304+
{
305+
"end": "2020-10-06T21:05:21Z",
306+
"granularity": "PT5M",
307+
"groupId": "5ddab74939ffb786fa79f10f",
308+
"hostId": "atlas-111xxx-shard-00-00.111xx.mongodb.net:27017",
309+
"links": [
310+
{
311+
"rel": "self",
312+
"href": "..."
313+
},
314+
{
315+
"rel": "http://mms.mongodb.com/host",
316+
"href": "..."
317+
}
318+
],
319+
"measurements": [
320+
{
321+
"dataPoints": [
322+
{
323+
"timestamp": "2020-10-06T20:25:21Z",
324+
"value": 691.96466
325+
},
326+
{
327+
"timestamp": "2020-10-06T20:50:21Z",
328+
"value": 691.96466
329+
},
330+
{
331+
"timestamp": "2020-10-06T21:05:21Z",
332+
"value": 691.96466
333+
}
334+
],
335+
"name": "DATABASE_AVERAGE_OBJECT_SIZE",
336+
"units": "BYTES"
337+
}
338+
],
339+
"processId": "atlas-111xxx-shard-00-00.111xx.mongodb.net:27017",
340+
"start": "2020-10-06T20:25:21Z",
341+
"databaseName": "sample_db"
342+
}

‎source/reference/ops-manager/metric-commands.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,6 @@ Ops Manager ``metric`` Commands
1010
:titlesonly:
1111

1212
List Process Metrics </reference/ops-manager/metrics-process>
13+
Describe a Database </reference/ops-manager/metrics-databases-describe>
1314
Describe Available Metrics </reference/ops-manager/metrics-disks-describe>
1415
List Available Partitions </reference/ops-manager/metrics-disks-list>

0 commit comments

Comments
 (0)