This add-on is operated by Hosted Graphite

Application, System, Infrastructure Metrics | Graphite | Grafana

Last updated April 01, 2022

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

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:

$ 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
deadbeef-dead-beef-fade-feedbeefdead

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.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command to add the HOSTEDGRAPHITE_APIKEY values retrieved from heroku config to your .env file.

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

For more information, see the Heroku Local article.

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.

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'

apikey = ENV['HOSTEDGRAPHITE_APIKEY']
conn   = TCPSocket.new 'carbon.hostedgraphite.com', 2003
conn.puts apikey + ".request.time 1444\n"
conn.close

UDP Connection

require 'socket'

apikey = ENV['HOSTEDGRAPHITE_APIKEY']
sock   = UDPSocket.new
sock.send apikey + ".request.time 1444\n", 0, "carbon.hostedgraphite.com", 2003

Using with Python

TCP Connection

import socket
import os

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

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, ("carbon.hostedgraphite.com", 2003))

Using with PHP

TCP Connection

<?
$apikey = getenv('HOSTEDGRAPHITE_APIKEY');
$conn   = fsockopen("carbon.hostedgraphite.com", 2003);
fwrite($conn, $apikey . ".request.time 1444\n");
fclose($conn);
?>

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, "carbon.hostedgraphite.com", 2003);
?>

Using with Java

TCP Connection

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

UDP Connection

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

Using with Node.js

TCP Connection

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

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

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, "carbon.hostedgraphite.com", function(err, bytes) {
    client.close();
});

Dashboard

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 Dashboard and selecting the application in question. Select Hosted Graphite from the Add-ons menu.

Troubleshooting

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

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.

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

Support

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 team@hostedgraphite.com or on twitter at @hostedgraphite

Additional resources

Additional resources are available at:

• Hosted Graphite docs