HTTP integration

You can send custom metrics through various data collectors/aggregators.

Data format

The format of a payload looks like this:

name: Description and namespace for the metric.
tags: Key/Value string pairs and usually used to identify the metric.
fields: Key/Value pairs that are typed and usually contain the metric data.
timestamp: Date and time associated with the fields.


An example of it in JSON serialization looks like the one you sent in the Getting started tutorial:

  "name": "tutorial",
  "timestamp": 1628044399,
  "tags": {
    "color": "red" 
  "fields": { 
    "cpu": 12.66 

We are actively adding new serialization formats.


Send them as POST requests to with your API key as the authorization header:


Authorization: Bearer <api-token>

You can find your API token by going into the HTTP integration modal.

HTTP integrationHTTP integration

HTTP integration

API keyAPI key

API key

Open source collectors

One of the most popular open-source data collectors out there is Telegraf.

The easiest way to get started with Telegraf is to start sending CPU readings from a machine.

  1. Install it here for the platform of the machine you want to collect data from.
  2. Download or copy the contents of this gist. It is a configuration template that'll tell Telegraf to collect CPU data every 10s and send to Terrastruct in JSON. Don't forget to replace the API key with your own.


Telegraf configuration

You can view the full configuration for Telegraf here.

  1. Run Telegraf with the configurations from (2). Platform-specific instructions for running Telegraf found here.
  2. Explore the various plugins that let you collect more than CPU data. For example, Telegraf has a Statsd input plugin that lets your application metrics to be sent via Statsd to Terrastruct (example config here).

With that, you should start to see metrics streaming in from Telegraf!