This is one stop global knowledge base where you can learn about all the products, solutions and support features.
On this page
Note
This feature is available only with Cloud Manager Premium, which comes with certain MongoDB subscriptions. Contact MongoDB for more information.
The Performance Advisor monitors any operation with a query predicate that MongoDB considers slow and suggests new indexes to improve query performance. For the selected host and time period, the Performance Advisor evaluates up to the 20,000 most recent slow queries found in the logs.
Recommended indexes are accompanied by sample queries, grouped by query shape , that were run against a collection that would benefit from the suggested index. The Performance Advisor does not negatively affect the performance of your Cloud Manager clusters.
Note
To view the Performance Advisor, you must:
Run MongoDB version 3.2 or later on your cluster.
Manage your cluster with MongoDB Agent Automation.
To learn more about the MongoDB Agent, see MongoDB Agent .
To view the field values in the example queries, you must be a Cloud Manager user with one or more of the following roles:
Project
Owner
Project
Data
Access
Admin
Project
Data
Access
Read/Write
Project
Data
Access
Read
Only
Users without the aforementioned roles cannot see the field values.
Required Privileges
To enable
Performance Advisor
for a project, you must
have the
Project
Owner
role for the project.
Performance Advisor is enabled by default. To disable or enable Performance Advisor:
If a query is slow, common reasons include:
Indexes improve read performance, but a large number of indexes can negatively impact write performance since indexes must be updated during writes. If your collection already has several indexes, consider this tradeoff of read and write performance when deciding whether to create new indexes. Examine whether a query for such a collection can be modified to take advantage of existing indexes, as well as whether a query occurs often enough to justify the cost of a new index.
The Performance Advisor can help identify and remove unnecessary indexes. To learn more, see Review Drop Index Recommendations .
To access the Performance Advisor :
If the replica set resides in a sharded cluster, first click the sharded cluster containing the replica set.
The Performance Advisor displays up to 20 query shapes across all collections in the cluster and suggested indexes for those shapes. The Performance Advisor ranks the indexes according to their Impact , which indicates High or Medium based on the total wasted bytes read. To learn more about index ranking, see Review Index Ranking .
Note
If the slow query log contains consecutive
$match
stages
in the aggregation pipeline, the two stages can coalesce
into the first
$match
stage and result in a single
$match
stage. As a result, the query shape in the
Performance Advisor might differ from the actual query you ran.
The Performance Advisor ranks the indexes that it suggests according to their Impact , which indicates High or Medium based on the total wasted bytes read. To learn more about how the Performance Advisor ranks indexes, see Review Index Ranking .
To learn how to create indexes that the Performance Advisor suggests, see Create Suggested Indexes .
Each index that the Performance Advisor suggests contains the following metrics. These metrics apply specifically to queries which would be improved by the index:
| Metric | Description |
|---|---|
| Execution Count | Number of queries executed per hour which would be improved. |
| Average Execution Time | Current average execution time in milliseconds for affected queries. |
| Average Query Targeting | Average number of documents read per document returned by affected queries. A higher query targeting score indicates a greater degree of inefficiency. For more information on query targeting, see Query Targeting . |
| In Memory Sort | Current number of affected queries per hour that needed to be sorted in memory. |
| Average Docs Scanned | Average number of documents scanned. |
| Average Docs Returned | Average number of documents returned. |
| Avgerage Object Size | Average object size. |
For each suggested index, the Performance Advisor shows the most commonly executed query shapes that the index would improve. For each query shape, the Performance Advisor displays the following metrics:
| Metric | Description |
|---|---|
| Execution Count | Number of queries executed per hour which match the query shape. |
| Average Execution Time | Average execution time in milliseconds for queries which match the query shape. |
| Average Query Targeting | Average number of documents read for every document returned by matching queries. A higher query targeting score indicates a greater degree of inefficiency. For more information on query targeting, see Query Targeting . |
| Average Docs Scanned | Average number of documents scanned. |
| Average Docs Returned | Average number of documents returned. |
The Performance Advisor also shows each executed sample query that matches the query shape, with specific metrics for that query.
Each index suggestion includes an Average Query Targeting score indicating how many documents were read for every document returned for the index’s corresponding query shapes. A score of 1 represents very efficient query shapes because every document read matched the query and was returned with the query results. All suggested indexes represent an opportunity to improve query performance.
By default, the Performance Advisor suggests indexes for all clusters in the deployment. To only show suggested indexes from a specific collection, use the Collection dropdown at the top of the Performance Advisor.
You can also adjust the time range the Performance Advisor takes into account when suggesting indexes by using the Time Range dropdown at the top of the Performance Advisor.
The Performance Advisor can’t suggest indexes for MongoDB databases configured to use the ctime timestamp format. As a workaround, set the timestamp format for such databases to either iso8601-utc or iso8601-local.
The Performance Advisor analyzes up to 200,000 of your cluster’s most recent log lines.
You can create indexes suggested by the Performance Advisor directly within the Performance Advisor itself. When you create indexes, keep the ratio of reads to writes on the target collection in mind. Indexes come with a performance cost, but are more than worth the cost for frequent queries on large data sets. To learn more about indexing strategies, see Indexing Strategies.
To create a suggested index:
The Performance Advisor opens the Create Index dialog and prepopulates the Fields based on the index you selected.
{ <option1>: <value1>, ... }
Example
The following options document specifies the
unique
option and
the
name
for the index:
{ unique: true, name: "myUniqueIndex" }
Use collation to specify language-specific rules for string comparison,
such as rules for lettercase and accent marks. The
collation document
contains a
locale
field which indicates the ICU Locale code, and may contain other
fields to define collation behavior.
Example
The following collation option document specifies a locale value
of
fr
for a French language collation:
{ "locale": "fr" }
To review the list of locales that MongoDB collation supports, see the list of languages and locales . To learn more about collation options, including which are enabled by default for each locale, see Collation in the MongoDB manual.
Warning
Due to critical issue SERVER-68925, Cloud Manager deployments using certain versions of the MongoDB Agent should not perform automated rolling index builds on clusters running the following MongoDB versions:
You can continue to perform manual rolling index builds safely on your clusters. To perform automated rolling index builds safely, upgrade the MongoDB Agent to 12.4.0.7703 or later or upgrade your clusters to:
Important
Rolling index builds succeed only when they meet certain conditions. To ensure your index build succeeds, avoid the following design patterns that commonly trigger a restart loop:
Note
Data Explorer doesn’t support building indexes in a rolling fashion for standalone deployments.
Building indexes in a rolling fashion reduces the performance impact of building indexes on replica sets and sharded clusters . To maintain cluster availability, Cloud Manager removes one node from the cluster at a time starting with a secondary .
After you build an index in a rolling fashion, if your MongoDB database
runs with an FCV
less than
4.2
,
resync the head database
to ensure that the head database takes the
new index into account.
Cloud Manager automatically cancels rolling index builds that don’t succeed on all nodes. When a rolling index build completes on some nodes, but fails on others, Cloud Manager cancels the build and removes the index from any nodes that it was successfully built on.
In the event of a rolling index build cancellation, Cloud Manager generates an activity feed event and sends a notification email to the project owner with the following information:
To learn more about rebuilding indexes, see Build Indexes on Replica Sets .
Note
The following index options are incompatible with building indexes in a rolling fashion:
Cloud Manager ignores these options if you specify them in the Options pane.
Important
When an index build completes, Cloud Manager generates an activity feed event and sends a notification email to the project owner with the following information:
This document addresses common questions about Cloud Manager and its use.
On this page
Cloud Manager can automate operations for the MongoDB processes running on your hosts. Cloud Manager can both discover existing processes and deploy new ones.
Cloud Manager Automation relies on an Automation Agent, which must be installed on every server that runs a monitored MongoDB deployment. The Automation Agents periodically poll Cloud Manager to determine the goal configuration, deploy changes as needed, and report deployment status back to Cloud Manager.
Install the MongoDB Agent on each host that you want Cloud Manager to manage. The following procedure applies to all operating systems.
Instructions for a specific operating system can be read on Install MongoDB Agent .
On Linux hosts, if you installed MongoDB with a package manager, use the same package manager to install the MongoDB Agent. If you installed MongoDB without a package manager, use an archive to install the MongoDB Agent.
Once you have installed the MongoDB Agent to all your hosts, you can deploy your first replica set , cluster , or standalone .
On this page
new
Groups are now projects.
In Cloud Manager, MongoDB deployments are associated with projects.
You can create multiple projects in an organization. Each project has its own Monitoring, Backup and Automations associated with the project.
Projects within the same organization share the same billing settings.
For a project, the Monitoring must be able to connect to all hosts it monitors. If you have multiple MongoDB deployments in distinct environments and cannot monitor all deployments with a single agent (for instance, if your environments are separated by firewalls), you will need to add new projects.
You can also use multiple projects and agents if you want to separately monitor different MongoDB deployments that run in the same environment.
Important
Organization
Owner
or an
Organization
Project
Creator
.
Project
Owner
of the project.
You can also expand the Projects menu in the navigation bar, then click + New Project .
To learn more about MongoDB Atlas, see https://www.mongodb.com/cloud.
If you selected an MongoDB Atlas project, enter a name for the Organization .
If managing Cloud Manager users through LDAP , enter values for the following Optional LDAP Configuration fields .
Important
Multiple LDAP Groups Can Map to One Role
Cloud Manager roles can include more than one LDAP group. Type
multiple LDAP group names in the relevant role fields separated
by two semicolons (
;;
).
| Field | Action |
|---|---|
| LDAP Groups for Project Owner Role |
Type the LDAP group(s) to which the Project Owners of the
Cloud Manager project belong. You can type multiple LDAP groups into
this field if they are separated by two semicolons (
;;
).
|
| LDAP Groups for Automation Admin Role |
Type the LDAP group(s) to which Cloud Manager project’s Automation
Administrators belong. You can type multiple LDAP groups
into this field if they are separated by two semicolons
(
;;
).
|
| LDAP Groups for Backup Admin Role |
Type the LDAP group(s) to which Cloud Manager project’s Backup
Administrators belong. You can type multiple LDAP groups
into this field if they are separated by two semicolons
(
;;
).
|
| LDAP Groups for Monitoring Admin Role |
Type the LDAP group(s) to which Cloud Manager project’s Monitoring
Administrators belong. You can type multiple LDAP groups
into this field if they are separated by two semicolons
(
;;
).
|
| LDAP Groups for User Admin Role |
Type the LDAP group(s) to which Cloud Manager project’s User
Administrators belong. You can type multiple LDAP groups
into this field if they are separated by two semicolons
(
;;
).
|
| LDAP Groups for Read Only Role |
Type the LDAP group(s) to which Cloud Manager project’s Read Only
Users belong. You can type multiple LDAP groups into this
field if they are separated by two semicolons (
;;
).
|
For existing Cloud Manager users, enter their username. Usually, this is the email the person used to register.
For new Cloud Manager users, enter their email address to send an invitation.
Important
Deleting a project removes all the project’s artifacts, including all monitoring data. Cloud Manager no longer displays the project in selection lists.
You can delete a project if:
Project
Owner
access for the project.
Click the trash icon button for the project you wish to delete to open the Delete Project modal.
| Agent | Procedure |
|---|---|
| Automations | Stop the agent’s process on each server. |
| Monitoring | See Stop the Monitoring Agent and Remove Monitoring Agents from Cloud Manager . |
| Backup | See Stop the Backup Agent and Remove the Backup Agent from Cloud Manager . |
Use the following procedures to modify projects:
Base URL:
https://cloud.mongodb.com/api/public/v1.0
POST /users/{USER-ID}/whitelist
| Parameter | Type | Description |
|---|---|---|
| USER-ID | string | (Required.) Unique identifier of the current user. To retrieve the ID of the current user, see Get All Users in One Project . |
The following query parameters are optional:
| Name | Type | Necessity | Description | Default |
|---|---|---|---|---|
| pageNum | number | Optional | One-based integer that returns a subsection of results. |
1
|
| itemsPerPage | number | Optional | Number of items to return per page, up to a maximum of 500. |
100
|
| pretty | boolean | Optional | Flag that indicates 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
For endpoints that return a list of results, the
|
false
|
The request body must be an array of whitelist entities, even if there is only one. The only field that you need to specify for each request object is the IP-ADDRESS .
If an IP address is already in the whitelist, it will be ignored.
If you specify a single IP address with the
/32
subnet mask, Cloud Manager
does not store the
/32
, as the
/32
does not change the address.
Example
An address of
12.34.56.78
is the same as
12.34.56.78/32
.
| Parameter | Type | Description |
|---|---|---|
| ipAddress | string | (Required.) The IP address or CIDR block that you want to add to the specified user’s whitelist. |
The response JSON document includes an array of result objects, an array of link objects and a count of the total number of result objects retrieved.
| Name | Type | Description |
|---|---|---|
results
|
array | Array includes one object for each item detailed in the results Embedded Document section. |
links
|
array | Array includes one or more links to sub-resources and/or related resources. The relations between URL s are explained in the Web Linking Specification . |
totalCount
|
number | Integer count of the total number of items in the result set. It may be greater than the number of objects in the results array if the entire result set is paginated. |
Each result is one whitelist.
| Name | Type | Description |
|---|---|---|
cidrBlock
|
string | A CIDR-notated range of IP addresses. |
created
|
date | The date this IP address was added to the whitelist. |
ipAddress
|
string | A whitelisted IP address. |
lastUsed
|
date | The date of the most recent request that originated from this IP address. Note that this field is only updated when a whitelisted resource is accessed. |
lastUsedAddress
|
string | The address from which the last call to the API was issued. |
count
|
number | The total number of requests that originated from this IP address. Note that this field is only updated when a resource that is protected by the whitelist is accessed. |
links
|
array |
Links to related sub-resources. All links arrays in responses
contain at least one link called
self
. The relations between
URLs are explained in the Web Linking Specification.
|
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/users/{USER-ID}/whitelist" --data '
[
{
"ipAddress" : "192.0.1.15",
"comment" : "IP address for Application Server A"
},
{
"cidrBlock" : "192.0.2.0/24",
"comment" : "CIDR block for Application Server B - D"
}
]'
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}
{
"totalCount" : 3,
"results" : [ {
"cidrBlock" : "12.34.56.78/32",
"ipAddress" : "12.34.56.78",
"created" : "2014-04-23T16:17:44Z",
"lastUsed" : "2016-08-17T19:34:05Z",
"lastUsedAddress" : "12.34.56.78",
"count" : 0,
"links" : []
}, {
"cidrBlock" : "76.54.32.10/32",
"ipAddress" : "76.54.32.10",
"created" : "2016-08-17T19:34:05Z",
"count" : 0,
"links" : []
}, {
"cidrBlock" : "2.3.4.5/32",
"ipAddress" : "2.3.4.5",
"created" : "2016-08-17T19:34:05Z",
"count" : 0,
"links" : []
} ],
"links" : []
}
On this page
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.
Base URL:
https://cloud.mongodb.com/api/public/v1.0
GET /groups/byName/{GROUP-NAME}
| Name | Type | Description |
|---|---|---|
| GROUP-NAME | string | (Required.) The name of the project. |
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:
|
false
|
This endpoint doesn’t use HTTP request body parameters.
| Name | Type | Description |
|---|---|---|
| activeAgentCount | integer |
Number of active agents sending regular pings to Cloud Manager.
The value is refreshed about every 24 hours and cached. If
you start a new agent or stop an existing one, the change
can take up to 30 minutes to show up in the
|
| hostCounts | object | Total number of hosts by type. The embedded fields should be self-explanatory. |
| id | string | Unique identifier for the group. |
| lastActiveAgent | string |
Time Cloud Manager last updated the
activeAgentCount
total for
the project. Cloud Manager refreshes this value every 24 hours and
caches it to record the number of active MongoDB Agents.
|
| links | object array |
One or more links to sub-resources and/or related resources. All
links
arrays in responses include at least one link called
self
. The relationships between
URL
s are explained in the
Web Linking Specification
.
|
| name | string | Display name for the project. |
| orgId | string | Unique identifier for the organization to which the project belongs. |
| publicApiEnabled | boolean |
Flag indicating that the
API
is enabled for this project.
This is a read-only field that is always
true
.
|
| replicaSetCount | integer | Total number of replica sets for this project. |
| shardCount | integer | Total number of shards for this project. |
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--include \
--request GET "https://cloud.mongodb.com/api/public/v1.0/groups/byName/{GROUP-NAME}?pretty=true"
Important
Some characters are not allowed in URLs. These are called
reserved characters.
If your
{GROUP-NAME}
includes reserved characters, like spaces,
you must replace them with their
percent encoding.
Example
Instead of making this request (via curl):
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/json" \
--include \
--request GET "https://cloud.mongodb.com/api/public/v1.0/groups/byName/My%20Project?pretty=true"
Make this request (via curl):
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/json" \
--include \
--request GET "https://cloud.mongodb.com/api/public/v1.0/groups/byName/My%20Group?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}
X-MongoDB-Service-Version: gitHash={gitHash}; versionString={ApplicationVersion}
{
"activeAgentCount": 1,
"agentApiKey": "{AGENT-API-KEY}",
"hostCounts": {
"arbiter": 2,
"config": 1,
"primary": 4,
"secondary": 8,
"mongos": 2,
"master": 0,
"slave": 0
},
"id": "{PROJECT-ID}",
"lastActiveAgent": ISODate("2016-08-05T07:23:34Z"),
"links" : [],
"name": "My Project",
"orgId" : "111111111cccccf38dc78bdf",
"publicApiEnabled": true,
"replicaSetCount": 3,
"shardCount": 2,
}