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.

How we differ from standard Graphite

How we differ from 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.

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.


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:

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:

Dan Fox

SRE at Hosted Graphite.

Related Posts

See why thousands of engineers trust Hosted Graphite with their monitoring