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

How to: Install the NginX 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 NginX agent to get monitoring on your web server:

Installation and running

  1. Click the Continue button and complete the brief form.
  2. Download the NGINX web server plugin .tar.gz file.
  3. Unpack the .tar.gz file in a new directory.
  4. Run bundle install to install all needed prerequisites.
  5. Copy config/ to config/newrelic_plugin.yml.
  6. Insert your New Relic license key and NGINX status URL into config/newrelic_plugin.yml.
  7. Run ./newrelic_nginx_agent.daemon start to start the agent in daemon mode.

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

bundle install

(Download the plugin to a folder like /etc/newrelic and extract the files to a subdirectory)

cd newrelic_nginx_agent/

cp config/ config/newrelic_plugin.yml

nano config/newrelic_plugin.yml #Add license key and monitoring agent endpoint information

./newrelic_nginx_agent.daemon start

ln -s /etc/newrelic/newrelic_nginx_agent/newrelic_nginx_agent.daemon /etc/init.d/newrelic_nginx_agent.daemon

update-rc.d newrelic_nginx_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 download the server agent from the web at:

But you could also do the following:

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:


tar -xvzf newrelic_nginx_agent.tar.gz

IV. Install Agent

Run the following commands:

bundle install

You should get the following prompt:

Fetching gem metadata from………..
Fetching additional metadata from
Resolving dependencies…
Using daemons (1.1.9)
Installing json (1.8.1)
Installing 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.

Then copy and edit the configuration file

cp config/ 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 status stub and the name you want it to display under.

V. Make sure you have the NginX status stub

There needs to be a special stub_status location to your nginx configuration for the agent to poll NginX for its current status. You can configure it in a number of ways:

a) Listen to localhost only


server_name localhost;
location = /nginx_stub_status
stub_status on;
acces_log off;
deny all;

b) Listen on *:80, access limited by HTTP basic auth



listen 80;


location = /nginx_stub_status


stub_status on;

auth_basic “nginx status”;

auth_basic_user_file /path/to/auth_file;



Please follow this link to get more information about HTTP basic auth:

You need to reload your configuration once you make this changes as indicated here: How to: Reload your NginX Configuration

VI. Execute the Daemon

First lets do a test to make sure things work.


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

[2014-02-19 23:02:20 UTC] INFO: Using Ruby SDK version: 1.3.1
[2014-02-19 23:02:20 UTC] INFO: Agent Nginx is at version 1.2.1
[2014-02-19 23:02:20 UTC] DEBUG: Start collecting agent data for poll cycle
== http://localhost/nginx_stub_status: STUB STATUS
conns: active=1 idle=0 accepted=14 dropped=0
reqs: total=14 current=1
[2014-02-19 23:02:20 UTC] DEBUG: Finished collecting agent data for poll cycle
[2014-02-19 23:02:20 UTC] DEBUG: JSON payload: {“agent”:{“version”:”1.2.1″},”components”:[{“name”:”Northern Europe Web Cache”,”guid”:”com.nginx.newrelic-agent”,”duration”:60,”metrics”:{“Component/Connections/Active[Connections]”:

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

[2014-02-19 23:00:25 UTC] DEBUG: Start collecting agent data for poll cycle
ERROR while gathering stats from http://localhost/nginx_incorrect_status: 404 Not Found
[2014-02-19 23:00:25 UTC] ERROR: Error occurred in poll cycle: undefined method `content_type’ for nil:NilClass
[2014-02-19 23:00:25 UTC] DEBUG: Stacktrace:
./newrelic_nginx_agent:79: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_nginx_agent:265:in `<module:NginxStatusAgent>’
./newrelic_nginx_agent:13:in `<main>’
[2014-02-19 23:00:25 UTC] DEBUG: Finished collecting agent data for poll cycle

If everything looks good, you can start it as a daemon like so:

./newrelic_nginx_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

As per the instructions:

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

We shall create a symbolic link:

ln -s /etc/newrelic/newrelic_nginx_agent/newrelic_nginx_agent.daemon /etc/init.d/newrelic_nginx_agent.daemon

And then we should let Ubuntu know about it:

update-rc.d newrelic_nginx_agent.daemon defaults

You should then get a similar message:

update-rc.d: warning: /etc/init.d/newrelic_nginx_agent.daemon missing LSB information
update-rc.d: see <>
Adding system startup for /etc/init.d/newrelic_nginx_agent.daemon …
/etc/rc0.d/K20newrelic_nginx_agent.daemon -> ../init.d/newrelic_nginx_agent.daemon
/etc/rc1.d/K20newrelic_nginx_agent.daemon -> ../init.d/newrelic_nginx_agent.daemon
/etc/rc6.d/K20newrelic_nginx_agent.daemon -> ../init.d/newrelic_nginx_agent.daemon
/etc/rc2.d/S20newrelic_nginx_agent.daemon -> ../init.d/newrelic_nginx_agent.daemon
/etc/rc3.d/S20newrelic_nginx_agent.daemon -> ../init.d/newrelic_nginx_agent.daemon
/etc/rc4.d/S20newrelic_nginx_agent.daemon -> ../init.d/newrelic_nginx_agent.daemon
/etc/rc5.d/S20newrelic_nginx_agent.daemon -> ../init.d/newrelic_nginx_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_nginx_agent.daemon status

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

Enhanced by Zemanta

You may also like...

1 Response

  1. February 19, 2014

    […] is just a quick complement of the article How to: Install the NginX Agent for NewRelic in an Ubuntu server. As I mentioned there if you need Ruby for something other than running a plugin agent like in a […]

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.