This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

    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.

    Remember! Never edit dragent.default.yaml directly; always edit only dragent.yaml.

    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:

    metric prefixEntry under additional_metrics
    mongodb.collectioncollection
    mongodb.usage.commandstop
    mongodb.usage.getmoretop
    mongodb.usage.inserttop
    mongodb.usage.queriestop
    mongodb.usage.readLocktop
    mongodb.usage.writeLocktop
    mongodb.usage.removetop
    mongodb.usage.totaltop
    mongodb.usage.updatetop
    mongodb.usage.writeLocktop
    mongodb.tcmalloctcmalloc
    mongodb.metrics.commandsmetrics.commands

    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

    Parameters

    Description

    ssl_certfile

    The certificate file that is used to identify the local connection with MongoDB.

    ssl_keyfile

    The private keyfile that is used to identify the local connection with MongoDB. Ignore this option if the key is included with ssl_certfile.

    ssl_cert_reqs

    Specifies whether a certificate is required from the MongoDB server, and whether it will be validated if provided. Possible values are:

    • 0 for ssl.CERT_NONE. Implies certificates are ignored.

    • 1 for ssl.CERT_OPTIONAL. Implies certificates are not required, but validated if provided.

    • 2 for ssl.CERT_REQUIRED. Implies certificates are required and validated.

    ssl_ca_certs

    The ca_certs file contains a set of concatenated certification authority certificates, which are used to validate certificates used by MongoDB server. Mostly used when server certificates are self-signed.

    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