Begin Monitoring One Host

On this page

Resource

Request Path Parameters
Request Query Parameters
Request Body Parameters
Response
Example Request
Example Response
Response Header
Response Body

Cloud Manager will no longer support Automation, Backup, and Monitoring for MongoDB 3.6 and 4.0 after August 30th, 2024. Please upgrade your MongoDB deployment or migrate to Atlas.

OAuth 2.0 authentication for programmatic access to Cloud Manager is available as a Preview feature.: The feature and the corresponding documentation might change at any time during the Preview period. To use OAuth 2.0 authentication, create a service account to use in your requests to the Cloud Manager Public API.

Note

Groups and projects are synonymous terms. Your {PROJECT-ID} is the same as your project id. For existing groups, your group/project id remains the same. This page uses the more familiar term group when referring to descriptions. The endpoint remains as stated in the document.

Start monitoring a new MongoDB process. The Monitoring starts monitoring the MongoDB process on the hostname and port you specify. Cloud Manager knows only the information that you provide. The response document includes blank values until Cloud Manager completes discovery of the MongoDB processes configuration.

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

Resource

POST /groups/{PROJECT-ID}/hosts

Request Path Parameters

Parameter	Type	Necessity	Description
PROJECT-ID	string	Required	Unique identifier of the project that owns this MongoDB process.

Request Query Parameters

The following query parameters are optional:

Name

Type

Necessity

Description

Default

pretty

boolean

Optional

Flag indicating whether the response body should be in a prettyprint format.

false

envelope

boolean

Optional

Flag that indicates whether or not to wrap 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.

For endpoints that return one result, the response body includes:

Name	Description
`status`	HTTP response code
`content`	Expected response body

false

Request Body Parameters

Name	Type	Necessity	Description
alertsEnabled	boolean	Optional	Set to `true` if alerts should be enabled for this MongoDB process.
authMechanismName	string	Optional	Specify which authentication mechanism should be used to connect to this MongoDB process. Possible values are: `MONGODB_CR` (This covers SCRAM-SHA-1, SCRAM-SHA-256, and MONGODB-CR.) `GSSAPI` `PLAIN` `MONGODB_X509` `NONE`
hostname	string	Required	Set the primary hostname Cloud Manager should use to connect to this MongoDB instance.
logsEnabled	boolean	Optional	Set to `true` if Cloud Manager should collect logs for this MongoDB process.
password	string	Optional	Password associated with `username` for connecting to this MongoDB process. Set this parameter if `"authMechanismName" : "MONGODB_CR"` Cloud Manager doesn't include this parameter in any Host \|\| response.
port	number	Required	Port on which MongoDB process listens.
profilerEnabled	boolean	Optional	Flag indicating whether Cloud Manager collects profile information from this MongoDB process.
sslEnabled	boolean	Conditional	Flag indicating whether TLS should be enabled for this MongoDB process. Set to `true` if `"authMechanismName" : "MONGODB_X509"`.
username	string	Conditional	Username needed to connect to this MongoDB process. Required if `"authMechanismName" : "MONGODB_CR"`

Response

Name	Type	Description
aliases	array of strings	Array of alternate hostname and port combinations that Cloud Manager discovered for the MongoDB process. These combinations can include hostnames, FQDNs, IPv4 addresses, and IPv6 addresses.
alertsEnabled	boolean	`true` if this MongoDB process has alerts enabled.
authMechanismName	string	Authentication mechanism used to connect to this MongoDB process. This displays only one of the following values: `MONGODB_CR` (This covers SCRAM-SHA-1, SCRAM-SHA-256, and MONGODB-CR.) `GSSAPI` `PLAIN` `MONGODB_X509` `NONE`
clusterId	string	Unique identifier of the cluster to which the MongoDB process belongs.
created	date	Date Cloud Manager created or first discovered this MongoDB process.
groupId	string	Unique identifier of the group that owns this host.
hasStartupWarnings	boolean	`true` if this MongoDB process had startup warnings.
hidden	boolean	`true` if host is displayed in the Cloud Manager UI. Hosts set to `true` are omitted from API responses.
hiddenSecondary	boolean	`true` if this host is a hidden secondary.
hostEnabled	boolean	`true` if the MongoDB process currently enabled.
hostname	string	Primary hostname as Cloud Manager can best determine. This can be a hostname, an FQDN, an IPv4 address, or an IPv6 address.
id	string	Unique identifier.
ipAddress	string	IPv4 or IPv6 address associated with the `hostname` of this MongoDB process. Additional accessible IPv4 or IPv6 addresses may be displayed in the `aliases` array.
journalingEnabled	boolean	`true` if journaling is enabled for this MongoDB process.
lastDataSizeBytes	number	Uncompressed size of the host's databases on disk in bytes excluding indexes. `lastDataSizeBytes` does not include the data in the local database.
lastIndexSizeBytes	number	Uncompressed size of the host's database indexes on disk in bytes. This number does not include the size of the index for the local database.
lastPing	date	Timestamp in ISO 8601 date and time format in UTC when the last ping for this MongoDB process was received.
lastRestart	date	Timestamp in ISO 8601 date and time format in UTC when this process last restarted. If the MongoDB process has never been restarted, the `lastRestart` field is omitted.
links	array	Array that includes one or more links to sub-resources and/or related resources. The relations between URLs are explained in the Web Linking Specification. At minimum, a `links` array contains one link called `self`.
logsEnabled	boolean	`true` if Cloud Manager is collecting logs for this MongoDB process.
lowUlimit	boolean	`true` if this MongoDB process's host has a low `ulimit` setting.
port	number	Port on which the MongoDB process listens.
profilerEnabled	boolean	`true` if Cloud Manager collects profile information from this MongoDB process.
replicaSetName	string	Name of the replica set this process belongs to. Only present if this process is part of a replica set.
replicaStateName	string	Current state of this MongoDB process within a replica set. Only present if this process is part of a replica set. See Replica Set Member States for possible values.
shardName	string	Name of the shard to which this process belongs. Only present if the process is part of a sharded cluster.
secondaryDelaySecs	number	Number of seconds this replica set member's data trails the primary. If this value is set to `0`, the member is not configured as a delayed member. For additional details on secondary delays, see Delayed Replica Set Members
sslEnabled	boolean	`true` if TLS/SSL and is enabled for this MongoDB process.
systemInfo	object	Object that contains RAM and CPU information for this MongoDB process' server as reported by the operating system or container.
systemInfo.memSizeMB	number	Amount of RAM in megabytes.
systemInfo.numCores	number	Number of CPU cores.
typeName	string	Type for this MongoDB process. Possible values are: `STANDALONE` `REPLICA_PRIMARY` `REPLICA_SECONDARY` `REPLICA_ARBITER` `RECOVERING` `SHARD_MONGOS` `SHARD_CONFIG` `SHARD_STANDALONE` `SHARD_PRIMARY` `SHARD_SECONDARY` `NO_DATA` The type for new hosts added to Cloud Manager will be `NO_DATA` until the Monitoring receives its first ping.
uptimeMsec	number	Number of milliseconds since this process last restarted.
version	string	Version of MongoDB running for this process.

Example Request

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     --include \
     --request POST "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/hosts?pretty=true" \
     --data '
       {
         "hostname": "server1.example.com",
         "port": 27017
       }'

Example Response

Response Header

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 201 Created
Vary: Accept-Encoding
Content-Type: application/json
Strict-Transport-Security: max-age=300
Date: {dateInUnixFormat}
Connection: keep-alive
Content-Length: {requestLengthInBytes}
X-MongoDB-Service-Version: gitHash={gitHash}; versionString={ApplicationVersion}

Response Body

1 {
2   "alertsEnabled" : true,
3   "authMechanismName" : "NONE",
4   "created" : "2014-04-22T19:56:50Z",
5   "groupId" : "{PROJECT-ID}",
6   "hasStartupWarnings" : false,
7   "hidden" : false,
8   "hostEnabled" : true,
9   "hostname" : "server1.example.com",
10   "id" : "{HOST-ID}",
11   "journalingEnabled" : false,
12   "links" : [  ],
13   "logsEnabled" : false,
14   "lowUlimit" : false,
15   "port" : 27017,
16   "profilerEnabled" : false,
17   "sslEnabled" : false
18   "systemInfo" : {
19     "memSizeMB" : 65536,
20     "numCores" : 16
21   },
22 }

Back

Get by Hostname & Port

Update

1	{
2	"alertsEnabled" : true,
3	"authMechanismName" : "NONE",
4	"created" : "2014-04-22T19:56:50Z",
5	"groupId" : "{PROJECT-ID}",
6	"hasStartupWarnings" : false,
7	"hidden" : false,
8	"hostEnabled" : true,
9	"hostname" : "server1.example.com",
10	"id" : "{HOST-ID}",
11	"journalingEnabled" : false,
12	"links" : [ ],
13	"logsEnabled" : false,
14	"lowUlimit" : false,
15	"port" : 27017,
16	"profilerEnabled" : false,
17	"sslEnabled" : false
18	"systemInfo" : {
19	"memSizeMB" : 65536,
20	"numCores" : 16
21	},
22	}