MongoDB Management Suite Manual Release 1.1

Transcription

1 MongoDB Management Suite Manual Release 1.1 MongoDB, Inc. Dec 03, 2017

2 MongoDB, Inc

3 Contents 1 On Prem MMS Monitoring On Prem MMS Monitoring Overview How On Prem MMS Monitoring works Security Installation Getting Started with On Prem MMS Monitoring On Prem MMS Monitoring Setup Tutorials Monitoring Hosts with On Prem MMS Monitoring Configuring On Prem MMS Monitoring Updating the Monitoring Agent Troubleshooting Using the MMS Console Hosts Events Alerts User and Environment Management Dashboards Settings Host Statistics Next Steps Frequently Asked Questions: On Prem MMS Monitoring How do I add a new host or server? How do I download the preconfigured agent? How do I setup and configure the agent? Should I run more than one agent? How does MMS gather database statistics? Can I run the Monitoring agent on an AWS micro instances? Can I monitor Kerberos-enabled nodes? What are all those vertical bars in my charts? Why is my hostname displayed in orange? Why is my Monitoring agent highlighted in red on the Agents tab? What is Exposed DB Host Check, and why did MMS send me an MMS Found Exposed Databases!!! ? Why can t the Monitoring agent connect to my host? How do I modify my alert settings? How do I reset my password? How do I change my password? How do I add a user to my company/group? What open source projects are you using? On Prem MMS Monitoring Reference Host Types Host Process Types Event Types Alert Types Chart Colors Database Commands Used by the Monitoring Agent PyMongo Error Codes Browsers Supported by the MMS Console

4 1 On Prem MMS Monitoring On Prem MMS Monitoring is a service for monitoring MongoDB deployments, as an inteegral part of the On-Prem MongoDB Management Service. On Prem MMS Monitoring collects statistics on all key server and hardware indicators and presents this data through an intuitive web interface. This manual describes the installation of the On Prem MMS Monitoring server component, the Monitoring agent, and operation of the On Prem MMS Monitoring web console. You can find answers to common questions in the FAQs, but for all other inquiries please feel free to open a JIRA ticket. As an alternative, you may consider the full installation instructions in the /monitoring/tutorial. 1.1 On Prem MMS Monitoring Overview On this page How On Prem MMS Monitoring works Security Installation On Prem MMS Monitoring is an integral part of the On-Prem MongoDB Management Service (MMS). Designed for security and ease of use, MMS collects statistics on all key server and hardware indicators and then presents the data in a powerful web console. The data is a great asset when optimizing applications during development and potentially invaluable when diagnosing production issues. For sharded clusters consisting of dozens of nodes, On Prem MMS Monitoring is particularly useful because it provides a holistic overview of MongoDB deployments so that administrators can quickly asses the health of their clusters. How On Prem MMS Monitoring works You enable On Prem MMS Monitoring by installing the lightweight Monitoring agent in the server environment. A single agent can monitor an entire deployment of mongod and mongos instances. The agent extracts the data that you provide to On Prem MMS Monitoring and automatically discovers MongoDB instances in your deployment using this seed information. The agent then regularly pushes data to On Prem MMS Monitoring, which it uses to provide reports on metrics that include memory usage, ops per second, and open connections. If enabled, On Prem MMS Monitoring can also track system performance, including CPU load and I/O activity. The MMS web console then displays the status of each MongoDB instance, as well as historical graphs for all collected data. You can create custom dashboards, perform side-by-side data comparisons, and re-plot charts on different timescales to aid analysis. Security The agent transmits all metrics to the MMS servers over SSL (128-bit encryption), and agent traffic is exclusively outbound. The Monitoring agent is a Python script, and you are free to examine its source code. MMS pushes no data to the agent. The agent is subject to firewalls and contains support for MongoDB authentication. Monitored services are only discovered when the agent fetches information provided to MMS or from other members of the cluster. By default, the agent only records server metrics: the collection of hardware and application data must be explicitly enabled. The web interface is secured over SSL, and extensive data access controls and audits are in place to ensure the the safety of your data. 4

5 Installation On Prem MMS Monitoring is compatible with all varieties of MongoDB deployments, regardless of the infrastructure or architecture of the MongoDB deployment. The agent and server installation are quick and straightforward, meaningful results are available through the web interface in minutes. See the Getting Started with On Prem MMS Monitoring document and your On Prem MMS Monitoring instance for more information. 1.2 Getting Started with On Prem MMS Monitoring Installing and configuring On Prem MMS Monitoring quick and easy. This manual will explain how to install and configure your On-Prem MongoDB Management Service server, and guide you through the On Prem MMS Monitoring installation process specific to your operating system. Other pages will help you to customize your configuration, keep the Monitoring agent updated, and provide you with troubleshooting strategies. As an alternative, you may follow the install process from start to finish in the /monitoring/tutorial. On Prem MMS Monitoring Setup Tutorials The following tutorials will guide you through the steps necessary to install and deploy On Prem MMS Monitoring on your system. You will need to install and configure the On-Prem Monitoring server itself, and then install and start the Monitoring agent. As an alternative, you may follow the install process from start to finish in the /monitoring/tutorial. class hidden Install the On-Prem Monitoring Server On this page Requirements Installation Process Configure On-Prem MMS Server Start and Stop the On-Prem MMS Server Advanced Configuration Requirements Hardware To run the On-Prem Monitoring server, you must use a 64-bit server, with requirements according to the following table: 5

6 Number of Monitored CPU Cores RAM Storage Capacity Storage IOPS/s Hosts Up to 400 monitored hosts GB 200 GB 500 Up to 2000 monitored hosts GB 500 GB (SSD) More than 2000 hosts Contact MMS For reference: an AWS EC2 Standard Extra Large (i.e. m1.xlarge) with a provisioned 500 IOP/s EBS volume supported the 400-host configuration above. An AWS EC2 High I/O Quadruple Extra Large (hi1.4xlarge) supported the 2000 host configuration above. For the best results, On-Prem MMS instances require SSD-backed storage. Software On Prem MMS Monitoring has the following required dependencies: 64-bit Linux. On-Prem MMS servers must run any of the following distributions: CentOS 5 or later, Red Hat Enterprise Linux 5, or later, or Amazon Linux AMI (latest version only,) MongoDB or later. SMTP server or other integration option. While many Linux server-oriented distributions include a local SMTP server by default (e.g. Postfix, Exim, Sendmail,) you may also configure On Prem MMS Monitoring to send mail via 3rd party providers including Gmail and Sendgrid. On Prem MMS Monitoring requires for fundamental server functionality such as password reset and alerts. On Prem MMS Monitoring has the following optional dependencies. A Twilio API account for SMS alerting integration. A Graphite hostname / port for charting the MMS server s internal health. An SNMP trap receiver for periodic heartbeat traps about MMS server s internal health. Installation Process Overview At a high level, a basic installation will look like the following. The estimated setup time is less than an hour. 1. Install a standalone local MongoDB server backed by a fast, large storage volume. 2. Install an SMTP server as appropriate for your environment. 3. Install the MMS server RPM package. 4. Configure the MMS server s URL and addresses. 5. Start up MMS server. 6

7 Prepare Server 1. For AWS users, prepare MongoDB Storage: If you are not using AWS, skip this step and continue to the next step. If using an AWS EBS volume for MongoDB storage, create and attach the volume to your EC2 instance. Once the volume is successfully attached, issue the following command to determine the name of the new EBS volume: sudo fdisk -l Create a filesystem on this volume using the name you found in the previous, command, using the following form: sudo mkfs -t ext4 /dev/xvd<letter> Replace <letter> with the identifier for the volume, as in the following example: sudo mkfs -t ext4 /dev/xvdf You only need to create a filesystem the first time you initiate the drive. Create a directory to use as the mount point: sudo mkdir /mnt/ebs-mount-dir Mount the volume with a command that resembles the following: sudo mount /dev/xvd<letter> /mnt/ebs-mount-dir Replace <letter> with the identifier for the volume, as in the following example: sudo mount /dev/xvdf /mnt/ebs-mount-dir 2. Set Linux Kernel parameters. All users must complete this step to ensure optimal performance. Begin by using the following commands to change the parameters of running instance: sudo /sbin/sysctl -w net.core.netdev_max_backlog=30000 sudo /sbin/sysctl -w net.core.wmem_max= sudo /sbin/sysctl -w net.core.rmem_max= Edit the /etc/sysctl.conf file and append the lines below to ensure that these parameters are always applied following a system reboot: net.core.netdev_max_backlog = net.core.wmem_max = net.core.rmem_max = Install and Start MongoDB This section assumes you re installing MongoDB on an instance running Red Hat, CentOS, Fedora, or Amazon Linux: Use the Install Mongodb on Red Hat, CentOS, or Fedora Linux tutorial for more information. 1. Add MongoDB repositories to the system s package management tool. 7

8 Create the /etc/yum.repos.d/mongodb.repo file and add the following information about the repository: [mongodb] name=mongodb Repository baseurl= gpgcheck=0 enabled=1 2. Install the MongoDB packages using the following operations: sudo yum install mongo-10gen mongo-10gen-server 3. Configure data and logging directories for MongoDB. Create directories for MongoDB s log and data. This example assumes that the path for all MongoDB data is beneath /mnt/ebs-mnt-dir/mongo/. Use the following commands: sudo mkdir -p /mnt/ebs-mount-dir/mongo/data sudo mkdir -p /mnt/ebs-mount-dir/mongo/logs Issue the following command to ensure that the mongod process owns all paths below the /mnt/ ebs-mnt-dir/mongo/ path: sudo chown -R mongod:mongod /mnt/ebs-mount-dir/mongo Edit the /etc/mongod.conf to include the following settings: logpath=/mnt/ebs-mount-dir/mongo/logs/mongod.log dbpath=/mnt/ebs-mount-dir/mongo/data This will configure the paths for the log and data directories. Adjust the paths as needed. 4. Start MongoDB. Issue the following command: sudo /etc/init.d/mongod start Note: If using EBS, starting MongoDB may take several minutes to pre-allocate the journal files. This is normal behavior. Obtain and Install On-Prem MMS Server Note: Contact a MongoDB representative to obtain the current stable On Prem MMS Monitoring release. MMS is available in RPM, tar.gz, and zip packages. You can also download the latest On-Prem Monitoring releases from < commercialsupport/downloads> as an RPM package. RPM Install Install the RPM by issuing command in the following form: 8

9 sudo rpm -ivh 10gen-mms-<version>.x86_64.rpm Replace <version> with the version of the.rpm you obtained. When installed, the base directory for the MMS software is /opt/10gen/mms/. The RPM will also create a new system user 10gen-mms under which the server will run. tar.gz and zip Install You can install On Prem MMS Monitoring from the provided tar.gz or zip archive without making any changes to the underlying system (i.e. without creating users.) To install, extract the package, as in the following command: tar -zxf 10gen-mms-<version>.x86_64.tar.gz Optionally create a symlink in /etc/init.d to the included control script for convenience, as in the following: sudo ln -s <install_dir>/bin/10gen-mms /etc/init.d/ Configure On-Prem MMS Server This section describes the required configuration for the On-Prem MMS Server. See Advanced Configuration for more configuration information. Required Configuration Note: By default, On Prem MMS Monitoring will use a local SMTP server listening on port 25. Configure MMS properties, by editing the <install_dir>/conf/conf-mms.properties file. Edit the following properties according to the needs of your deployment, as in the following example: mms.centralurl= mms.from addr=mms Alerts <mms-alerts@example.com> mms.replyto addr=mms-no-reply@example.com mms.adminfrom addr=mms Admin <mms-admin@example.com> mms.admin addr=mms-admin@example.com mms.bounce addr=bounce@example.com These properties are blank initially, and you must define them before the On Prem MMS Monitoring instance will start. Configure Authentication Please refer to your SMTP provider s documentation for the appropriate settings or for how to configure a local SMTP server as a relay. You may configure authentication if you want to send mail using existing infrastructure (i.e. SMTP,) or a service such as Gmail or Sendgrid. Set the following value in the <install_dir>/conf/conf-mms.properties file: 9

10 mms. daoclass=com.xgen.svc.mms.dao. .java dao Then, to the same file, set the following values as defined by your provider. Defaults specified inline: mms.mail.transport=<smtp/smtps> # (defaults to smtp) mms.mail.hostname=<mail.example.com> # (defaults to localhost) mms.mail.port=<number> # (defaults to 25) mms.mail.tls=<true/false> # (defaults to false) The following two values are optional, and unless set default to disabled authentication: mms.mail.username= mms.mail.password= Optional: AWS Simple Service Configuration Set the following value in <install_dir>/conf/conf-mms.properties to configure integration with AWS s Simple Service (SES:) mms. daoclass=com.xgen.svc.mms.dao. .aws dao To configure this integration you must also provide your AWS account credentials in the following two properties: aws.accesskey= aws.secretkey= Start and Stop the On-Prem MMS Server After configuring your On Prem MMS Monitoring deployment, you can start the MMS server with the following command. 1 sudo /etc/init.d/10gen-mms start The On-Prem MMS server logs its output to a logs directory inside the installation directory. You can view this log information with the following command: sudo less <install_dir>/logs/mms0.log If the server starts successfully, you will see content in this file that resembles the following: [main] INFO ServerMain:202 - Starting mms... [main] WARN AbstractConnector:294 - Acceptors should be <=2*availableProcessors: SelectChannelConnector@ :0 [null] LoginService=HashLoginService identityservice=org.eclipse.jetty.security. DefaultIdentityService@1eb3319f [main] INFO AppConfig:46 - Starting app for env: hosted [main] INFO MmsAppConfig:67 - Not loading backup components [main] INFO GraphiteSvcImpl:67 - Graphite service not configured, events will be ignored. [main] INFO TwilioSvcImpl:48 - Twilio service not configured, SMS events will be ignored. 1 If you installed from a tar.gz or zip archive, you must create a symlink located at the path /etc/init.d/10gen-mms that points to the <install_dir>/bin/10gen-mms. 10

11 [main] INFO OpenDMKSnmpTrapAgentSvcImpl:91 - SNMP heartbeats hosts not configured, no heartbeat traps will be sent. [main] INFO ServerMain:266 - Started mms in: (ms) You can now use the On Prem MMS Monitoring instance by visiting the URL specified in the mms. centralurl parameter (e.g. to continue configuration: Unlike the SaaS version of MMS, On Prem MMS Monitoring stores user accounts in the local MongoDB instance. When you sign into the On Prem MMS Monitoring instance for the first time, the system will prompt you to register and create a new group for your deployment. After completing the registration process, you will arrive at the MMS Hosts, page. Because there are no Monitoring agents attached to your account, the first page you see in On Prem MMS Monitoring will provide instructions for downloading the Monitoring agent. Click the download agent link to download a pre-configured agent for your account. Continue reading this document for installation and configuration instructions for the MMS agent. Stopping the On-Prem MMS server is as follows: sudo /etc/init.d/10gen-mms stop Advanced Configuration Change Port Number 1. Edit <install_dir>/conf/conf-mms.properties mms.centralurl= 2. Edit <install_dir>/conf/mms.conf BASE_PORT=<newport> 3. Restart MMS server: sudo <install_dir>/bin/10gen-mms restart Run as Different User 1. Edit <install_dir>/conf/mms.conf: MMS_USER=foo_user 2. Change Ownership of <install_dir> for new user: sudo chown -R foo_user:foo_group <install_dir> 3. Restart MMS server: sudo <install_dir>/bin/10gen-mms restart 11

12 Replication Configuration The backing MongoDB store uses a connection string URI defined in the <install_dir>/conf/ conf-mms.properties directory. Edit conf-mms.properties to define the replication hosts or partition MMS databases onto separate machines. For example: mongo.mmsdbpings.mongouri=mongodb://host1:40000,host2:40000,host3:40000/? maxpoolsize=100 mongo.mmsdbpings.replicaset=pingsreplset mongo.mmsdbqueues.mongouri=mongodb://host1:50000,host2:50000,host3:50000/? maxpoolsize=50 mongo.mmsdbqueues.replicaset=mmsdbqueuesreplset Note: More information about connection string URI format available here Authentication Configuration For standalone MongoDB nodes running with user authentication, simply add the username and password credentials to the mongouri, and specify the database as admin. For example: mongo.mmsanalytics.mongouri=mongodb://mongouser:mongopw@ :40000/admin? maxpoolsize=25 mongo.mmsanalytics.replicaset=mmsanalyticsreplset Unfortunately, this does require the plaintext credentials be in the clear, however following standard practice you may reduce the permissions of the configuration file: sudo chmod 600 <install_dir>/conf/conf-mms.properties Optional: Configure a Required recaptcha for user Registration To enable recaptcha anti-spam test on new user registration, you may sign up for a recaptcha account and provide your API credentials in the following two properties: recaptcha.public.key= recaptcha.private.key= Optional: Configure Twilio SMS Alert Support To receive alert notifications via SMS, signup for a Twilio account at and enter your account ID, API token, and Twilio phone number into the following properties: twilio.account.sid= twilio.auth.token= twilio.from.num= 12

13 Optional: Configure SNMP Heartbeat Support New in v1.1.0 The MIB file is available for download at: MMS-10GEN-MIB.txt You can configure the On-Prem MMS Server to send a periodic heartbeat trap notification (v2c) that contain an internal health assessment of the MMS Server. The MMS Server can send traps to one or more endpoints on the standard SNMP UDP port 162. There are three configuration options that affect the heartbeat behavior: # Listening UDP port for SNMP. (Note: Setting to less than 1024 will require running MMS server with root privileges.) snmp.listen.port=11611 #default # Period in seconds between heartbeat notifications snmp.default.heartbeat.interval=300 #default # Optional comma-separated list of hosts where heartbeat traps will be sent on standard UDP port 162. # Leaving blank (the default) disables the SNMP heartbeat functionality snmp.default.hosts= Installing the Monitoring Agent on UNIX/Linux On this page Requirements and Prerequisites Install Monitoring Agent Software Automating Agent Deployments Next Steps Requirements and Prerequisites On Prem MMS Monitoring has a series of prerequisite requirements. The following sections will guide you through the requirements and provide basic instructions for fulfilling them. Basic On Prem MMS Monitoring Requirements Your MongoDB instances (i.e. mongod and mongos) must be version 1.6 or newer. You must have Python 2.4 or greater. 13

14 Note: The Monitoring agent does not provide support the PyPy implementation of Python, and does not support the Python 3.x series of Python. You ll need Python s setuptools. Most operating systems (i.e. distributions) package setuptools. For example, Debian and Ubuntu users can use the following command to install the package: sudo apt-get install python-setuptools For Red Hat Enterprise Linux (RHEL) CentOS, or Fedora users, the the following command will install the package: sudo yum install python-setuptools If your system is running Python 2.4, you will need to install the following Python modules: hmac hashlib Issue the following command: sudo easy_install hmac hashlib Note: The latest version of the Monitoring agent includes no other Python module dependencies. If you re installing version 1.4 of the agent (legacy) you will also need to install the simplejson module. For users of Python 2.4, you will need to install simplejson version Install this module with the following command: sudo easy_install simplejson==2.1.0 For users of Python 2.5, you will need to install the simplejson with the following command: sudo easy_install simplejson Do not use pip to install modules when using Python 2.4 or 2.5, as there are some compatibility issues. Some users have reported problems installing hmac, if easy_install produces an error or you suspect a problem with these libraries see instructions for installing hmac manually. All users must install PyMongo, the Python driver for MongoDB. Use the latest possible version of PyMongo for the best possible speed and stability. The agent is not compatible with versions of PyMongo before 1.9. For instructions for installing PyMongo, see Installing PyMongo. If your datacenter requires that you proxy outbound connections through a gateway, you must use a version of Python greater than Additionally, you will need export the https_proxy environment variable (or HTTPS_PROXY on Windows). For more information, see Working with Proxies. 14

15 Consider the README file distributed with the agent for more information. When all dependencies are successfully installed, you may proceed to installing the agent. Install Monitoring Agent Software If you already have jira account you may sign in to MMS with your JIRA credentials. When you sign into MMS for the first time, the system prompts you to create a new group for your deployment. If you have not downloaded the Monitoring agent already, you can click the Settings link immediately after you sign into MMS (i.e. < and then select MMS Agent from the left-hand list to download an agent specifically configured for your account. You can run the agent on any system that can connect to the MongoDB instances you want to monitor. As long as it can connect to each instance, you can use a single agent to do all the monitoring. Do be sure that the agent can make outgoing connections via HTTPS on port 443. Note: The Monitoring agent does have some resource requirements and should run on separate systems to avoid impacting mongod and mongos performance. To monitor five or fewer nodes, you can safely deploy on an AWS micro instance. Similarly, if you are only monitoring a small number of databases, you may be able to deploy the agent on the system running the mongos process. Running PyMongo with the native extensions, which requires GCC, provides significant performance improvements. Unzip the archive and run the agent with the following command: python agent.py This starts two processes: a parent to monitor the agent daemon and perform automatic upgrades and a child process to collect data. Warning: If your MongoDB instance has thousands of databases or collections, you will want to disable database statistics collection. See Database and Collection statistics for more information. Automating Agent Deployments The agent you downloaded from the On-Prem MongoDB Management Service site is automatically configured with the credentials for your account. You can download a configured copy of the Monitoring agent by copying the link available in the Group Settings section of the Settings tab of the MMS console. This link will resemble the following: Alternately, you may automate Monitoring agent deployments using an unconfigured agent, and the API and secret keys from the API Key and Secret Key sections of the settings page. The unconfigured agent is available at the following URL: Unzip this archive and edit the settings.py file. Replace the with the API and Secret Keys defined for your account. You can find these in the Settings page of the MMS console. 15

16 You may embed this process in your existing deployment scripts to automatically install or redeploy new agents. Next Steps Now that you have installed the Monitoring agent software, you can deploy the Monitoring agent in production. Installing the Monitoring Agent on Windows On this page Install Agent Software If you already have jira account you may sign in to MMS with your JIRA credentials. When you sign into MMS for the first time, the system prompts you to create a new group for your deployment. If you have not downloaded the Monitoring agent already, you can click the Settings link immediately after you sign into MMS (i.e. < select Settings and then click on MMS Agent to download an agent specifically configured for your account. Install Agent Software The Monitoring agent distribution download includes a WINDOWS.txt file with instructions for using the agent on Windows platforms. Before you can use the agent on Windows platforms, you must ensure your system meets the system requirements. The following tutorial will ensure you have installed all required packages. 1. If you do not have a 2.x-series Python installation on your system, install the latest version of Python 2.7.x. If your system supports 64-bit executable, use the 64-bit version. 2. Use the Windows installer to install PyMongo from PyPi. Ensure that you install the correct PyMongo build for your Python installation both in terms of version number (e.g.2.6, 2.7, etc.) and system architecture (e.g. 32 or 64-bit.) See the Python Download Page for the most up to date Python distribution downloads, or use the direct link for the Python bit Windows Installer 3. If you do not have Windows PowerShell version 2.0 to install, install it now. PowerShell is available as part of the Windows Management Framework. Check your installed version of PowerShell by starting a PowerShell command window and issuing the following command: Get-Host Install the correct version if your version number is lower than Enable script execution in PowerShell. After installing the correct version, right click the PowerShell icon in the Start Menu, and run PowerShell as administrator. Issue the following command: Get-ExecutionPolicy 16

17 This returns the current execution policy. Save this value for future use. If the policy is Unrestricted you can proceed to the next step. If the policy is not Unrestricted issue the following command: Set-ExecutionPolicy -ExecutionPolicy Unrestricted Confirm the policy change when prompted. 5. Start an administrator command window. Change to the folder containing the MMS agent files. Run mongommsinstall.bat. If this succeeds, the MMS agent will be running and will start on system boot. Now you can start and stop the Windows service to control the MMS agent. Consult the WINDOWS.txt file for more information. If you have changed the execution policy, after the installation has completed successfully set it back to its original value using the following command: Set-ExecutionPolicy -ExecutionPolicy <original value> Replace <original value> with the value that you recorded above. Next Steps Now that you have properly configured your machines and installed the Monitoring agent software, you can deploy the Monitoring agent in production. Installing PyMongo On this page Easy Installation Installing PyMongo C Extensions Build PyMongo Packages with PyMongo C Extensions Easy Installation While the C extensions are not required for On Prem MMS Monitoring, they significantly improve performance. To install these extensions, make sure you have a C compiler (e.g. gcc) and Python header files installed on your system. Debian and Ubuntu users should issue the following command: sudo apt-get install build-essential python-dev Red Hat, CentOS, and Fedora Users should issue the following command: sudo yum install gcc python-devel If you have not installed pymongo issue the following command to install the latest version: sudo easy_install pymongo 17

18 To upgrade to the latest version of the driver, use the following command: sudo easy_install -U pymongo For more information concerning PyMongo installation, see the PyMongo documentation. Installing PyMongo C Extensions If you installed PyMongo with the C extensions (i.e. on a system with a C compiler, or using the Windows installer) then you can disregard this section. Otherwise use the following procedure to reinstall your agent with C extensions. 1. Install gcc, a C compiler, and the necessary development packages: Debian and Ubuntu users should issue the following command: sudo apt-get install build-essential python-dev Red Hat, CentOS, and Fedora Users should issue the following command: sudo yum install gcc python-devel 2. Install the pip utility so that you can uninstall the existing instance of PyMongo, by issuing the following command: sudo easy_install pip 3. Remove the existing copy of PyMongo with the following command: sudo pip uninstall pymongo 4. Now re-install PyMongo with the following command: sudo pip install pymongo After upgrading PyMongo, you will need to restart your Monitoring agent to receive the full effect of the improvement. Note: When you restart your agent there is a 5 minute timeout before the agent will begin sending data to MMS again. Build PyMongo Packages with PyMongo C Extensions If you are installing PyMongo and the Monitoring agent on systems that do not have C compilers, you can create a.egg package of PyMongo with C extensions to install on your system or systems. Note: The packages distributed in PyPI for Windows include C extensions. First, on a system that has a C-compiler, download the PyMongo source. Always download the source for the latest version of the driver, which you can find at the PyMongo page on PyPi. The following example uses version Issue the following command: 18

19 curl > pymongo tar.gz Note: To install a C-compiler (i.e. gcc) and the necessary dependencies, Debian and Ubuntu users should issue the following command: sudo apt-get install build-essential python-dev Red Hat, CentOS, and Fedora Users should issue the following command: sudo yum install gcc python-devel Extract the driver as follows: tar -zxvf pymongo tar.gz Change directories and build the.egg package with the following sequence: cd pymongo python setup.py bdist_egg You can find.egg file in the dist/ sub-directory. The file name will resemble pymongo py2. 7-linux-x86_64.egg but may have a different name depending on your platform and the version of python you use to compile. Warning: These binary distributions, will only work on systems that resemble the environment on which you built the package. In other words, ensure that operating systems and versions of Python and architecture (i.e. 32 or 64 bit) match. Copy this file to the target system and issue the following command to install the package (with root or sudo privileges:) easy_install pymongo py2.7-linux-x86_64.egg Deploying the Monitoring Agent in Production On this page Daemonizing the Process Control Scripts Working with Proxies Next Steps 19

20 Daemonizing the Process For production deployments of On Prem MMS Monitoring, you will want to daemonize the process and ensure that it restarts following a system restart. Your operating system likely has a preferred method for managing daemon processes. As a temporary measure, the following command will start the agent process detached from the current terminal session: nohup python agent.py > /[LOG-DIRECTORY]/agent.log 2>&1 & Replace [LOG-DIRECTORY] with the path to your MongoDB logs. This command allows the agent survive the current terminal session and writes all messages to the agent.log file. You may include this command in your MongoDB control script or use your system s /etc/rc.local equivalent; however, avoid running the agent as root. Control Scripts If you need to create an initialization script to control the daemonized process, consider the following resources: Ubuntu Boot Up How To Debian Linux Control/Init Scripts Arch Linux rc.d Scripts Debian and Ubuntu Systems have an example control script located at /etc/init.d/skeleton that you can use as a template. Red Hat Enterprise Linux and related distributions (e.g. Fedora, CentOS, etc.) provide example control scripts in the /usr/share/doc/initscripts-*/sysvinitfiles/ directory. You may also examine the scripts in your system s /etc/init.d/ or /etc/rc.d/ directory. Ensure that the agent does not run with root privileges. Use the update-rc.d utility on Debian and Ubuntu and the chkconfig tool on Red Hat related systems to add these scripts to the initialization process. Be sure to test the control script configuration. It is essential that you be able to start, stop, and restart the agent following a system reboot. Working with Proxies If your datacenter requires that you route outbound https connections via a proxy, export the https_proxy environment variable (or HTTPS_PROXY on Windows.) Issue the following command before running the Monitoring agent: export https_proxy= Replace with the name or IP address of the proxy server and port with the TCP port that the proxy service runs on. You may choose to export this variable inside of your control script. Next Steps Once the agent is running and configured to your satisfaction, you can begin configuring monitoring for your deployment or start using the console. 20

21 Monitoring Hosts with On Prem MMS Monitoring On this page Monitoring Architecture Additional Considerations for MongoDB 2.4 Nodes Note: On Prem MMS Monitoring does not currently support monitoring for Kerberos-enabled nodes. The Monitoring agent automatically discovers MongoDB processes based on existing cluster configuration. You ll have to manually seed at least one of these hosts from the MMS console. To add a host to On Prem MMS Monitoring, click the plus (+ ADD HOST) button at the top of the Hosts page. This raises a query element for the hostname, port, and optionally an admin DB username and password. Provide the necessary information and select Add. Once it has a seed host, the Monitoring agent will discover any other nodes from associated clusters. These clusters, and their respective seed hosts, include: Master databases, after adding slave databases. Shard clusters, after adding mongos instances. Replica sets, after adding any member of the set. Once you add these seed nodes, the Monitoring agent will fetch this information from the MMS servers. Thus, when configuring the monitoring environment, you may need to wait for several update cycles (e.g minutes) to complete the auto-discovery process and host identification. During this period, you may see duplicate hosts in the MMS web console. This is normal. The Monitoring agent fetches configuration and reports to On Prem MMS Monitoring every minute, so, again, there may be a delay of several minutes before data and host information propagate to the MMS console. You can find immediate evidence of a working installation in the agent output or logs. For more information, check the MMS console s Hosts, section in the Agent Log and Pings tabs. Once On Prem MMS Monitoring has data, you can view and begin using the statistics. If the agent cannot collect information about a host for 24 hours, the On Prem MMS Monitoring system deactivates the instance in the MMS agent and console. Deactivated hosts must be manually reactivated from the MMS console if you wish to collect data from these hosts. Monitoring Architecture Only one Monitoring agent per group or environment will report to On Prem MMS Monitoring at a time. However, you can run multiple instances of the agent to provide redundancy. Secondary agents act as hot standbys. If you stop the agent process, On Prem MMS Monitoring removes the agent from the Agents tab within a day. If a Monitoring agent is unavailable, the last ping times for that agent do not update. To install secondary agents, simply repeat the installation process in the installation guide for each new agent. You can also automate agent installation. Note: When the Monitoring agent restarts, there is a five minute delay before that agent begins collecting data sending pings to On Prem MMS Monitoring. If you have multiple agents, this delay permits other agents in your infrastructure to become the primary agent and for On Prem MMS Monitoring to determine which agent will be primary. 21

22 During this interval, the restarted Monitoring agent will not collect data. Additional Considerations for MongoDB 2.4 Nodes If you are monitoring a MongoDB 2.4 instance with authentication enabled, you must have elevated privileges to collect complete performance data. At a minimum, the user will need to possess: the clusteradmin role, and the readanydatabase role. If MMS is running with DB Profiling enabled, the user requires additional permissions. clusteradmin and readanydatabase roles, the user must possess either: the dbadminanydatabase role, or the dbadmin role on the specific databases being profiled. See also: User Privilege Roles in MongoDB. In addition to the Configuring On Prem MMS Monitoring On this page Hardware Monitoring with Munin-Node Using SSL with On Prem MMS Monitoring Next Steps with On Prem MMS Monitoring This document discusses specific configuration options for On Prem MMS Monitoring, including hardware monitoring with Munin-Node and using On Prem MMS Monitoring with SSL. Hardware Monitoring with Munin-Node On Prem MMS Monitoring provides support for collecting and charting hardware statistics collected with Munin. You must install the munin-node package on each the host system that you wish to monitor. Note: munin-node, and hardware monitoring is only available for MongoDB instances running on Linux hosts. On Debian and Ubuntu systems, issue the following command to install munin-node: sudo apt-get install munin-node To install munin-node on Red Hat, CentOS, and Fedora systems, issue the following command: yum install munin-node Note: For Red Hat and CentOS 6.8 systems, you will need to install the EPEL repository before installing munin-node. To install the EPEL repository, issue the following command: 22

23 rpm -Uvh When installation is complete, ensure that munin-node: is running. Use the command, ps -ef grep "munin" to confirm. If the process is not running, issue the command /etc/init.d/munin-node start. will start following the next system reboot. This is the default behavior on most Debian-based systems. Red Hat and related distributions should use the chkconfig command, to configure this behavior (i.e. chkconfig munin-node on ) is accessible from the system running the agent. munin-node uses port 4949, which needs to be open on the monitored system, so the agent can access this data source. Use the following procedure to test access: telnet [HOSTNAME] 4949 fetch iostat fetch iostat_ios fetch cpu Replace [HOSTNAME] with the hostname of the monitored system. Run these commands from the system where the MMS Agent is running. If these fetch commands return data, then munin-node is running and accessible by MMS agent. Note: On some platforms, munin-node does not have all required plugins enabled. For CentOS, the munin-node package does not have the iostat and iostat_ios plugins enabled. Use the following operation to enable these plugins: sudo ln -s /usr/share/munin/plugins/iostat /etc/munin/plugins/iostat sudo ln -s /usr/share/munin/plugins/iostat_ios /etc/munin/plugins/iostat_ios sudo /etc/init.d/munin-node restart If munin-node is running but inaccessible, make sure that you have access granted for the system running the Monitoring agent and that no firewalls block the port between munin-node and the Monitoring agent. You may find the munin-node configuration at /etc/munin-node/munin-node.conf or /etc/munin-node. conf, depending on your distribution. Additional considerations: If you have numbered disk devices (e.g. /dev/sda1 and /dev/sda2) then you will need to configure support for numbered disk in the munin iostat plugin. Find the configuration file at /etc/munin/plugin-conf. d/munin-node or a similar path, and add the following value: [iostat] env.show_numbered 1 If you have Munin enabled and do not have iostat ios data in your Munin charts, your munin-node may not have write access to required state files in its munin/plugin-state/ directory. See the munin-node plugin log (i.e. /var/log/munin/munin-node.log or similar depending on your distribution) for more information. The full path of this state directory depends on the system, but is typically /var/lib/munin/ plugin-state/. Run the following command sequence to correct this issue: 23

24 touch /var/lib/munin/plugin-state/iostat-ios.state chown -R [username]:[group] /var/lib/munin/plugin-state/ chmod -R 660 /var/lib/munin/plugin-state/ Replace [username] and [group] with the username and group that the munin-node process runs with. If you encounter any other problems, check the log files for munin-node to ensure that there are no errors with Munin. munin-node writes logs files in the /var/log/ directory on the monitored system. Using SSL with On Prem MMS Monitoring On Prem MMS Monitoring can monitor MongoDB instances running with SSL. To use SSL with mongod and mongos, you must enable it at compile time, or use one of the subscriber builds. MongoDB added SSL support in version 2.0. To monitor a host with SSL enabled, you can either: 1. Edit the settings.py file in your agent installation, so that the usesslforallconnections value is True, as follows: usesslforallconnections = True Then restart the Monitoring agent. After restarting the agent you may observe a five minute delay before On Prem MMS Monitoring receives data from the agent. 2. Enable support on a per-host basis in the MMS console by clicking on the edit (i.e. Pencil ) button on the right hand-side of the Hosts page. In the dialogue that pops up, click the check-box on the SSL tab. If you enable SSL support globally you will not be able to override this setting on a per-host basis. Next Steps with On Prem MMS Monitoring Take this opportunity to explore the MMS interface. For a detailed explanation of the pages that form the MMS console, continue to the usage guide. You may also want to consult the troubleshooting guide. Updating the Monitoring Agent Upgrading an RPM-Based Installation Please contact MMS to receive the download location of the latest MMS server release. 1. Shutdown the On-Prem MMS server and take a backup of your existing configuration: sudo /etc/init.d/10gen-mms stop sudo cp -a <install_dir>/conf ~/mms_conf.backup 2. Perform an RPM upgrade: sudo rpm -Uvh 10gen-mms-<version>.x86_64.rpm 3. Reconcile any changes in configuration files. At this point the upgrade is complete. However you may need to reconcile changes in your configuration with new configuration options available in the latest release. During the rpm operation, if you saw the following output, you have changes to reconcile: 24

25 warning: <install_dir>/conf/conf-mms.properties created as conf-mms.properties.rpmnew <install_dir>/conf/ Compare your current configuration to the updated version, with the following sequence of operations.: diff -u <install_dir>/conf/conf-mms.properties <install_dir>/conf/conf-mms. properties.rpmnew diff -u <install_dir>/conf/mms.conf <install_dir>/conf/mms.conf.rpmnew Edit your configuration to resolve any conflicts between the old and new versions, being sure to take any new changes from conf-mms.properties.rpmnew as appropriate. Changes to mms.centraluri, addresses, and MongoDB are the most common configuration changes. Repeat the above reconciliation for mms.conf if the upgrade indicates a conflict. Note: The upgrade from beta versions to changed several paths to make the MMS server completely self contained. In all logs, configuration, and working files are in the /opt/10gen/mms/ hierarchy. This changes the following paths from 1.0.1: New logs path: <install_dir>/logs/ New tmp path: <install_dir>/tmp/ Finally, you may also need to re-symlink your startup script: sudo ln -s /<install_dir>/bin/10gen-mms /etc/init.d/10gen-mms 4. Restart the On-Prem MMS server. sudo /etc/init.d/10gen-mms start Upgrading a tgz/zip Installation To upgrade a tarball installation, backup configuration and/or logs, and then re-install the On-Prem MMS server. Important: It is crucial that you back up the existing configuration because the upgrade process will delete existing data. In more details: 1. Shutdown the MMS server and take a backup of your existing configuration and logs. sudo /etc/init.d/10gen-mms stop sudo cp -a <install_dir>/conf ~/mms_conf.backup sudo cp -a <install_dir>/logs ~/mms_logs.backup 2. Remove your existing MMS server installation entirely and extract latest release in its place: cd <install_dir>/../ sudo rm -rf <install_dir> sudo tar -zxf -C. /path/to/10gen-mms-<version>.x86_64.tar.gz 3. Similar to the RPM upgrade path above, compare and reconcile any changes in configuration between versions: 25

26 diff -u ~/mms_conf.backup/conf-mms.properties <install_dir>/conf/conf-mms. properties diff -u ~/mms_conf.backup/mms.conf <install_dir>/conf/mms.conf 4. Edit your configuration to resolve any conflicts between the old and new versions, being sure to take any new changes as appropriate. Note: Changes to mms.centraluri, addresses, and MongoDB are the most common configuration changes. 5. Restart the On-Prem MMS server. sudo /etc/init.d/10gen-mms start Troubleshooting On this page Troubleshooting: Monitoring Agent Installation Troubleshooting: hmac Installation The document provide troubleshooting advice for common issues encountered installing the On Prem MMS Monitoring agent, and working with hmac. For answers to other questions, see the FAQ. Troubleshooting: Monitoring Agent Installation Consider the following issues if you encounter difficulty installing the Monitoring agent. Make sure that the system running the agent has pymongo installed. If your system runs a 2.4.x series Python, verify the installation of other requirements. Ensure that the system running the agent can resolve and connect to the MongoDB instances. To confirm, log into the system where the agent is running and issue a command in the following form: mongo [hostname]:[port] Replace [hostname] with the hostname and [port] with the port that the database is listening on. Verify that the Monitoring agent can connect on TCP port 443 (outbound) to the MMS server (i.e. mms. mongodb.com.) Allow the agent to run for 5-10 minutes to allow host discovery and initial data collection. If your MongoDB instances run with authentication enabled, ensure that MMS has these credentials. You can supply these credentials when adding a host by specifying credentials in the Add Host Interface, for every host that has authentication enabled. You may also click on the Edit host button (i.e. the pencil) on the Hosts page in the MMS console to provide credentials. If you continue to encounter problems, check the agent s output or logs for errors. 26