Use Graphite

Last updated 31th December, 2019

Objective

Graphite is a Time Series platform with analytics capabilities. In this guide, you will learn how to use Graphite protocol with Metrics.

Requirements

• a valid OVH Metrics account.

Instructions

Compatibility

The Graphite API documentation is available at http://graphite-api.readthedocs.io/en/latest/api.html.

We are currently supporting this calls:

How to push data

Graphite Carbon use a push-based approach using a TCP listener to gather metrics. We developed open-source tools called Beamium and Fossil in order to push metrics to Metrics Data Platform. Please see the dedicated guide to use Beamium and Fossil github repository.

The Graphite protocol is support on the Metrics Data Platform via a TCP connection or via an HTTP request. You can use the same syntax as defined in Hosted Graphite.

In this part og the guide, you will learn how to send Graphite's metrics to Metrics Data Platform.

Via a TCP connection

You can use the same syntax as defined in Hosted Graphite. You need to ensure each metrics names are prefixed by a valid Metric token and an "@.", like this:

TOKEN@.metricname value [timestamp]

Where TOKEN is the write token of your Metrics Data Platform application. You can put multiple metrics on separate lines. The timestamp is optional.

Host: graphite.REGION.metrics.ovh.net, Port (no SSL): 2003, Port (with SSL): 20030

The following example shows how to send a single metric to the Metrics gra1 REGION using netcat on linux:

echo "TOKEN@.tcp_metric 14.2 1546420308000" | ncat --ssl graphite.gra1.metrics.ovh.net 20030

Via StatsD in TCP

StatsD is a network daemon. It listens for statistics such as counters and timers sent via UDP or TCP. You can use StatsD to perform metrics aggregations before sending them to the Metrics Data Platform.

You need to install StatsD, once it's done. StatsD can be used with a config file as describe below.

{
  graphitePort: 2003
, graphiteHost: "graphite.gra1.metrics.ovh.net"
, port: 8125
, backends: [ "./backends/graphite" ]
,  graphite: {
    legacyNamespace: false,
    globalPrefix: "TOKEN@"
  }
}

TOKEN is the write token of your Metrics Data Platform application.

Via an HTTP Post

You can use the same syntax as defined in Hosted Graphite. You need to ensure each metrics names have a valid Graphite format:

metricname value [timestamp]

You can put multiple metrics on separate lines. The timestamp is optional. You can use the following URL to push your metrics on our Graphite endpoint: https://graphite.REGION.metrics.ovh.net/api/vi/sink

The following example shows how to send a single metric on the gra1 REGION using the cURL command on linux:

curl https://u:TOKEN@graphite.gra1.metrics.ovh.net/api/v1/sink --data-binary "https_metric 14.2 1546420308000"

Where TOKEN is the write token of your Metrics Data Platform application.

How to query

Graphite expose an HTTP api in order to query time series. It offers basic query capabilities and a way to use functions on time series. All query documentation is available here.

For example to retrieve your data, you can simply execute the following HTTP request using cURL.

curl 'https://u:READ_TOKEN@graphite.REGION.metrics.ovh.net/render?target=SERIES_NAME'

where:

• READ_TOKEN is your read token available on your OVH Metrics account. You can get the list here.
• REGION is the region where metrics is available. For example, gra1.
• SERIES_NAME is the series name to retrieve. It can be for example os.cpu.

Special use case

When using a function the time series must be set between double quotes ". This behaviour will be replaced in the future in order to be fully compliant with Graphite Carbon.

Graphite functions

Table of function which are supported by Metrics Data Platform.

Graphite example queries

Here, you will find a valid query example.

For example this request will add 2 os.cpu series from host 1 and host 2.

curl 'https://u:READ_TOKEN:@graphite.REGION.metrics.ovh.net/render?target=sumSeries("os.cpu;host=1", "os.cpu;host=1")'

Grafana

When you are using Graphite tags with Grafana, you should put between double " your time series name with tags in order to work with Metrics Data Platform.

For example this request will add 2 os.cpu series from host 1 and host 2.

curl 'https://u:READ_TOKEN:@graphite.REGION.metrics.ovh.net/render?target=sumSeries("os.cpu;host=1", "os.cpu;host=1")'

This case appears when you are using functions on Grafana. If you want to discover how works Grafana's Graphite plugin, please take a look here.

Go further

• Documentation: Guides
• Vizualize your data: https://grafana.metrics.ovh.net/login
• Community hub: https://community.ovh.com
• Create an account: Try it free!
• Gitter: Gitter

Ces guides pourraient également vous intéresser...