AppDynamics Monitoring Extension for use with MongoDB

Use Case

The MongoDB custom monitor captures statistics from the MongoDB server and displays them in the AppDynamics Metric Browser.

This extension works only with the standalone machine agent.

Metrics include:

• Server up time
• Global lock time
• Operations currently queued, number waiting for the read-lock or write-lock
• Total active connections, number of read and write operations
• Memory metrics including bits, resident RAM, virtual memory, mapped memory, mapped memory with journaling
• Current and available connections
• Index counters including index access, hits and misses, resets
• Background flushing metrics such as number of times, total time, average time, last time
• Network traffic sent and received (in bytes), number of distinct requests received
• Number of database operations including: insert, query, update, delete, get more, and total number of commands
• Number of asserts since the server process started: regular, warnings, message, user, and number of times the rollover counter has rolled
• Database related stats
• Cluster related stats (status, health and uptime)

Pre-requisite

Before the extension is installed, the prerequisites mentioned here need to be met. Please do not proceed with the extension installation if the specified prerequisites are not met.

Installation

1. Download and unzip MongoMonitor.zip into <MACHINE_AGENT_HOME>/monitors/
2. Edit the file config.yml located at <MachineAgent_Dir>/monitors/ The metricPrefix of the extension has to be configured as specified here. Please make sure that the right metricPrefix is chosen based on your machine agent deployment, otherwise this could lead to metrics not being visible in the controller.
3. Restart the machineagent
4. In the AppDynamics Metric Browser, look for: Application Infrastructure Performance | <Tier> | Custom Metrics | Mongo Server.

Configuration

Note : Please make sure to not use tab (\t) while editing yaml files. You may want to validate the yaml file using a yaml validator

1. Configure the Mongo instances by editing the config.yml file in <MACHINE_AGENT_HOME>/monitors/MongoMonitor/.

   For eg.

       # MongoDB host and port. If ReplicaSet is enabled, configure all OR subset of members of the cluster.
       servers:
         - host: "localhost"
           port: 27017
         - host: "localhost"
           port: 27018
   
       # Specify this key if Password Encryption Support is required else keep it empty
       # If specified, adminDBPassword and databases passwords are now the encrypted passwords.
       passwordEncryptionKey: ""
   
       # Admin DB username and password. Required if mongod is started with --auth (Authentication) else keep empty
       # The user should have clusterMonitor role as a minimum
       adminDBUsername: "admin"
       adminDBPassword: "admin"
   
       # Change ssl to true if mongod is started with ssl. Then specify the pemFilePath, if not keep empty.
       ssl: false
       pemFilePath: ""
   
       # https://docs.mongodb.com/manual/reference/command/serverStatus/
       serverStatusExcludeMetricFields: [locks, wiredTiger, tcmalloc, opcountersRepl, metrics]
   
       #prefix used to show up metrics in AppDynamics
       metricPathPrefix:  "Custom Metrics|Mongo Server|"
       #This will create it in specific Tier. Replace 
       #metricPrefix:  "Server|Component:|Custom Metrics|Mongo Server|"
   
   

2. Configure the path to the config.yml file by editing the in the monitor.xml file in the <MACHINE_AGENT_HOME>/monitors/MongoMonitor/ directory. Below is the sample

    <task-arguments>
        <!-- config file-->
        <argument name="config-file" is-required="true" default-value="monitors/MongoMonitor/config.yml" />
         ....
    </task-arguments>
   

Note : By default, a Machine agent or a AppServer agent can send a fixed number of metrics to the controller. To change this limit, please follow the instructions mentioned here. For eg.

    java -Dappdynamics.agent.maxMetrics=2500 -jar machineagent.jar

Password Encryption Support

To avoid setting the clear text password in the config.yml, please follow the process below to encrypt the passwords

1. Download the util jar to encrypt the password from https://github.com/Appdynamics/maven-repo/blob/master/releases/com/appdynamics/appd-exts-commons/1.1.2/appd-exts-commons-1.1.2.jar and navigate to the downloaded directory
2. Encrypt password from the commandline java -cp appd-exts-commons-1.1.2.jar com.appdynamics.extensions.crypto.Encryptor myKey myPassword
3. Specify the passwordEncryptionKey and encrypted adminDBPassword in config.yml
4. For every db, use the same encryption key to encrypt the password and specify the encrypted password in config.yml

Metrics

Server Stats

Metric Category: Asserts

Metric Category: Background Flushing

Metric Category: Connections

Metric Category: Global Lock

Active Clients

Current Queue

Metric Category: Index Counter

Metric Category: Memory

Metric Category: Network

Metric Category: Operations

Replica Stats

For each replica the following metrics are reported.

DB Stats

Metric Category: Collection Stats

Troubleshooting

Please look at the troubleshooting document and make sure that everything is followed correctly.

Contributing

Always feel free to fork and contribute any changes directly via GitHub.

Support

For any questions or feature request, please contact help@appdynamics.com.