Securely sending metric data to Hosted Graphite

October 9, 2017

Security is a top priority at Hosted Graphite. To make sure your custom metrics arrive safely, we offer several options for their transport. In addition to the plaintext TCP or UDP carbon-format interfaces, you can send your metric data in the same format via TCP over TLS, and HTTPS. If you'd like a simpler, faster option for securely sending metric data, install the Hosted Graphite agent which accepts metric data over the `localhost` interface, buffers it in case of network disruptions, and forwards it over HTTPS. Read on for a closer look at the agent and other ways to send your custom metric data securely to Hosted Graphite.

To follow along with this article, get into the Hosted Graphite free trial here. You can start to send data to Graphite by just downloading the agent and installing it on your system. There's a bunch of other ways to send metrics as well, such as our AWS add-on, or StatsD. Get into the Hosted Graphite app and check it out! Feel free to reach out to us and ask any questions you might have!

How we differ from standard Graphite

A diagram showing the difference how metrics are being sent between Hosted Graphite and the standard Graphite

First, it’s useful to make the distinction between our service and standard Graphite. When you self host Graphite, the main methods for sending metric data are the plaintext carbon line protocol over TCP and UDP, and the carbon pickle protocol over TCP. Hosted Graphite supports all those, and adds a few secure options:

  • Our local machine agent, which submits to us over HTTPS
  • Carbon line protocol over TCP, wrapped in TLS
  • Carbon pickle protocol over TCP, wrapped in TLS
  • Carbon line protocol, wrapped in HTTPS

If your metric data is confidential, we recommend you choose one of these secure options. Below, we'll explore these options in detail.

For a more in depth analysis of how Graphite and Hosted Graphite are different, check out this article Hosted Graphite isn't Graphite.

The agent

By far the most straightforward way to securely send your metrics is by installing the Hosted Graphite agent. Once installed, it offers the standard Graphite carbon line TCP and UDP interfaces on the `localhost` interface, and it automatically forwards to Hosted Graphite over HTTPS. The agent also automatically collects information about the server it's running on, and you get a system metrics dashboard inside Hosted Graphite for each server the agent is running on, without having to configure or do anything extra.

We’ve built it to be quick to set up and easy-to-use so you can have it up and running in no time. View the full getting started guide in our docs. The best way to test our the agent is to get into the Hosted Graphite free trial and send data to Graphite!


A simple way to securely send metrics to us is via HTTPS. If you’re using cURL you can post your metrics in the carbon line format to the following URL:

(You can find your API key on your account page)


curl --data-binary " 1.2"

For more user-friendly testing, you might prefer to use a tool like Postman or it’s chrome extension. If you're using Postman, you'll need to set up basic authentication using the API key as the username and no password. The URL would then be:

For a full run down on how to keep your monitoring infrastructure secure, check out this guide here. Securely sending data to Graphite requires a few considerations, HTTPS being one of the most significant factors.

TCP over TLS

Where the overhead of making full HTTPS requests in your application doesn’t make sense, sending metrics via TCP over TLS is another secure alternative. As we support TLS on all our TCP endpoints, it allows you to use a lightweight protocol while having the advantage of being transport encrypted. To start sending metrics this way, ensure each metric name is prefixed by your API key, then send your metric(s) using the carbon line protocol as normal.

We provide this endpoint on port 20030. The following shell example shows how to send a metric via TCP/TLS using ncat:

`echo " 1.2" | ncat --ssl 20030`

Remember, you don’t need to create a new connection for each metric (and it’s not recommended): you can put multiple metrics on separate lines. For more information, view the getting started guide in docs.


If you don't want to configure your application to manage a TLS connection, you can use a tool like stunnel to set up your own local endpoint, so that all the transport encryption to Hosted Graphite is handled for you and your application isn't burdened with having to manage the secure connection itself. Using this method, you could start encrypting your data today without any changes to how you handle graphite connections in your software.

View our docs for full steps on installing and configuring stunnel.

Forwarding your traffic securely through an existing carbon-relay

If you're already running a carbon-relay daemon for your existing Graphite infrastructure, you can configure the relay to forward your traffic to Hosted Graphite. If you insert stunnel into this mix, then you also get the benefit of securing that traffic without having to modify anything about where your applications send their metric data.


How you choose to send metrics depends on your particular situation. Something to bear in mind is that if your application connects to us over TCP or HTTP, those calls can be blocking/synchronous, which could have a performance impact on your application. To work around this, we suggest sending locally to our agent over UDP, and letting it take care of non-blocking forwarding, and doing it securely, which gives you the best of both worlds.

More information:

Here at Hosted Graphite we take security seriously, so reach out to us if you have any questions surrounding security. Sending data to Graphite requires careful planning, but with Hosted Graphite we take care of everything for you. We'll get your data sending securely and without error. The first step is to start up your 14-day Hosted Graphite free trial. Get into the app and install the Hosted Graphite agent. Your metrics will start sending automatically, and you'll be able to see them on awesome Grafana Dashboards right away!

Dan Fox

SRE at Hosted Graphite.

Related Posts

See why thousands of engineers trust Hosted Graphite with their monitoring