Hosted Graphite

This add-on is operated by Metricfire Ltd

High performance metrics and monitoring

Hosted Graphite

Last Updated: 07 May 2015

Table of Contents

Hosted Graphite is an add-on for providing application performance metrics.

Hosted Graphite Dashboard

Hosted Graphite give you a simple, scalable way to measure metric data from your application. Graphite is one of the most widely-used and well-tested metrics platforms, used by small developers and large companies such as Etsy alike.

Hosted Graphite is easily accessible using native libraries of Java, Python Ruby, Node.js and has an HTTP API as well.

Why use Graphite?

Graphite is excellent for measuring large amounts of time-series data, in a situation where you might not necessarily know what’s important. It’s a versatile system that allows you to measure thousands of metrics concurrently, and then combine, manipulate, and transform the data into meaningful graphs. Some good examples might be to measure performance data from hundreds of servers, perhaps grouping some of your data by whether the machine is in production or just a development machine. It also allows you to time specific blocks, functions, or functional areas of your code to find performance bottlenecks and tweak ‘em.

Using plugins such as the Hosted Graphite StatsD backend you can automatically aggregate your data so it sends intermittently.

Message format

Hosted Graphite messages are sent in the following format:

apikey.metric_path value\n

Where * 'apikey’ is your Hosted Graphite API key * ‘metric_path’ is the name of the metrics you want to track, dot separated (e.g. ‘request.time’) * ‘value’ is the data you want to send. We accept numeric data only, numeral or decimal.

Provisioning the add-on

Hosted Graphite can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:create hostedgraphite
-----> Adding hostedgraphite to sharp-mountain-4005... done, v18 (free)

Once Hosted Graphite has been added a HOSTEDGRAPHITE_APIKEY setting will be available in the app configuration, which contains your Hosted Graphite API Key used to send metric data to the service. This can be confirmed using the heroku config:get command.

$ heroku config:get HOSTEDGRAPHITE_APIKEY

After installing Hosted Graphite the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export HOSTEDGRAPHITE_APIKEY=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the HOSTEDGRAPHITE_APIKEY values retrieved from heroku config to .env.

$ heroku config -s | grep HOSTEDGRAPHITE_APIKEY >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using Hosted Graphite with various languages

In the following code snippets, the HOSTEDGRAPHITE_APIKEY is automatically pulled from the local environment, and refers to the value returned from the heroku config:get HOSTEDGRAPHITE_APIKEY command listed in the provisioning section.

Calculations such as summing or averaging data can be configured on the graph via the Hosted Graphite dashboard.

Data can be sent to Hosted Graphite using both TCP and UDP methods. In these examples the code sends a hypothetical measurement of a web request which took 1444ms. The value sent is numeric, and doesn’t require that you give a specific type measurement.

TCP Connection

If you’re sending very low volumes of data and are adamant that every single packet needs to be received and measured, TCP is the way to go. There is a slightly larger overhead than UDP due to the nature of the connection, but still should not have any noticeable impact on your application. However, for 99% of users, UDP is the most appropriate option.

UDP Connection

If you’re sending any volume of metric data, UDP is preferred due to it’s low overhead, and asynchronous data transmission. With UDP there is a small chance that some packets never arrive at the destination, but in practice very little is lost - certainly not enough that would have any measurable impact on your graphs.

Using with Ruby

TCP Connection

require 'socket'

conn   = '', 2003
conn.puts apikey + ".request.time 1444\n"

UDP Connection

require 'socket'

sock   =
sock.send apikey + ".request.time 1444\n", 0, "", 2003

Using with Python

TCP Connection

import socket
import os

apikey = os.environ['HOSTEDGRAPHITE_APIKEY']
conn   = socket.create_connection(("", 2003))
conn.send("%s.request.time 1444\n" % apikey)

UDP Connection

import socket
import os

apikey = os.environ['HOSTEDGRAPHITE_APIKEY']
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.sendto("%s.request.time 1444\n" % apikey, ("", 2003))

Using with PHP

TCP Connection

$apikey = getenv('HOSTEDGRAPHITE_APIKEY');
$conn   = fsockopen("", 2003);
fwrite($conn, $apikey . ".request.time 1444\n");

UDP Connection

$apikey  = getenv('HOSTEDGRAPHITE_APIKEY');
$sock    = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
$message = $apikey . ".request.time 1444\n";
socket_sendto($sock, $message, strlen($message), 0, "", 2003);

Using with Java

TCP Connection

String apikey = System.getenv("HOSTEDGRAPHITE_APIKEY");
Socket conn   = new Socket("", 2003);
DataOutputStream dos = new DataOutputStream(conn.getOutputStream());
dos.writeBytes(apikey + ".request.time 1444\n");

UDP Connection

String apikey         = System.getenv("HOSTEDGRAPHITE_APIKEY");
DatagramSocket sock   = new DatagramSocket();
InetAddress addr      = InetAddress.getByName("");
byte[] message        = apikey + ".request.time 1444\n".getBytes()
DatagramPacket packet = new DatagramPacket(message, message.length, addr, 2003);

Using with Node.js

TCP Connection

var net    = require('net');
var apikey = process.env.HOSTEDGRAPHITE_APIKEY;

var socket = net.createConnection(2003, "", function() {
   socket.write(apikey + ".request.time 1444\n');

UDP Connection

var dgram  = require('dgram');
var apikey = process.env.HOSTEDGRAPHITE_APIKEY;

var message = new Buffer(apikey + ".request.time 1444\n");
var client = dgram.createSocket("udp4");
client.send(message, 0, message.length, 2003, "", function(err, bytes) {


For more information on the features available within the Hosted Graphite dashboard please see the docs at

The Hosted Graphite dashboard allows you to view all of your created metrics, create custom graphs and display those graphs on a dashboard.

The dashboard can be accessed via the CLI:

$ heroku addons:open hostedgraphite
Opening hostedgraphite for sharp-mountain-4005...

or by visiting the Heroku apps web interface and selecting the application in question. Select Hosted Graphite from the Add-ons menu.


If you want to test how many metrics have been sent, visit your dashboard to see exactly which metrics have been added. Creating a graph with a short timescale (e.g. 30 minutes) will show you what data has been added very recently.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the ‘heroku addons:upgrade’ command to migrate to a new plan.

$ heroku addons:upgrade hostedgraphite:newplan
-----> Upgrading hostedgraphite:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: hostedgraphite:newplan

Removing the add-on

Hosted Graphite can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy hostedgraphite
-----> Removing hostedgraphite from sharp-mountain-4005... done, v20 (free)


All Hosted Graphite support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome - just mail us at or on twitter at @hostedgraphite

Additional resources

Additional resources are available at: