AppDynamics MongoDB Monitoring Extension

##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

##Installation

1. Run 'ant package' from the mongo-monitoring-extension directory
2. Download the file MongoMonitor.zip found in the 'dist' directory into <machineagent install dir>/monitors/
3. Unzip the downloaded file
4. In the newly created directory "MongoMonitor", edit the monitor.xml configuring the parameters specified below.
5. If there are additional DB to be monitored, add the credentials to properties.xml
6. Restart the machineagent
7. In the AppDynamics Metric Browser, look for: Application Infrastructure Performance | <Tier> | Custom Metrics | Mongo Server | <DB>.

##Rebuilding the Project

1. At the command line, go to the root directory (where all the files are located).

2. Type "ant" (without the quotes) and press Return.

   'dist' will be updated with the monitor.xml and mongo.jar

##Configuration

Parameter	Description
host	Mongo DB host
port	Mongo DB port
username	Username to access mongo db
password	Password to access mongo db
db	The name of the mongo db on the host

#####Note: Ensure that the user has appropriate permissions to the database! Otherwise, metrics will not be displayed in the AppDynamics Metric Browser.

###Example Monitor XML

<monitor>
        <name>Mongo DBMonitor</name>
        <type>managed</type>
        <description>Mongo DB server monitor</description>
        <monitor-configuration></monitor-configuration>
        <monitor-run-task>
                <execution-style>continuous</execution-style>
                <!--
                <execution-frequency-in-seconds>60</execution-frequency-in-seconds>
                -->
                <name>Mongo DB Monitor Run Task</name>
                <display-name>Mongo DB Monitor Task</display-name>
                <description>Mongo DB Monitor Task</description>
                <type>java</type>
                <!--
                <execution-timeout-in-secs>60</execution-timeout-in-secs>
                -->
                <task-arguments>
                        <argument name="host" is-required="true" default-value="localhost" />
                        <argument name="port" is-required="true" default-value="27017" />
                        <argument name="username" is-required="true" default-value="admin" />
                        <argument name="password" is-required="true" default-value="admin" />
                        <argument name="db" is-required="true" default-value="admin" />

                        <!-- Additional MongoDB credentials (OPTIONAL)
                                Additional MongoDB credentials can be placed in properties.xml
                        -->
                        <argument name="properties-path" is-required="false" default-value="monitors/MongoMonitor/properties.xml" />
                </task-arguments>
                <java-task>
                    <classpath>MongoMonitor.jar;lib/gson-2.2.2.jar;lib/mongo-java-driver-2.11.3.jar;lib/dom4j-1.6.1.jar</classpath>
                        <impl-class>com.appdynamics.monitors.mongo.MongoDBMonitor</impl-class>
                </java-task>
        </monitor-run-task>
</monitor>

##Directory Structure

File/Folder	Description
conf	Contains the monitor.xml and properties.xml
lib	Contains third-party project references
src	Contains source code to Mongo DB Custom Monitor
dist	Only obtained when using ant. Run 'ant build' to get binaries. Run 'ant package' to get the distributable .zip file.
build.xml	Ant build script to package the project (required only if changing Java code)

Main Java File: src/com/appdynamics/monitors/mongo/MongoDBMonitor.java -> This file contains the metric parsing and printing.

##Metrics

Server

Metric Name	Description
Up Time (ms)	The duration of time that the server is up

###Locks

Metric Name	Description
Total Time (ms)	The total time since the globalLock was started and created
Lock Time (ms)	The time since the database last started globalLock and has been held

Current Queue

Metric Name	Description
Total	Number of operations queued before a lock
Readers	Number of operations waiting for the read-lock
Writers	Number of operations waiting for the write-lock

Active Clients

Metric Name	Description
Total	Number of active client connections to the database
Readers	Number of readers performing read operations
Writers	Number of writers performing write operations

###Memory

Metric Name	Description
Bits	Target Architecture
Resident	Amount of RAM (MB) currently used by the database process
Virtual	MB currently used by the mongod process
Mapped	Amount of mapped memory (MB) used by the database
Mapped With Journal	Amount of mapped memory (MB), including memory used for journaling.

###Connections

Metric Name	Description
Current	Number of current connections to the database server from clients. This number includes the current shell connection as well as any inter-node connections to support a replica set or sharded cluster.
Available	Number of unused available connections that the database can provide. Consider this value in combination with the value of Current to understand the connection load on the database.

###Index Counters

Metric Name	Description
Accesses	Number of times that operations have accessed indexes (Includes hits and misses)
Hits	Number of times an index has been accessed and index was found in memory
Misses	Number of times an index has been accessed and index was available in memory
Resets	Number of times that the index counter has been reset since the database last started

###Background Flushing

Metric Name	Description
Flushes	Number of times the database has been flushed
Total (ms)	Total time (ms) that the mongod process spent writing data to disk
Average (ms)	Average time (ms) that the mongod process spent writing data to disk
Last (ms)	Time (ms) that the mongod process last spent writing data to disk

###Network

Metric Name	Description
Bytes In	The amount of network traffic (bytes) received by the database
Bytes Out	The amount of network traffic (bytes) sent from the database
Number Requests	Number of distinct requests that the server has received

###Operations

Metric Name	Description
Insert	Number of insert operations
Query	Number of query operations
Update	Number of update operations
Delete	Number of delete operations
GetMore	Number of getmore operations
Command	Total number of commands issued to database

###Asserts

Metric Name	Description
Regular	Number of regular assertions raised since the server started
Warning	Number of warnings raised since the server process started
Msg	Number of message assertions raised since the process started
User	Number of "user asserts" that have occurred since the last time
Rollovers	Number of times that the rollover counter has rolled over since the last time

##Contributing

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

##Community

Find out more in the AppSphere community.

##Support

For any questions or feature request, please contact AppDynamics Center of Excellence.