Find the New Relic MySQL plugin in the New Relic storefront
Find the New Relic MySQL plugin in Plugin Central
Your New Relic MySQL plugin can be operational in just a few minutes when following these steps.
The MySQL plugin for New Relic requires the following:
- A New Relic account. Signup for a free account at http://newrelic.com
- A server running MySQL Version 5.0 or greater. Download MySQL for free at http://dev.mysql.com/downloads
- A configured Java Runtime (JRE) environment Version 1.6 or better
- Network access to New Relic (authenticated proxies are not currently supported, but see workaround below)
Note: The MySQL Plugin includes the Connector/J JDBC Driver and it does not need to be installed separately.
The MySQL plugin can be installed manually or automatically with Chef and Puppet. For Chef and Puppet support see the New Relic plugin's Chef Cookbook and Puppet Module.
Additional information on using Chef and Puppet with New Relic is available in New Relic's documentation.
Download and unpack the New Relic plugin for MySQL from Plugin Central
Linux example:
$ mkdir /path/to/newrelic-plugin
$ cd /path/to/newrelic-plugin
$ tar zxvf newrelic_mysql_plugin*.tar.gz
The MySQL plugin requires a MySQL user with limited privileges. To use the New Relic default, run the following SQL script located at /scripts/mysql_user.sql.
$ mysql -uroot -p < mysql_user.sql
This script will create the following user:
username: newrelic
host: localhost or 127.0.0.1
password: *B8B274C6AF8165B631B4B517BD0ED2694909F464 (hashed value)
You can choose to use a different MySQL user name and password. See MYSQL.TXT for more info.
If your MySQL Server is bound to an externally visible IP address, both localhost and 127.0.0.1 will not be accessible via TCP as the host for the MySQL Plugin. In order for the plugin to connect, you will need to create a user for your IP address. Due to security concerns in this case, we strongly recommend not using the default password and instead setting it to some other value.
CREATE USER newrelic@<INSERT_IP_ADDRESS_HERE> IDENTIFIED BY '<INSERT_HASHED_PASSWORD_HERE>';
GRANT PROCESS, REPLICATION CLIENT ON *.* TO newrelic@<INSERT_IP_ADDRESS_HERE>;
The New Relic plugin for MySQL runs an agent process to collect and report MySQL metrics to New Relic. Configure your New Relic license and MySQL databases.
Specify your license key in the necessary properties file. Your license key can be found under Account Settings at https://rpm.newrelic.com see https://newrelic.com/docs/subscriptions/license-key for more help.
Linux example:
$ cp config/template_newrelic.properties config/newrelic.properties
# Edit config/newrelic.properties and paste in your license key
Each running MySQL plugin agent requires a JSON configuration file which defines the access to the monitored MySQL instance(s). An example file is provided in the config directory.
Linux example:
$ cp config/template_mysql.instance.json config/mysql.instance.json
# Edit config/mysql.instance.json
If using your localhost MySQL instance, add a meaningful name which will appear in the New Relic user interface for the MySQL instance. Set the "name" attribute to match your MySQL databases purpose, e.g. "Production Master". If you used the provided /scripts/mysql_user.sql to generate a default user and password, then you do not need to set the "user" and "passwd" attributes. If you are not using the default user and password, you will need to provide a user and clear text password with the same limited priveleges as shown below.
[
{
"name" : "Production Master",
"host" : "localhost",
"metrics" : "status,newrelic",
"user" : "USER_NAME_HERE",
"passwd" : "USER_CLEAR_TEXT_PASSWORD_HERE"
}
]
If your MySQL Server is bound to an externally visible IP address, set the 'host' to your IP address and use the username and password that you created above. See the 'Create MySQL user if necessary' section above.
The MySQL Plugin is capable of reporting different sets of metrics by configuring the 'metrics' attribute. E.g., add the 'slave' category to report replication metrics. See CATEGORIES.TXT for more info.
Note: The innodb_mutex metric category can lead to increased memory usage for the plugin if the monitored database is under a high level of contention (i.e. large numbers of active mutexes).
The MySQL plugin can report metrics for Amazon RDS MySQL instances as well. To do so, configure the mysql.instance.json as mentioned above in Configure your MySQL properties and set your host attribute to the RDS instance endpoint without the port. The endpoint can be found in the AWS console for your instance. For more information regarding the RDS endpoint see the Amazon RDS documentation.
Ex. database1.abcjiasdocdsf.us-west-1.rds.amazonaws.com
The user and passwd attributes should be the RDS master user and master password, or a user and password that has correct privileges. See Create MySQL user if necessary for more information.
To run the plugin from the command line:
$ java -jar newrelic_mysql_plugin*.jar
Note: When running the plugin on a server class machine, the java command will start a JVM that may reserve up to one quarter (25%) of available memory. To reduce the amount of reserved memory use the -Xmx JVM argument. Ex. java -Xmx128m -jar newrelic_mysql_plugin*.jar
For more information on JVM server class machines and the -Xmx JVM argument, see:
- http://docs.oracle.com/javase/6/docs/technotes/guides/vm/server-class.html
- http://docs.oracle.com/cd/E22289_01/html/821-1274/configuring-the-default-jvm-and-java-arguments.html
If your host needs a proxy server to access the Internet, you can specify a proxy server & port:
$ java -Dhttps.proxyHost=proxyhost -Dhttps.proxyPort=8080 -jar newrelic_mysql_plugin*.jar
To run the plugin from the command line and detach the process so it will run in the background:
$ nohup java -jar newrelic_mysql_plugin*.jar &
You can use services like these to manage this process.
The debian init script will import environment variables from /etc/default/newrelic-mysql-plugin
Set the DAEMONDIR variable to the directory where you have installed the agent
Plugin support and troubleshooting assistance can be obtained by visiting support.newrelic.com
The MySQL plugin uses an extensible architecture that allows you to define new MySQL metrics beyond the provided defaults. To expose more data about your MySQL servers, fork this repository, create a new GUID, add the metrics you would like to collect to config/metric.category.json and then build summary metrics and dashboards to expose your newly collected metrics.
See CATEGORIES.TXT for more info.
The MySQL plugin was originally authored by Ronald Bradford of EffectiveMySQL. Subsequent updates and support are provided by New Relic.