How to: Install the Memcached Agent for NewRelic in an Ubuntu server

How to: Install the Memcached Agent for NewRelic in an Ubuntu server

Everytime I try to install a plugin for New Relic I find myself trying to figure out how to perform each of the steps. For example, take this instructions on how to install the Memcached agent to get monitoring on your web server:

Manual Installation

1. Download the latest newrelic_memcached_plugin-X.Y.Z.tar.gz from https://github.com/newrelic-platform/newrelic_memcached_plugin/tags
2. Extract the downloaded archive to the location you want to run the Memcached agent from
3. Run bundle install to install required gems
4. Copy config/template_newrelic_plugin.yml to config/newrelic_plugin.yml
5. Edit config/newrelic_plugin.yml with your license key and to point to your instances of Memcached. You can add as many hosts as you’d like If your Memcached instances are bound to an external IP, use that value for the host field. If you omit the ‘port’ field it will default to ‘11211’
6. Edit the config/newrelic_plugin.yml file by changing the name and endpoint fields to match your Memcached server configuration
7. From your shell run: ./newrelic_memcached_agent
8. Wait a few minutes for New Relic to begin processing the data sent from your agent.
9. Log into your New Relic account and click on Memcached on the left hand nav bar to start seeing your Memcached metrics

Seems simple enough… but I really wish I could just copy paste some code and be done. For starters, I don’t even have Ruby installed or Bundler and I can’t remember how to properly extract .tar files… so I those instructions are too high level for me. Taking into consideration that not all users are savvy to the bone Linux users I decided to get a more low level detailed step by step instructions to make this task easier:

O. Summary (Just the commands)

For those who’ve done this in the past and just want to get it over with quickly:

sudo bash

apt-get install ruby2.0

apt-get install ruby2.0-dev

apt-get install build-essential

gem install bundler

(Download the plugin to a folder like /etc/newrelic and extract the files to a subdirectory. See to get the latest version)

wget https://github.com/newrelic-platform/newrelic_memcached_plugin/archive/release/1.0.1.tar.gz

tar -xvzf 1.0.1.tar.gz

cd newrelic_memcached_plugin-release-1.0.1/

nano Gemfile #(Add gem "daemons")

bundle install

cp config/template_newrelic_plugin.yml config/newrelic_plugin.yml

nano config/newrelic_plugin.yml #Add License key and configure your monitoring endpoint name/address

(Create the .daemon file as explained on section VI. Execute the Daemon)

./newrelic_memcached_agent.daemon start

ln -s /etc/newrelic/newrelic_memcached_plugin-release-1.0.1/newrelic_memcached_agent.daemon /etc/init.d/newrelic_memcached_agent.daemon

update-rc.d newrelic_memcached_agent.daemon defaults

And for those who are going through this for the first time: Step by Step with explanations:

I. Install Ruby & II. Install Bundler for Ruby

Visit How to: Install Ruby in an Ubuntu Server to use it with NewRelic’s Plugins to get a complete picture of these two steps. I moved them there as these steps are common among many plugins that use Ruby hence I will only need to maintain these instructions up to date in one place.

III. Get the Server Agent

You should check out what the latest version is from either

a) NewRelic’s site

https://rpm.newrelic.com/accounts/472634/plugins/directory/144

or

b) GitHub

https://github.com/newrelic-platform/newrelic_memcached_plugin/tags

As of the date this article was originally published the latest version is: and can be downloaded from: https://github.com/newrelic-platform/newrelic_memcached_plugin/archive/release/1.0.1.tar.gz. Once you have determined the URL for the latest tar file you can proceed to extract it.

First, create a new directory were you’ll put the agent with mkdir agent or whatever you prefer. Once done navigate to that folder and type:

wget https://github.com/newrelic-platform/newrelic_memcached_plugin/archive/release/1.0.1.tar.gz

tar -xvzf 1.0.1.tar.gz

this should result in the following output:

newrelic_memcached_plugin-release-1.0.1/
newrelic_memcached_plugin-release-1.0.1/.gitignore
newrelic_memcached_plugin-release-1.0.1/Gemfile
newrelic_memcached_plugin-release-1.0.1/LICENSE
newrelic_memcached_plugin-release-1.0.1/README.md
newrelic_memcached_plugin-release-1.0.1/config/
newrelic_memcached_plugin-release-1.0.1/config/template_newrelic_plugin.yml
newrelic_memcached_plugin-release-1.0.1/newrelic_memcached_agent

IV. Install Agent

Run the following commands:

cd newrelic_memcached_plugin-release-1.0.1/

You should modify the Gem file so that it includes the daemon gem in case you want to execute this as a daemon (who wouldn’t right?)

so pick your favorite editor like nano (nano Gemfile) and add the following line (at the end is fine):

gem “daemons”

after that you can proceed to run the script that will install all the gems for you:

bundle install

You should get the following prompt:

Fetching gem metadata from http://rubygems.org/………..
Fetching additional metadata from http://rubygems.org/..
Resolving dependencies…

Installing daemons 1.1.9

Installing dalli (2.7.0)
Using json (1.8.1)
Using newrelic_plugin (1.3.1)
Using bundler (1.5.3)
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.

Don’t worry if instead of “installing daemons 1.1.9” for example you get “using daemons 1.1.9”. That only means that you already had a previous bundle that installed that gem so instead of installing it you are just going to use it as well.

Then copy and edit the configuration file

cp config/template_newrelic_plugin.yml config/newrelic_plugin.yml

nano config/newrelic_plugin.yml

in the YML file you’ll need to configure things like your License Key for New Relic as well as the address of your host / listening endpoint and the name you want it to display under the dashboard.

V. Make sure you are accepting connections from the server the agent is installed on

For example, I was using memcached via unix socket but apparently the agent cannot connect via sockets only through the TCP/IP. Memcached only supports listening on either a unix socket or an ip port. So I had to change my memcached settings so my agent could communicate with it via TCP/IP.

VI. Execute the Daemon

First lets do a test to make sure things work.

./newrelic_memcached_agent

If things work you’ll get a message that reads:

[2014-03-01 20:49:19 UTC] INFO: Using Ruby SDK version: 1.3.1
[2014-03-01 20:49:19 UTC] INFO: Agent Memcached is at version 1.0.1
[2014-03-01 20:49:19 UTC] DEBUG: Start collecting agent data for poll cycle
[2014-03-01 20:49:19 UTC] ERROR: Error occurred in poll cycle: undefined method `>’ for nil:NilClass
[2014-03-01 20:49:19 UTC] DEBUG: Stacktrace:
./newrelic_memcached_agent:120:in `report_cacheuse_metrics’
./newrelic_memcached_agent:94:in `poll_cycle’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/agent.rb:139:in `run’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:143:in `block in run_agent_data_collection’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:141:in `each’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:141:in `run_agent_data_collection’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:127:in `loop_forever’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:15:in `setup_and_run’
./newrelic_memcached_agent:134:in `<module:MemcachedAgent>’
./newrelic_memcached_agent:37:in `<main>’
[2014-03-01 20:49:19 UTC] DEBUG: Finished collecting agent data for poll cycle
[2014-03-01 20:49:19 UTC] DEBUG: JSON payload: {“agent”:{“version”:”1.0.1″},”components”:[{“name”:”CloudIngenium – East US Server”,”guid”:”com.newrelic.plugins.memcached.ruby”,”duration”:60,”metrics”:{“Component/System/Summary/Memory/Bytes/Used[bytes]”:[]”:
[2014-03-01 20:49:20 UTC] INFO: Gathered 2 statistics from 1 components
[2014-03-01 20:50:19 UTC] DEBUG: Start collecting agent data for poll cycle
[2014-03-01 20:50:19 UTC] ERROR: Error occurred in poll cycle: undefined method `>’ for nil:NilClass
[2014-03-01 20:50:19 UTC] DEBUG: Stacktrace:
./newrelic_memcached_agent:120:in `report_cacheuse_metrics’
./newrelic_memcached_agent:95:in `poll_cycle’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/agent.rb:139:in `run’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:143:in `block in run_agent_data_collection’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:141:in `each’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:141:in `run_agent_data_collection’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:127:in `loop_forever’
/var/lib/gems/2.0.0/gems/newrelic_plugin-1.3.1/lib/newrelic_plugin/run.rb:15:in `setup_and_run’
./newrelic_memcached_agent:134:in `<module:MemcachedAgent>’
./newrelic_memcached_agent:37:in `<main>’
[2014-03-01 20:50:19 UTC] DEBUG: Finished collecting agent data for poll cycle

For example, if you haven’t configured properly your status stub you might get a message like this one:

[2014-03-01 20:43:51 UTC] DEBUG: Component with name “CloudIngenium – East US Server” and guid “com.newrelic.plugins.memcached.ruby” had no metrics

OR

[2014-03-01 20:45:04 UTC] ERROR: Error occurred in poll cycle: invalid value for Integer(): “/tmp/memcached.sock”

OR

[2014-03-01 20:46:40 UTC] DEBUG: Start collecting agent data for poll cycle
I, [2014-03-01T14:46:40.108269 #10759] INFO — : localhost:11211 failed (count: 0) Errno::ECONNREFUSED: Connection refused – connect(2)

If everything looks good, you can start to configure the daemon as follows.

First, create a file with your favorite file editor like nano:

nano newrelic_memcached_agent.daemon

then type the following:

#!/usr/bin/env ruby
#
# Copyright (C) CloudIngenium.com

require ‘rubygems’
require ‘daemons’
require ‘bundler/setup’

require ‘newrelic_plugin’
require ‘dalli’ # Memcached driver

Daemons.run(File.dirname(Pathname.new(__FILE__).realpath) + ‘/newrelic_memcached_agent’)

after that you will need to configure the execute bit otherwise you will get an error like this:

bash: ./newrelic_memcached_agent.daemon: Permission denied

chmod +x newrelic_memcached_agent.daemon

Now, there is a line we need to add to the regular agent file that without it the process won’t continue to run successfully:

nano newrelic_memcached_agent

and find the following lines and insert the one that is indicated in bold (Thanks to J. Zaparolli, otherwise I wouldn’t have figured this one out):

#
#
# Memcached Agent
#
#
module MemcachedAgent

class Agent < NewRelic::Plugin::Agent::Base
agent_guid “com.newrelic.plugins.memcached.ruby”
agent_version “1.0.1”
agent_config_options :endpoint,:port,:name
agent_human_labels(“Memcached”) { “#{name}” }

Dir.chdir ‘/etc/newrelic/newrelic_memcached_plugin-release-1.0.1’

def setup_metrics
@rusage_user = NewRelic::Processor::EpochCounter.new
@rusage_system = NewRelic::Processor::EpochCounter.new

Now you are done, start the daemon!

./newrelic_memcached_agent.daemon start

Note that you have start, stop, restart and status at your disposal

VII. Make it start every time you reboot your computer

You may want to create a symbolic link from /etc/init.d/ to the actual location of newrelic_memcached_agent.daemon in order to start the agent automatically at boot time.

We shall create a symbolic link:

ln -s /etc/newrelic/newrelic_memcached_plugin-release-1.0.1/newrelic_memcached_agent.daemon /etc/init.d/newrelic_memcached_agent.daemon

And then we should let Ubuntu know about it:

update-rc.d newrelic_memcached_agent.daemon defaults

You should then get a similar message:

update-rc.d: warning: /etc/init.d/newrelic_memcached_agent.daemon missing LSB information
update-rc.d: see <http://wiki.debian.org/LSBInitScripts>
Adding system startup for /etc/init.d/newrelic_memcached_agent.daemon …
/etc/rc0.d/K20newrelic_memcached_agent.daemon -> ../init.d/newrelic_memcached_agent.daemon
/etc/rc1.d/K20newrelic_memcached_agent.daemon -> ../init.d/newrelic_memcached_agent.daemon
/etc/rc6.d/K20newrelic_memcached_agent.daemon -> ../init.d/newrelic_memcached_agent.daemon
/etc/rc2.d/S20newrelic_memcached_agent.daemon -> ../init.d/newrelic_memcached_agent.daemon
/etc/rc3.d/S20newrelic_memcached_agent.daemon -> ../init.d/newrelic_memcached_agent.daemon
/etc/rc4.d/S20newrelic_memcached_agent.daemon -> ../init.d/newrelic_memcached_agent.daemon
/etc/rc5.d/S20newrelic_memcached_agent.daemon -> ../init.d/newrelic_memcached_agent.daemon

and you’re done! Congratulations!

Try rebooting your server and seeing if the daemon work properly.

First check the status on your server:

service newrelic_memcached_agent.daemon status

because we tested earlier then it should pick up it is executing and you will get a line similar to the one below:

newrelic_memcached_agent: running [pid 14056]

Then go to NewRelic.com and see if you are getting data in your dashboard.