graphite-web render api

Render API

Graphite web 提供了/render API用來生成圖片和獲取原始數據。這個API經過查詢字符串支持各類參數。參數之間經過&進行分割,以下所示:html

&name=value

你能夠經過訪問http://GRAPHITE_HOST:GRAPHITE_PORT/render這個url來確認這個API是否已經運行。若是這個API正常運行,那麼它會返回一個330*250的圖片,圖片內容爲」No Data」,以下圖所示:git

若是這個API正常運行,而且你已經給carbon發送了一些指標數據,那麼就可使用下面的參數來定製你的圖片和獲取原始數據:web

# single server load on large graph

http://graphite/render?target=server.web1.load&height=800&width=600



# average load across web machines over last 12 hours

http://graphite/render?target=averageSeries(server.web*.load)&from=-12hours



# number of registered users over past day as raw json data

http://graphite/render?target=app.numUsers&format=json



# rate of new signups per minute

http://graphite/render?target=summarize(derivative(app.numUsers),"1min")&title=New_Users_Per_Minute

注意:大多數函數和參數是大小寫敏感的,好比說使用&linewidth=2查詢會失敗,正確的參數應該是&lineWidth=2。json

爲了繪製指定的指標圖片,能夠給這個API指定一個或者多個target參數,而且使用from/until來指定一個時間區間。api

target

target參數用來指定一個指標路徑,這個路徑下能夠有一個或者多個指標。你還能夠在這些指標上使用一些處理函數。跨域

指標的路徑使用.號進行分割,好比說servers.ix02ehssvc04v.cpu.total.user緩存

 

路徑和通配符

指標的路徑也可使用下面的語法來定義,這可使你在一個路徑下定義多個指標:服務器

1:*號。*號能夠表明0個或者多個字符,它的使用是沒有限制的,你能夠在一個路徑裏面使用多個*號。例如:servers.ix*ehssvc*v.cpu.total.*這個路徑會返回全部服務器的全部符合這個路徑結構的指標數據。微信

2:[…]字符區間,若是路徑裏面有一個字符在這個字符區間裏面,那麼這個路徑就能夠匹配。app

字符區間由兩個字符加一個-號組成。意思就是說全部在這兩個字符中間的字符都會被匹配。中括號裏面能夠定義多個字符區間,好比說foo[a-z0-9]bar 就能夠匹配到 foopbar, foo7bar。

若是中括號內的字符不能被解析爲一個字符區間,那麼就會被解析爲一個字符列表,全部在這個字符列表裏面的字符都會被匹配到。好比foo[bc]ar 就能夠匹配到foobar and foocar。若是你要匹配一個-號把它放在字符區間或者列表的開頭或者結尾,那麼它就不會被解析爲字符區間標誌了。

3:值列表。大括號裏面使用逗號分開的值,好比{foo,bar,...},會被當成值列表。

好比servers.ix01ehssvc04v.cpu.total.{user,system,iowait}將能夠匹配製定服務器的user,system和iowait三個指標

注意:

全部的通配符只能使用在單個path裏面,不能跨.號使用。所以servers.* 將不能匹配 servers.ix02ehssvc04v.cpu.total.user, 可是servers.*.*.*.*能夠匹配servers.ix02ehssvc04v.cpu.total.user。

例子

 下面的例子將畫一個圖:

&target=company.server05.applicationInstance04.requestsHandled

假設咱們每臺服務器上跑了有四個同樣的應用程序,那麼下面這個例子將畫出四個圖:

&target=company.server05.applicationInstance*.requestsHandled

假設你有十臺服務器,那麼下面的例子將畫出40個圖:

&target=company.server*.applicationInstance*.requestsHandled

你也能夠在繪圖以前,在多個指標上使用多個函數進行處理,下面的例子將畫出一個平均線

&target=averageSeries(company.server*.applicationInstance.requestsHandled)

可使用多個target參數,這樣的話你就能夠把多個相關的指標畫在一張圖上:

&target=company.server1.loadAvg&target=company.server1.memUsage

注意:

若是你同時畫了十張圖,那麼圖表可能顯示不出來,相關細節你能夠參考hideLegend 參數。

from/until

這兩個可選參數,用來爲圖表指定一個相對的或者絕對的時間區間。From指定開始時間,until指定結束時間。若是沒有指定from參數,那麼默認是繪畫過去的24小時的指標。若是until參數沒有指定,那麼默認使用當前時間做爲結束時間。

這兩個參數可使用兩種方式來指定

&from=-RELATIVE_TIME
&from=ABSOLUTE_TIME

RELATIVE_TIME是一個從如今開始的時間長度。使用RELATIVE_TIME的時候,前面必須加上-符號,後面跟上時間單位。合法的時間單位以下表所示:

Abbreviation

Unit

s

Seconds

min

Minutes

h

Hours

d

Days

w

Weeks

mon

30 Days (month)

y

365 Days (year)

ABSOLUTE_TIME使用HH:MM_YYMMDD, YYYYMMDD, MM/DD/YY格式來指定時間。

Abbreviation

Meaning

HH

Hours, in 24h clock format. Times before 12PM must include leading zeroes.

MM

Minutes

YYYY

4 Digit Year.

MM

Numeric month representation with leading zero

DD

Day of month with leading zero

&from and &until能夠組合使用ABSOLUTE_TIME和RELATIVE_TIME

例子

&from=-8d&until=-7d
(shows same day last week)

&from=04:00_20110501&until=16:00_20110501
(shows 4AM-4PM on May 1st, 2011)

&from=20091201&until=20091231
(shows December 2009)

&from=noon+yesterday
(shows data since 12:00pm on the previous day)

&from=6pm+today
(shows data since 6:00pm on the same day)

&from=january+1
(shows data since the beginning of the current year)

&from=monday
(show data since the previous monday)

template

target參數裏面可使用template函數,當使用template函數的時候,指標路徑裏面能夠包含變量,變量的值經過template參數指定。

例子以下:

&target=template(hosts.$hostname.cpu)&template[hostname]=worker1

也能夠爲template參數指定默認值:

&target=template(hosts.$hostname.cpu, hostname="worker1")

變量也能夠沒有名字,而經過佔位符指定:

&target=template(hosts.$1.cpu, "worker1")

&target=template(hosts.$1.cpu, "worker1")&template[1]=worker*

例子中的$1就是佔位符。

除了路徑替換,變量也能夠用於數字和字符串:

&target=template(constantLine($number))&template[number]=123

&target=template(sinFunction($name))&template[name]=nameOfMySineWaveMetric

數據顯示格式

除了把數據渲染成圖像,這個API還能夠把數據生成帶嵌入式元數據的SVG,PDF或者返回多種格式的原始數據,以提供外部的圖形化,分析和監控需求。

format

控制數據的返回格式,對url裏面全部的target生效。

例子:

&format=png

&format=raw

&format=csv

&format=json

&format=svg

&format=pdf

png返回png圖像,圖像大小由width和height參數指定

raw返回每一個數據點的值,返回的格式以下:

<target name>,<start timestamp>,<end timestamp>,<series step>|[data]*

例子:

nms.usage.mem,1467274320,1467276120,60|None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,66.0,60.0,81.0,None,34.0,62.0,61.0,93.0

csv按csv格式返回數據,這種格式的數據能夠導入電子表格或者在腳本中處理

entries,2011-07-28 01:53:28,1.0

entries,2011-07-28 01:53:29,2.0

entries,2011-07-28 01:53:30,3.0

entries,2011-07-28 01:53:31,5.0

entries,2011-07-28 01:53:32,6.0

Json返回json格式的數據,可使用jsonp選項對json格式的數據進行包裝以支持跨域訪問。

[{"target": "nms.usage.mem", "datapoints": [[null, 1467275400], [null, 1467275460], [null, 1467275520], [null, 1467275580], [66.0, 1467275640], [60.0, 1467275700], [81.0, 1467275760], [null, 1467275820], [34.0, 1467275880], [62.0, 1467275940], [61.0, 1467276000], [93.0, 1467276060], [95.0, 1467276120], [13.0, 1467276180], [90.0, 1467276240], [89.0, 1467276300], [74.0, 1467276360], [45.0, 1467276420], [46.0, 1467276480], [78.0, 1467276540], [null, 1467276600], [14.0, 1467276660], [99.0, 1467276720], [7.0, 1467276780], [78.0, 1467276840], [6.0, 1467276900], [5.0, 1467276960], [16.0, 1467277020], [15.0, 1467277080], [null, 1467277140]]}]

Pdf返回pdf文件,文件大小由width和height參數指定

圖像參數

areaAlpha

默認值:1.0

合法的取值是0.0~1.0之間的浮點數值

當使用areaMode參數時,使用這個參數設置相關區域的alpha值。

areaAlpha=0.2

areaAlpha=0.5

areaMode

默認值:none

設置這個參數,能夠把圖像下方的區域進行填充,填充的顏色跟線的顏色一致。可使用areaAlpha參數進行半透明填充。使用下面幾個參數來指定填充模式:

none:不進行填充

first:填充第一個指標線的下方區域

all:填充全部指標下方的區域

stacked:堆疊填充

bgcolor

默認值:Template.conf文件裏面[default]下面指定的值

能夠指定的值有如下一些:

Color Names

RGB Value

black

0,0,0

white

255,255,255

blue

100,100,255

green

0,200,0

red

200,0,50

yellow

255,255,0

orange

255, 165, 0

purple

200,100,255

brown

150,100,50

aqua

0,150,150

gray

175,175,175

grey

175,175,175

magenta

255,0,255

pink

255,100,100

gold

200,200,0

rose

200,150,200

darkblue

0,0,255

darkgreen

0,255,0

darkred

255,0,0

darkgray

111,111,111

darkgrey

111,111,111

RGB值可使用#RRGGBB[AA]的格式來設置,RR,GG和BB都由兩個16進制的數構成。AA是可選的,可使用AA來設置alpha值,FF表明徹底不透明,而00表明全透明。

例子:

&bgcolor=blue

&bgcolor=2222FF

&bgcolor=5522FF60

bgcolor=5522FF60

cacheTimeout

默認值:local_setting.py文件裏面DEFAULT_CACHE_DURATION的值

圖片的緩存時間,單位是秒

colorList

默認值:Template.conf文件裏面[default]下面指定的值

使用逗號分隔開的一系列的顏色值或者RGB值。若是設置了這個參數,那畫線條的時候,會按順序使用裏面的顏色。若是線條數,多於給定的顏色數,那麼顏色會按順序循環使用。

例子:

&colorList=green,yellow,orange,red,purple,DECAFF

&colorList=FF000055,00FF00AA,DECAFFEF

drawNullAsZero

默認值:false

在渲染圖片的時候,把全部爲null的值渲染成0。

fgcolor

默認值:Template.conf文件裏面[default]下面指定的值

設置前景色,這個顏色會影響到圖片標題,圖例文字,座標軸標籤

fontBold

默認值:Template.conf文件裏面[default]下面指定的值

若是設置爲true,那會把字體都變成粗體

例子:

&fontBold=true

fontItalic

默認值:Template.conf文件裏面[default]下面指定的值

若是設置爲true,那會把字體都變成斜體

例子:

&fontItalic =true

fontName

默認值:Template.conf文件裏面[default]下面指定的值

改變渲染圖片使用的字體,使用的字體必須已經安裝在graphit安裝的機器上。

例子:

&fontName=FreeMono

fontSize

默認值:Template.conf文件裏面[default]下面指定的值

改變字體的大小,必須是一個正的浮點型數據或者整形數據,必須大於1,默認值是10。

例子:

&fontSize=8

graphOnly

默認值:false

只展現圖表區域,沒有網格線,座標軸和圖例

graphType

默認值:line

設置圖片的渲染類型,目前只支持兩種圖片類型:

line:折線圖

pie:餅圖

hideLegend

默認值:<unset>

若是設置爲true,那麼就不會繪製圖例。若是設置爲false,則繪製圖例。若是不設置這個值,會使用local_setting.py裏面設置的LEGEND_MAX_LINES這個值來決定是否繪製圖例。

提示:若是這個只被設置爲false,那麼height參數可能須要增長以用來容納圖例

例子:

&hideLegend=false

hideAxes

默認值:false

若是設置爲true,那麼x和y座標就不會被繪製出來

例子:

&hideAxes=true

hideXAxes

默認值:false

若是設置爲true,那麼x座標就不會被繪製出來

hideYAxes

默認值:false

若是設置爲true,那麼y座標就不會被繪製出來

hideGrid

默認值:false

若是設置爲true,那麼網格線就不會被繪製出來

例子:

&hideGrid=true

height

默認值:250

設置圖片的高度,單位是像素

例子:

&width=650&height=250

lineMode

默認值:slope

設置線條的類型,有如下幾種類型可使用:

slope: Slope line mode draws a line from each point to the next. Periods with Null values will not be drawn

staircase: Staircase draws a flat line for the duration of a time period and then a vertical line up or down to the next value

connected: Like a slope line, but values are always connected with a slope line, regardless of whether or not there are Null values between them

例子:

&lineMode=staircase

Linewidth

默認值:1.2

能夠設置爲任意的浮點型數或者整形數,表明線條的寬度,單位是像素。

例子:

&lineWidth=5

localOnly

默認值:False

若是設置爲True,則只訪問本地graphite服務器裏面的指標,不訪問遠端graphite服務器裏面的指標。

majorGridLineColor

默認值:Template.conf文件裏面[default]下面指定的值

設置網格線的顏色

例子:

&majorGridLineColor=FF22FF

margin

默認值:10

設置圖片周圍的邊距,單位是像素。

例子:

&margin=20

maxDataPoints

當返回json格式的數據時,可使用這個參數限制返回的最大數據點個數。

若是選定時間段內的數據點數大於這個值,則整個時間段內的數據點會進行合併操做

minorGridLineColor

默認值:Template.conf文件裏面[default]下面指定的值

設置minor grid line的顏色

例子:

&minorGridLineColor=darkgrey

minorY

Sets the number of minor grid lines per major line on the y-axis.

例子:

&minorY=3

noCache

默認值:False

若是設置爲true,則禁用圖片緩存功能

template

默認值:default

用來指定一個定義在graphTemplates.conf裏面的模板,模板裏面定義了一下默認的顏色和圖片風格。

例子:

&template=plain

title

默認值:不設置

爲圖像設置一個標題

例子:

&title=test

tz

默認值:定義在local_settings.py文件裏面的時區

例子:

&tz=America/Los_Angeles

&tz=UTC

能夠經過修改local_settings.py文件來修改默認時區

uniqueLegend

默認值:false

只顯示惟一的legend,去掉重複的

vtitle

默認值:不設置

設置y軸的名稱,若是沒有設置,那麼y軸上就沒有名稱

例子:

&vtitle=number

width

默認值:330

設置圖片的寬度

例子:

&width=650&height=250

xFormat

默認值:基於x軸的時間長度動態設置

Sets the time format used when displaying the X-axis. See datetime.date.strftime() for format specification details.

yAxisSide

默認值:left

設置y軸的位置,可使用的值有left和right

例子:

yAxisSide=right

yMin

默認值:指標數據裏面的最小值

設置y軸的最小值,能夠是任意的浮點型或者整形數

例子:

&yMin=0

yMax

默認值:指標數據裏面的最大值

設置y軸的最大值,能夠是任意的浮點型或者整形數

例子:

&yMax=100

yStep

默認值:根據指標數據動態設置

設置y軸的步長

&yStep=5

-----------------------------------------------------

歡迎關注個人微信公衆號 ^_^

相關文章
相關標籤/搜索