Navigation

Get Measurements for a MongoDB Process

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

Get measurements for a specific Atlas MongoDB process. An Atlas MongoDB process can be either a mongod or mongos.

The Atlas API authenticates using HTTP Digest Authentication. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request.

To learn how to configure API access for an Atlas project, see Configure Atlas API Access.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

GET /groups/{GROUP-ID}/processes/{HOST}:{PORT}/measurements
Parameter
Type
Necessity
Description
GROUP-ID
string
Required
Unique 24-hexadecimal digit string that identifies the project that owns this Atlas MongoDB process.
HOST
string
Required
Hostname, FQDN, IPv4 address, or IPv6 address of the machine running the Atlas MongoDB process.
PORT
number
Required
IANA port to which the Atlas MongoDB process listens.
Name
Type
Necessity
Description
Default
pageNum
integer
Optional
Page number, starting with one, that Atlas returns of the total number of objects.
1
itemsPerPage
integer
Optional
Number of items that Atlas returns per page, up to a maximum of 500.
100
includeCount
boolean
Optional
Flag that indicates whether Atlas returns the totalCount parameter in the response body.
true
pretty
boolean
Optional
Flag that indicates whether Atlas returns the JSON response in the prettyprint format.
false
envelope
boolean
Optional

Flag that indicates whether Atlas wraps the response in an envelope.

Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query.

Endpoints that return a list of results use the results object as an envelope. Atlas adds the status parameter to the response body.

false
granularity
string
Required

Duration in ISO 8601 notation that specifies the interval between measurement data points.

Example

PT1M specifies 1-minute granularity.

Atlas supports the following subset of ISO 8601-formatted time periods:

  • PT1M
  • PT5M
  • PT1H
  • P1D

When you specify granularity, you must specify either period or start and end.

period
string
Required

Duration in ISO 8601 notation that specifies the length of time in the past to query. Mutually exclusive with start and end.

Example

To request the last 36 hours, specify: period=P1DT12H.

start
string
Required
Timestamp in ISO 8601 date and time format in UTC when to start retrieving measurements. If you specify start you must also specify end. Mutually exclusive with period.
end
string
Required

Timestamp in ISO 8601 date and time format in UTC when to stop retrieving measurements.

If you specify end you must also specify start. Mutually exclusive with period.

m
string
Optional

Type of measurements this endpoint return. If you don't set m, the endpoint returns all measurements.

To specify multiple values for m, you must repeat the m parameter.

Example
../measurements?m=<measurement>&m=<measurement>&m=...

You must specify measurements that are valid for the host. Atlas returns an error if any specified measurements are invalid.

The Measurement Values section details these metrics.

Request Body Parameters

This endpoint doesn't use HTTP request body parameters.

Important
Limited Metrics for Free/Shared Tier Clusters

M0/M2/M5 clusters return a subset of the metrics documented.

If you set the query parameter to envelope=true, the resource wraps the response in a content object.

The HTTP response returns a JSON document that includes the following objects:

Name
Type
Description
end
string

Timestamp in ISO 8601 date and time format in UTC when to stop retrieving measurements.

If you specify end you must also specify start. Mutually exclusive with period.

granularity
string

Duration in ISO 8601 notation that specifies the interval between measurement data points.

Example

PT1M specifies 1-minute granularity.

Atlas supports the following subset of ISO 8601-formatted time periods:

  • PT1M
  • PT5M
  • PT1H
  • P1D

When you specify granularity, you must specify either period or start and end.

groupId
string
Unique 24-hexadecimal digit string that identifies the project that owns the Atlas MongoDB process.
hostId
string
Hostname and port of the host running the Atlas MongoDB process.
links
array

One or more links to sub-resources and/or related resources. The relations between URLs are explained in the Web Linking Specification

measurements
array
List of measurements recorded and their data points.
measurements
.dataPoints
array
Value of and metadata provided for one data point. If Atlas has no data point for a particular moment in time, the value field is set to null.
measurements
.dataPoints
.timestamp
string
Timestamp in ISO 8601 date and time format in UTC when this time interval that this data point represents began.
measurements
.dataPoints
.value
number
Value this data point provides.
measurements
.name
string

Name of the measurement that this data point covers.

The Measurement Values section details these metrics.

measurements
.units
string

Magnitude by which Atlas quanitifies the measurement. Atlas uses units of throughput, storage, and time that include:

  • PERCENT
  • MILLISECONDS
  • BYTES
  • GIGABYTES
  • BYTES_PER_SECOND
  • MEGABYTES_PER_SECOND
  • GIGABYTES_PER_HOUR
  • SCALAR_PER_SECOND
  • SCALAR
processId
string
Hostname and port of the machine running the Atlas MongoDB process.
start
string
Timestamp in ISO 8601 date and time format in UTC when to start retrieving measurements. If you specify start you must also specify end. Mutually exclusive with period.
PROCESS_CPU_USER
PROCESS_CPU_KERNEL
PROCESS_CPU_CHILDREN_USER
PROCESS_CPU_CHILDREN_KERNEL
MongoDB CPU usage. For hosts with more than one CPU core, these values can exceed 100%.
PROCESS_NORMALIZED_CPU_USER
PROCESS_NORMALIZED_CPU_KERNEL
PROCESS_NORMALIZED_CPU_CHILDREN_USER
PROCESS_NORMALIZED_CPU_CHILDREN_KERNEL
MongoDB CPU usage scaled to a range of 0% to 100%. Atlas computes this value by dividing by the number of CPU cores.
ASSERT_REGULAR
ASSERT_WARNING
ASSERT_MSG
ASSERT_USER
Rate of asserts for a MongoDB process found in the asserts document that the serverStatus command generates.
BACKGROUND_FLUSH_AVG
Amount of data flushed in the background.
CACHE_BYTES_READ_INTO
CACHE_BYTES_WRITTEN_FROM
CACHE_DIRTY_BYTES
CACHE_USED_BYTES
TICKETS_AVAILABLE_READS
TICKETS_AVAILABLE_WRITE
Amount of bytes in the WiredTiger storage engine cache and tickets found in the wiredTiger.cache and wiredTiger.concurrentTransactions documents that the serverStatus command generates.
CONNECTIONS
Number of connections to a MongoDB process found in the connections document that the serverStatus command generates.
CURSORS_TOTAL_OPEN
CURSORS_TOTAL_TIMED_OUT
Number of cursors for a MongoDB process found in the metrics.cursor document that the serverStatus command generates.
EXTRA_INFO_PAGE_FAULTS
GLOBAL_ACCESSES_NOT_IN_MEMORY
GLOBAL_PAGE_FAULT_EXCEPTIONS_THROWN
Numbers of Memory Issues and Page Faults for a MongoDB process.
GLOBAL_LOCK_CURRENT_QUEUE_TOTAL
GLOBAL_LOCK_CURRENT_QUEUE_READERS
GLOBAL_LOCK_CURRENT_QUEUE_WRITERS
Number of operations waiting on locks for the MongoDB process that the serverStatus command generates. Cloud Manager computes these values based on the type of storage engine.
INDEX_COUNTERS_BTREE_ACCESSES
INDEX_COUNTERS_BTREE_HITS
INDEX_COUNTERS_BTREE_MISSES
INDEX_COUNTERS_BTREE_MISS_RATIO
Number of index btree operations.
JOURNALING_COMMITS_IN_WRITE_LOCK
JOURNALING_MB
JOURNALING_WRITE_DATA_FILES_MB
Number of journaling operations.
MEMORY_RESIDENT
MEMORY_VIRTUAL
MEMORY_MAPPED
COMPUTED_MEMORY
Amount of memory for a MongoDB process found in the mem document that the serverStatus command collects.
NETWORK_BYTES_IN
NETWORK_BYTES_OUT
NETWORK_NUM_REQUESTS
Amount of throughput for MongoDB process found in the network document that the serverStatus command collects.
OPLOG_SLAVE_LAG_MASTER_TIME
OPLOG_MASTER_TIME
OPLOG_MASTER_LAG_TIME_DIFF
OPLOG_RATE_GB_PER_HOUR
Durations and throughput of the MongoDB process' oplog.
DB_STORAGE_TOTAL
DB_DATA_SIZE_TOTAL
Number of database operations on a MongoDB process since the process last started.
OPCOUNTER_CMD
OPCOUNTER_QUERY
OPCOUNTER_UPDATE
OPCOUNTER_DELETE
OPCOUNTER_GETMORE
OPCOUNTER_INSERT
Rate of database operations on a MongoDB process since the process last started found in the opcounters document that the serverStatus command collects.
OPCOUNTER_REPL_CMD
OPCOUNTER_REPL_UPDATE
OPCOUNTER_REPL_DELETE
OPCOUNTER_REPL_INSERT
Rate of database operations on MongoDB secondaries found in the opcountersRepl document that the serverStatus command collects.
DOCUMENT_METRICS_RETURNED
DOCUMENT_METRICS_INSERTED
DOCUMENT_METRICS_UPDATED
DOCUMENT_METRICS_DELETED
Average rate of documents returned, inserted, updated, or deleted per second during a selected time period.
OPERATIONS_SCAN_AND_ORDER
Average rate for operations per second during a selected time period that perform a sort but cannot perform the sort using an index.
OP_EXECUTION_TIME_READS
OP_EXECUTION_TIME_WRITES
OP_EXECUTION_TIME_COMMANDS
Average execution time in milliseconds per read, write, or command operation during a selected time period.
RESTARTS_IN_LAST_HOUR
Number of times the host restarted within the previous hour.
QUERY_EXECUTOR_SCANNED
Average rate per second to scan index items during queries and query-plan evaluations found in the value of totalKeysExamined from the explain command.
QUERY_EXECUTOR_SCANNED_OBJECTS
Average rate of documents scanned per second during queries and query-plan evaluations found in the value of totalDocsExamined from the explain command.
QUERY_TARGETING_SCANNED_PER_RETURNED
Ratio of the number of index items scanned to the number of documents returned.
QUERY_TARGETING_SCANNED_OBJECTS_PER_RETURNED
Ratio of the number of documents scanned to the number of documents returned.
SYSTEM_CPU_USER
SYSTEM_CPU_KERNEL
SYSTEM_CPU_NICE
SYSTEM_CPU_IOWAIT
SYSTEM_CPU_IRQ
SYSTEM_CPU_SOFTIRQ
SYSTEM_CPU_GUEST
SYSTEM_CPU_STEAL
CPU usage of processes on the host. For hosts with more than one CPU core, this value can exceed 100%.
SYSTEM_NORMALIZED_CPU_USER
SYSTEM_NORMALIZED_CPU_KERNEL
SYSTEM_NORMALIZED_CPU_NICE
SYSTEM_NORMALIZED_CPU_IOWAIT
SYSTEM_NORMALIZED_CPU_IRQ
SYSTEM_NORMALIZED_CPU_SOFTIRQ
SYSTEM_NORMALIZED_CPU_GUEST
SYSTEM_NORMALIZED_CPU_STEAL
CPU usage of processes on the host scaled to a range of 0 to 100% by dividing by the number of CPU cores.
SYSTEM_MEMORY_AVAILABLE
SYSTEM_MEMORY_BUFFERS
SYSTEM_MEMORY_CACHED
SYSTEM_MEMORY_FREE
SYSTEM_MEMORY_SHARED
SYSTEM_MEMORY_USED
Physical memory usage, in bytes, that the host uses.
SYSTEM_NETWORK_BYTES_IN
SYSTEM_NETWORK_BYTES_OUT
Average rate of physical bytes per second that the eth0 network interface received and transmitted.
SWAP_USAGE_USED
SWAP_USAGE_FREE
Total amount of memory that swap uses.
SWAP_IO_IN
SWAP_IO_OUT
Total amount of memory written and read from swap.
FTS_MEMORY_RESIDENT
FTS_MEMORY_VIRTUAL
FTS_MEMORY_MAPPED
Memory usage, in bytes, that Atlas Search processes use.
FTS_DISK_UTILIZATION
Disk space, in bytes, that Atlas Search indexes use.
FTS_PROCESS_CPU_USER
FTS_PROCESS_CPU_KERNEL
FTS_PROCESS_NORMALIZED_CPU_USER
FTS_PROCESS_NORMALIZED_CPU_KERNEL
Percentage of CPU that Atlas Search processes use.

The following example request sets a granularity and period of one minute. Replace the information in brackets {} with your own Atlas information to execute this example request:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --header "Content-Type: application/json" \
     --include \
     --request GET "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/processes/{HOST}:{PORT}/measurements?granularity=PT1M&period=PT1M&pretty=true"
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=ISO-8859-1
Date: {dateInUnixFormat}
WWW-Authenticate: Digest realm="MMS Public API", domain="", nonce="{nonce}", algorithm=MD5, op="auth", stale=false
Content-Length: {requestLengthInBytes}
Connection: keep-alive
HTTP/1.1 200 OK
Vary: Accept-Encoding
Content-Type: application/json
Strict-Transport-Security: max-age=300
Date: {dateInUnixFormat}
Connection: keep-alive
Content-Length: {requestLengthInBytes}

Response Body

1{
2  "end" : "2021-04-09T20:31:14Z",
3  "granularity" : "PT1M",
4  "groupId" : "{GROUP-ID}",
5  "hostId" : "shard-00-00.mongodb.net:27017",
6  "links":[],
7  "measurements" : [
8    {
9      "dataPoints": [
10        {
11          "timestamp": "2021-04-09T10:06:15Z",
12          "value": 0.0
13        }
14      ],
15      "name": "QUERY_EXECUTOR_SCANNED",
16      "units": "SCALAR_PER_SECOND"
17    },{
18      "dataPoints": [
19        {
20          "timestamp": "2021-04-09T10:06:15Z",
21          "value": 6.866666666666666
22        }
23      ],
24      "name": "QUERY_EXECUTOR_SCANNED_OBJECTS",
25      "units": "SCALAR_PER_SECOND"
26    },{
27      "dataPoints": [
28        {
29          "timestamp": "2021-04-09T10:06:15Z",
30          "value": 0.0
31        }
32      ],
33      "name": "QUERY_TARGETING_SCANNED_PER_RETURNED",
34      "units": "SCALAR"
35    },{
36      "dataPoints": [
37        {
38          "timestamp": "2021-04-09T10:06:15Z",
39          "value": 1.0147783251231526
40        }
41      ],
42      "name": "QUERY_TARGETING_SCANNED_OBJECTS_PER_RETURNED",
43      "units": "SCALAR"
44    }
45  ],
46  "processId" : "shard-00-00.mongodb.net:27017",
47  "start" : "2021-04-09T20:30:45Z"
48}

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.

Give Feedback