MongoDB¶
How to set up PMM to monitor a MongoDB or Percona Server for MongoDB database instance.
Before you start¶
Check that:
- PMM Server is installed and running with a known IP address or hostname accessible from the client node.
- PMM Client is installed and the node is registered with PMM Server.
- You have superuser (root) access on the client host.
- You have
adminUserAnyDatabase
or superuser role privilege to any database servers that you want to monitor. - Your MongoDB server is version 4.0 or higher.
Create PMM account and set permissions¶
We recommend using a dedicated account to connect PMM Client to the monitored database instance.
Run the example codes below in a mongo
session to:
- create custom roles with the privileges required for creating/restoring backups and working with Query Analytics (QAN)
- create/update a database user with these roles above, plus the built-in
clusterMonitor
role
Values for username (user
) and password (pwd
) are examples. Replace them before using these code snippets.
db.getSiblingDB("admin").createRole({
role: "explainRole",
privileges: [{
resource: {
db: "",
collection: ""
},
actions: [
"listIndexes",
"listCollections",
"dbStats",
"dbHash",
"collStats",
"find"
]
}],
roles:[]
})
db.getSiblingDB("admin").createRole({ "role": "pbmAnyAction",
"privileges": [
{ "resource": { "anyResource": true },
"actions": [ "anyAction" ]
}
],
"roles": []
});
db.getSiblingDB("admin").createUser({
user: "pmm",
pwd: "pmm",
roles: [
{ role: "explainRole", db: "admin" },
{ role: "clusterMonitor", db: "admin" },
{ role: "read", db: "local" },
{ "db" : "admin", "role" : "readWrite", "collection": "" },
{ "db" : "admin", "role" : "backup" },
{ "db" : "admin", "role" : "clusterMonitor" },
{ "db" : "admin", "role" : "restore" },
{ "db" : "admin", "role" : "pbmAnyAction" }
]
})
db.getSiblingDB("admin").updateUser("pmm", {
roles: [
{ role: "explainRole", db: "admin" },
{ role: "clusterMonitor", db: "admin" },
{ role: "read", db: "local" },
{ "db" : "admin", "role" : "readWrite", "collection": "" },
{ "db" : "admin", "role" : "backup" },
{ "db" : "admin", "role" : "clusterMonitor" },
{ "db" : "admin", "role" : "restore" },
{ "db" : "admin", "role" : "pbmAnyAction" }
]
})
Permissions for advanced metrics¶
To fetch advanced metrics, use the following to provide additional privileges to an existing PMM user:
{
resource : {
db : "",
collection : "system.profile"
},
actions : [
"collStats",
"dbStats",
"indexStats"
]
}
If the role explainRole
already exists, then you can use the following command to provide additional privileges:
{
db.runCommand( {
grantPrivilegesToRole: "explainRole",
privileges: [ { "resource" : { "db" : "", "collection" : "system.profile" }, "actions" : [ "indexStats", "dbStats", "collStats" ] } ] } )
Profiling¶
To use PMM Query Analytics, you must turn on MongoDB’s profiling feature.
You can set profiling:
- permanently, by editing the MongoDB configuration file and restarting the database instance (recommended);
- when starting MongoDB, by passing arguments to
mongod
on the command line; - until the next database instance restart, by running a command in a
mongo
session.
Profiling is turned off by default as it can adversely affect the performance of the database server.
Set profiling in the configuration file¶
-
Edit the configuration file (usually
/etc/mongod.conf
). -
Create or add this to the
operationProfiling
section. (Read more.)operationProfiling: mode: all slowOpThresholdMs: 200 rateLimit: 100 # (Only available with Percona Server for MongoDB.)
Important
This is a YAML file. Indentation matters.
-
Restart the
mongod
service. (Example forsystemd
.)systemctl restart mongod
Set profiling on the command Line¶
mongod --dbpath=DATABASEDIR --profile 2 --slowms 200 --rateLimit 100
--dbpath
: The path to database files (usually/var/lib/mongo
).--profile
: The MongoDB profiling level. A value of2
tells the server to collect profiling data for all operations. To lower the load on the server, use a value of1
to only record slow operations.--slowms
: An operation is classified as slow if it runs for longer than this number of milliseconds.-
--rateLimit
: (Only available with Percona Server for MongoDB.) The sample rate of profiled queries. A value of100
means sample every 100th fast query. (Read more.)Caution
Smaller values improve accuracy but can adversly affect the performance of your server.
Set profiling in a mongo
session¶
In a mongo
session, the profiler should be enabled per database.
For example, to enable the profiler in the testdb
, run this:
use testdb
db.setProfilingLevel(2, {slowms: 0})
If you have already added a service, you should remove it and re-add it after changing the profiling level.
Add service¶
When you have configured your database server, you can add a MongoDB service with the user interface or on the command line.
With the user interface¶
-
Select Configuration → PMM Inventory → Add Instance.
-
Select MongoDB – Add a remote instance.
-
Enter or select values for the fields.
-
Click Add service.
On the command line¶
Use pmm-admin
to add the database server as a service using one of these example commands.
When successful, PMM Client will print MongoDB Service added
with the service’s ID and name. Use the --environment
and -custom-labels
options to set tags for the service to help identify them.
Tips
- When adding nodes of a sharded cluster, add each node separately using the
--cluster mycluster
option for the MongoDB Cluster Summary dashboard to populate correctly. - Atlas doesn’t support direct connections. When connecting to an Atlas instance, use the
pmm-admin
option--direct-connection=false
. (Doing so will prevent replicaset status from working and the MongoDB Overview dashboard widget will show invalid values.)
Examples¶
pmm-admin add mongodb \
--username=pmm_mongodb --password=password \
--query-source=profiler --cluster=mycluster
pmm-admin add mongodb \
--username=pmm_mongodb --password=password \
mongo 127.0.0.1:27017
pmm-admin add mongodb \
--username=pmm_mongodb --password=password \
--service-name=mymongosvc --host=127.0.0.1 --port=27017
Connect via UNIX socket¶
pmm-admin add mongodb --socket=/tmp/mongodb-27017.sock
Connecting via SSL/TLS¶
pmm-admin add mongodb --tls \
--tls-certificate-key-file=PATHTOCER \
--tls-certificate-key-file-password=IFPASSWORDTOCERTISSET \
--tls-ca-file=PATHTOCACERT
--authentication-mechanism=AUTHENTICATION-MECHANISM
--authentication-database=AUTHENTICATION-DATABASE
where:
PATHTOCERT
: Path to TLS certificate file.IFPASSWORDTOCERTISSET
: Password for TLS certificate file.PATHTOCACERT
: Path to certificate authority file.AUTHENTICATION-MECHANISM
: Authentication mechanism. Default is empty. UseMONGODB-X509
for SSL certificates.AUTHENTICATION-DATABASE
: Authentication database. Default is empty. Use$external
for SSL certificates.
Check the service¶
With the user interface¶
- Select Configuration → PMM Inventory → Inventory list.
- Look in the Services tab for a matching Service Type (MongoDB), Service name, Addresses, and any other values used when adding the service.
- Look in the Agents tab to check the desired data source is being used.
- If your MongoDB instance is configured to use TLS, click on the Use TLS for database connection check box and fill in TLS certificates and keys.
- If you use TLS, the authentication mechanism is automatically set to
MONGODB-X509
.
- If you use TLS, the authentication mechanism is automatically set to
On the command line¶
Look for your service in the output of this command.
pmm-admin inventory list services --service-type=mongodb
Check data¶
- Open the MongoDB Instances Overview dashboard.
- Set the Service Name to the newly-added service.
Query Analytics¶
- Open PMM Query Analytics.
- In the Filters panel:
- Under Service Name, select your service.
- Under Service Type select
mongodb
.
Remove service¶
With the user interface¶
- Select Configuration → PMM Inventory → Inventory List.
- In the first column, click the tick box for the service you want to remove.
- Click Delete.
- On the Confirm action dialog window:
- (Optional) Select Force mode to also delete associated agents.
- Click Proceed.
On the command line¶
pmm-admin remove mongodb SERVICE_NAME
SERVICE_NAME
: The name the service was added as. (Find it withpmm-admin list
.)