Mon compte clientContact commercialWebmailOVHcloud Blog

Bienvenue chez OVHcloud !

Identifiez-vous pour commander, gérez vos produits et services et suivre vos commandes

Me connecter
Documentation OVH

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 this 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 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.

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

Go further


Cette documentation vous a-t-elle été utile ?

Génial ! Ravi d'avoir pu vous aider.

Images, contenu, structure... N'hésitez pas à nous dire pourquoi afin de la faire évoluer ensemble !

Merci beaucoup pour votre aide ! Vos retours seront étudiés au plus vite par nos équipes..


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