OVH Guides

Use Graphite

Get an overview on how to use Graphite for Metrics

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 these calls:

API Method Supported limitation
/render GET / POST This path does not support pictures generation
/metrics GET
/metrics/find GET
/metrics/index.json GET

How to push data

Graphite Carbon uses 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 supported 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 of 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.

Once it's done, you need to install StatsD. StatsD can be used with a config file as described 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 exposes 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.

Function Supported
averageSeries
absolute
aggregate
aggregateLine
aggregateWithWildcards
alias
aliasByMetric
aliasByNode
aliasSub
averageAbove
averageBelow
averageSeries
averageSeriesWithWildcards
consolidateBy
constantLine
countSeries
cumulative
currentAbove
currentBelow
delay
derivative
diffSeries
divideSeries
drawAsInfinite
exclude
grep
highestAverage
highestCurrent
highestMax
hitcount
integral
interpolate
invert
keepLastValue
limit
logarithm
lowestAverage
lowestCurrent
maxSeries
maximumAbove
maximumBelow
minMax
minSeries
minimumAbove
minimumBelow
multiplySeries
multiplySeriesWithWildcards
offset
perSecond
pow
randomWalk
randomWalkFunction
rangeOfSeries
removeAboveValue
removeBelowValue
removeEmptySeries
scale
scaleToSeconds
seriesByTag
sinFunction
sortByMaxima
sortByMinima
sortByName
sortByTotal
squareRoot
stddevSeries
substr
sumSeries
sumSeriesWithWildcards
summarize
threshold
timeFunction
timeShift
timeSlice
transformNull
unique
aliasByTags
aliasQuery
alpha
applyByNode
areaBetween
asPercent
averageOutsidePercentile
cactiStyle
changed
color
dashed
divideSeriesLists
events
exponentialMovingAverage
fallbackSeries
filterSeries
group
groupByNode
groupByNodes
groupByTags
highest
holtWintersAberration
holtWintersConfidenceArea
holtWintersConfidenceBands
holtWintersForecast
identity
integralByInterval
isNonNull
legendValue
lineWidth
linearRegression
linearRegressionAnalysis
lowest
mapSeries
mostDeviant
movingAverage
movingMax
movingMedian
movingMin
movingSum
movingWindow
nPercentile
nonNegativeDerivative
offsetToZero
percentileOfSeries
pieAverage
pieMaximum
pieMinimum
powSeries
reduceSeries
removeAbovePercentile
removeBelowPercentile
removeBetweenPercentile
roundFunction
secondYAxis
setXFilesFactor
smartSummarize
sortBy
stacked
stddev
timeStack
useSeriesAbove
verticalLine
weightedAverage

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 Grafana's Graphite plugin works, please take a look here.

Go further


These guides might also interest you...