Graphite HTTP API

Grafana Cloud

Graphite HTTP API

The HTTP API is the same as that of Graphite, with the addition of ingestion, authentication, series lineage, meta tags and storage-aggregation/storage-schemas.conf endpoints.

First of all, there are two endpoints you will be talking to. They are provided on your grafana.com Hosted Metrics instance details page.

They will look something like:

<ingest_endpoint> : https://something.grafana.net/metrics
<query_endpoint> : https://something.grafana.net/graphite

Furthermore, you will need to provision API keys to talk to the API. Each key will be of one of these types:

Viewer
MetricsPublisher
Editor
Admin

A “Viewer” key can only be used to execute queries, while a “MetricsPublisher” key can only be used to push metrics into the platform. “Editor” and “Admin” keys can be used for both pushing metrics and performing queries.

API keys can be provisioned on your Grafana.com organization page under “Security > API Keys”.

Authentication

Authentication differs depending on whether your instance is provisioned on a dedicated or a shared cluster. How to tell the difference? On your Grafana.com instance details page, if your query and metrics endpoint look generic like this:

https://graphite-us-central1.grafana.net/graphite
https://graphite-us-central1.grafana.net/metrics

Then you are on a shared cluster. However if your URL’s look more like this:

https://tsdb-123-your-company-name.hosted-metrics.grafana.net/graphite
https://tsdb-123-your-company-name.hosted-metrics.grafana.net/metrics

Then you are on a dedicated cluster.

You have several ways to authenticate:

For dedicated clusters, any of these HTTP headers will work:

Authorization: Basic base64(api_key:<api key>)
Authorization: Bearer <api key>
Authorization: Bearer api_key:<api key>

For shared clusters, use any of these HTTP headers:

Authorization: Basic base64(<instance id>:<api key>)
Authorization: Bearer <instance id>:<api key>

Note that you can find the instance ID as the username in the “Using Grafana with Hosted Metrics” section of your Grafana.com instance details page

So essentially you can use basic auth with username “api_key” (for dedicated clusters) or your instance ID (for shared clusters) and password the api key that you provisoned

You can also use a bearer token in “username:password” format (if username not specified, “api_key” is assumed)

Common Request Parameters

Many of the API methods involve using Graphite patterns (queries), tag queries and the standard Graphite from/to syntax.

Graphite Patterns

Graphite patterns are queries that involve glob patterns (*, {}, [], ?).

Tag Expressions

Tags expressions are strings, and may have the following formats:

tag=spec    tag value exactly matches spec
tag!=spec   tag value does not exactly match spec
tag=~value  tag value matches the regular expression spec
tag!=~spec  tag value does not match the regular expression spec

Any tag spec that matches an empty value is considered to match series that don’t have that tag, and at least one tag spec must require a non-empty value. Regular expression conditions are treated as being anchored at the start of the value.

From/To (Until)

Graphite from/to

Endpoints

Adding New Data: Posting To `/metrics`

The main entry point for any publisher to publish data to, be it carbon-relay-ng, or any other script or application such as the hosted-metrics-sender-example

Method: POST
API key type: any (including Viewer)

Headers

Authorization: header is required (see authentication section above)
Content-Type: supports 3 values:
- application/json: the simplest one, and the one used here
- rt-metric-binary: same datastructure, but messagepack encoded. (see the MetricData Marshal/Encode methods)
- rt-metric-binary-snappy: same as above, but snappy compressed.

Data Format

Each metricpoint message can have the following properties:

name     // Graphite style name (required)
interval // the resolution of the metric in seconds (required)
value    // float64 value (required)
time     // unix timestamp in seconds (required)
tags     // list of key=value pairs of tags (optional)

Example

timestamp_now_rounded=$(($(date +%s) / 10 * 10))
timestamp_prev_rounded=$((timestamp_now_rounded - 10))

curl -X POST -H "Authorization: Bearer <key> -H "Content-Type: application/json" "<ingest_endpoint>" -d '[{
    "name": "test.metric",
    "interval": 10,
    "value": 12.345,
    "time": '$timestamp_prev_rounded'
},
{
    "name": "test.metric",
    "interval": 10,
    "value": 12.345,
    "time": '$timestamp_now_rounded'
},
{
    "name": "test.metric.tagged",
    "interval": 10,
    "value": 1,
    "tags": ["foo=bar", "baz=quux"],
    "time": '$timestamp_prev_rounded'
},
{
    "name": "test.metric.tagged",
    "interval": 10,
    "value": 2,
    "tags": ["foo=bar", "baz=quux"],
    "time": '$timestamp_now_rounded'
}
]'

Tag Exploration

Count tag values With `/tags/terms`

Returns count of series for each tag value which matches tag queries for a given set of tag keys.

Method: GET or POST
API key type: any (including MetricsPublisher)

Headers

Authorization: Bearer <api-key> required

Parameters

expr (required): a list of tag expressions
tags: a list of tag keys for which to count values series

Example

curl -H "Authorization: Bearer <key>" "<query_endpoint>/tags/terms?expr=datacenter=dc1&expr=server=web01&tags=rack"

{
  "totalSeries": 5892,
  "terms": {
    "rack": {
      "a1": 2480,
      "a2": 465,
      "b1": 2480,
      "b2": 467
    }
  }
}

Render `/render` (return data for a given query)

Graphite-web-like api. It can return JSON, pickle or messagepack output

Method: GET or POST (recommended. as GET may result in too long URL’s)
API key type: any (viewer, publisher, editor)

Headers

Authorization: Bearer <api-key> required

Parameters

maxDataPoints: int (default: 800)
target: mandatory. one or more metric names or patterns.
from: see timespec format (default: 24h ago) (exclusive)
to/until: see timespec format(default: now) (inclusive)
format: json, msgp, pickle, csv or msgpack (default: json) (note: msgp and msgpack are similar, but msgpack is for use with Graphite)
meta: Use ‘meta=true’ to enable performance and series lineage metadata in the response body. Only supported for json responses. See below for more information.

Data queried for must be stored under the given org or be public data (see multi-tenancy)

Example

curl -H "Authorization: Bearer <key>" "<query_endpoint>/render?target=statsd.fakesite.counters.session_start.*.count&from=-3h&to=-2h"

Adjust storage-schemas.conf and storage-aggregation.conf

Grafana Cloud Graphite V5 allows for dynamic changing of both the graphite schemas and aggregation configuration. When interval data or rollups are poorly configured (e.g. defaults not matching the real data or their intended use) this can result in suboptimal visualizations. By correcting the configuration you can fix the problem. Unlike Graphite, changes are applied automatically retroactively without any loss of information. You can post as many changes as needed. If you do not update this configurations, the default Grafana Cloud settings will be applied instead.

Carbon-relay-NG version 1.2 or later will automatically push both of these files for you

Carbon-relay-ng is the recommended way of publishing these files, but you can manually use this endpoint when:

you haven’t upgraded your relay yet.
you want to experiment iteratively without having to repeatedly restart your relay.

There are two URL paths:

/graphite/config/storageSchema for posting storage-schemas.conf
/graphite/config/storageAggregation for posting storage-aggregation.conf
Method: POST

Headers

Authorization: Bearer <api-key> required

Parameters

None. the body is the file contents

Example

curl -H "Authorization: Bearer <key>" "<query_endpoint>/config/storageSchema" --data-binary '@<path-to-your-storage-schemas.conf>'
curl -H "Authorization: Bearer <key>" "<query_endpoint>/config/storageAggregation" --data-binary '@<path-to-your-storage-aggregation.conf>'

Graphite HTTP API

Authentication

Common Request Parameters

Graphite Patterns

Tag Expressions

From/To (Until)

Endpoints

Adding New Data: Posting To /metrics

Headers

Data Format

Example

Tag Exploration

Count tag values With /tags/terms

Headers

Parameters

Example

Render /render (return data for a given query)

Headers

Parameters

Example

Adjust storage-schemas.conf and storage-aggregation.conf

Headers

Parameters

Example

Related documentation

Related resources from Grafana Labs

Adding New Data: Posting To `/metrics`

Count tag values With `/tags/terms`

Render `/render` (return data for a given query)