MongoDB

MongoDB is an open-source database management system (DBMS) that uses a document-oriented database model that supports various forms of data. If MongoDB is installed in your environment, the Sysdig agent will automatically connect and collect basic metrics (if authentication is not used). You may need to edit the default entries to connect and collect additional metrics. See the Default Configuration section, below.

This page describes the default configuration settings, how to edit the configuration to collect additional information, the metrics available for integration, and a sample result in the Sysdig Monitor UI.

MongoDB Setup

Create a read-only user for the Sysdig agent.

# Authenticate as the admin user.
use admin
db.auth("admin", "<YOUR_MONGODB_ADMIN_PASSWORD>")

# On MongoDB 2.x, use the addUser command.
db.addUser("sysdig-cloud", "sysdig-cloud-password", true)

# On MongoDB 3.x or higher, use the createUser command.
db.createUser({
  "user":"sysdig-cloud",
  "pwd": "sysdig-cloud-password",
  "roles" : [
    {role: 'read', db: 'admin' },
    {role: 'clusterMonitor', db: 'admin'},
    {role: 'read', db: 'local' }
  ]
})

Sysdig Agent Configuration

Review how to Edit dragent.yaml to Integrate or Modify Application Checks.

Default Configuration

By default, Sysdig’s dragent.default.yaml uses the following code to connect with MongoDB.

app_checks:
  - name: mongodb
    check_module: mongo
    pattern:
      comm: mongod
    conf:
      server: "mongodb://localhost:{port}/admin"

The default MongoDB entry should work for without modification if authentication is not configured. If you have enabled password authentication, the entry will need to be changed.

Some metrics are not available by default. Additional configuration needs to be provided to collect them as shown in following examples.

Example 1: With Authentication

Replace <username> and <password> with actual username and password.

app_checks:
  - name: mongodb
    check_module: mongo
    pattern:
      comm: mongod
    conf:
      server: mongodb://<username>:<password>@localhost:{port}/admin
      replica_check: true

Example 2: Additional Metrics

Some metrics are not collected by default. These can be collected by adding additional_metrics section in the dragent.yaml file under the app_checks mongodb configuration.

Available options are:

collection - Metrics of the specified collections

metrics.commands - Use of database commands

tcmalloc - TCMalloc memory allocator

top - Usage statistics for each collection

app_checks:
  - name: mongodb
    check_module: mongo
    pattern:
      comm: mongod
    conf:
      server: mongodb://<username>:<password>@localhost:{port}/admin
      replica_check: true
      additional_metrics:
        - collection
        - metrics.commands
        - tcmalloc
        - top

List of metrics with respective entries in dragent.yaml:

Example 3: Collections Metrics

MongoDB stores documents in collections. Collections are analogous to tables in relational databases. The Sysdig agent by default does not collect the following collections metrics:

• collections: List of MongoDB collections to be polled by the agent. Metrics will be collected for the specified set of collections. This configuration requires the additional_metrics.collection section to be present with an entry for collection in the dragent.yaml file. The collection entry under additional_metrics is a flag that enables the collection metrics.

• collections_indexes_stats: Collect indexes access metrics for every index in every collection in the collections list. The default value is false.

  The metric is available starting MongoDB v3.2.

For the agent to poll them, you must configure the dragent.yaml file and add an entry corresponding to the metrics to the conf section as follows.

app_checks:
  - name: mongodb
    check_module: mongo
    pattern:
      comm: mongod
    conf:
      server: mongodb://<username>:<password>@localhost:{port}/admin
      replica_check: true
      additional_metrics:
        - collection
        - metrics.commands
        - tcmalloc
        - top
      collections:
        - <LIST_COLLECTIONS>
      collections_indexes_stats: true

Configure SSL for MongoDB App Check

You can tighten the security measure of the app check connection with MongoDB by establishing an SSL connection. To enable secure communication, you need to set the SSL configuration in dragent.yaml to true. In an advanced deployment with multi-instances of MongoDB, you need to include a custom CA certificate or client certificate and other additional configurations.

Basic SSL Connection

In a basic SSL connection:

• A single MongoDB instance is running on the host.

• An SSL connection with no advanced features, such as the use of a custom CA certificate or client certificate.

To establish a basic SSL connection between the agent and the MongoDB instance:

1. Open the dragent.yaml file.

2. Configure the SSL entries as follows:

   app_checks:
     - name: mongodb
       check_module: mongo
       pattern:
         comm: mongod
       conf:
         server: "mongodb://<HOSTNAME>:{port}/admin"
         ssl: true
         # ssl_cert_reqs: 0    # Disable SSL validation
   

   To disable SSL validation, set ssl_cert_reqs to 0. This setting is equivalent to ssl_cert_reqs=CERT_NONE.

Advanced SSL Connection

In an advanced SSL connection:

• Advanced features, such as custom CA certificate or client certificate, are configured.

• Single or multi-MongoDB instances are running on the host. The agent is installed as one of the following:

  • Container

  • Service

Prerequisites

Set up the following:

• Custom CA certificate

• Client SSL verification

• SSL validation

(Optional ) SSL Configuration Parameters

Sysdig Agent as a Container

1. If Sysdig agent is installed as a container, start it with an extra volume containing the SSL files mentioned in the agent configuration. For example:

   # extra parameter added: -v /etc/ssl:/etc/ssl
   docker run -d --name sysdig-agent --restart always --privileged --net host --pid host -e ACCESS_KEY=xxxxxxxxxxxxx -e SECURE=true -e TAGS=example_tag:example_value -v /var/run/docker.sock:/host/var/run/docker.sock -v /dev:/host/dev -v /proc:/host/proc:ro -v /boot:/host/boot:ro -v /lib/modules:/host/lib/modules:ro -v /usr:/host/usr:ro -v /etc/ssl:/etc/ssl --shm-size=512m sysdig/agent
   

2. Open the dragent.yaml file and configure the SSL entries:

   app_checks:
     - name: mongodb
       check_module: mongo
       pattern:
         comm: mongod
       conf:
         server: "mongodb://<HOSTNAME>:{port}/admin"
         ssl: true
         # ssl_ca_certs: </path/to/ca/certificate>
         # ssl_cert_reqs: 0    # Disable SSL validation
         # ssl_certfile: </path/to/client/certfile>
         # ssl_keyfile: </path/to/client/keyfile>
   

Sysdig Agent as a Process

1. If Sysdig agent is installed as a process, store the SSL files on the host and provide the path in the agent configuration.

   app_checks:
     - name: mongodb
       check_module: mongo
       pattern:
         comm: mongod
       conf:
         server: "mongodb://<HOSTNAME>:{port}/admin"
         ssl: true
         # ssl_ca_certs: </path/to/ca/certificate>
         # ssl_cert_reqs: 0    # Disable SSL validation
         # ssl_certfile: </path/to/client/certfile>
         # ssl_keyfile: </path/to/client/keyfile>
   

   See optional SSL configuration parameters for information on SSL certificate files.

Multi-MongoDB Setup

In a multi-MongoDB setup, multiple MongoDB instances are running on a single host. You can configure either a basic or an advanced SSL connection individually for each MongoDB instance.

Store SSL Files

In an advanced connection, different SSL certificates are used for each instance of MongoDB on the same host and are stored in separate directories. For instance, the SSL files corresponding to two different MongoDB instances can be stored at a mount point as follows:

• Mount point is /etc/ssl/

• Files for instance 1 are stored in  /etc/ssl/mongo1/

• Files for instance 2 are stored in  /etc/ssl/mongo2/

Configure the Agent

1. Open the dragent.yaml file.

2. Configure the SSL entries as follows:

   app_checks:
     - name: mongodb-ssl-1
       check_module: mongo
       pattern:
         comm: mongod
         args: ssl_certificate-1.pem
       conf:
         server: "mongodb://<HOSTNAME|Certificate_CN>:{port}/admin"
         ssl: true
         ssl_ca_certs: /etc/ssl/mongo1/ca-cert-1
         tags:
           - "instance:ssl-1"
   
     - name: mongodb-ssl-2
       check_module: mongo
       pattern:
         comm: mongod
         args: ssl_certificate-2.pem
       conf:
         server: "mongodb://<HOSTNAME|Certificate_CN>:{port}/admin"
         ssl: true
         ssl_ca_certs: /etc/ssl/mongo2/ca-cert-2
         tags:
           - "instance:ssl-2"
   

   Replace the names of the instances and certificate files with the names that you prefer.

Metrics Available

See MongoDB Metrics.

Result in the Monitor UI