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參數用來指定一個指標路徑,這個路徑下能夠有一個或者多個指標。你還能夠在這些指標上使用一些處理函數。跨域
指標的路徑使用.號進行分割,好比說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參數,那麼默認是繪畫過去的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)
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或者返回多種格式的原始數據,以提供外部的圖形化,分析和監控需求。
控制數據的返回格式,對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參數指定
默認值:1.0
合法的取值是0.0~1.0之間的浮點數值
當使用areaMode參數時,使用這個參數設置相關區域的alpha值。
areaAlpha=0.2
areaAlpha=0.5
默認值:none
設置這個參數,能夠把圖像下方的區域進行填充,填充的顏色跟線的顏色一致。可使用areaAlpha參數進行半透明填充。使用下面幾個參數來指定填充模式:
none:不進行填充
first:填充第一個指標線的下方區域
all:填充全部指標下方的區域
stacked:堆疊填充
默認值: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
默認值:local_setting.py文件裏面DEFAULT_CACHE_DURATION的值
圖片的緩存時間,單位是秒
默認值:Template.conf文件裏面[default]下面指定的值
使用逗號分隔開的一系列的顏色值或者RGB值。若是設置了這個參數,那畫線條的時候,會按順序使用裏面的顏色。若是線條數,多於給定的顏色數,那麼顏色會按順序循環使用。
例子:
&colorList=green,yellow,orange,red,purple,DECAFF &colorList=FF000055,00FF00AA,DECAFFEF
默認值:false
在渲染圖片的時候,把全部爲null的值渲染成0。
默認值:Template.conf文件裏面[default]下面指定的值
設置前景色,這個顏色會影響到圖片標題,圖例文字,座標軸標籤
默認值:Template.conf文件裏面[default]下面指定的值
若是設置爲true,那會把字體都變成粗體
例子:
&fontBold=true
默認值:Template.conf文件裏面[default]下面指定的值
若是設置爲true,那會把字體都變成斜體
例子:
&fontItalic =true
默認值:Template.conf文件裏面[default]下面指定的值
改變渲染圖片使用的字體,使用的字體必須已經安裝在graphit安裝的機器上。
例子:
&fontName=FreeMono
默認值:Template.conf文件裏面[default]下面指定的值
改變字體的大小,必須是一個正的浮點型數據或者整形數據,必須大於1,默認值是10。
例子:
&fontSize=8
默認值:false
只展現圖表區域,沒有網格線,座標軸和圖例
默認值:line
設置圖片的渲染類型,目前只支持兩種圖片類型:
line:折線圖
pie:餅圖
默認值:<unset>
若是設置爲true,那麼就不會繪製圖例。若是設置爲false,則繪製圖例。若是不設置這個值,會使用local_setting.py裏面設置的LEGEND_MAX_LINES這個值來決定是否繪製圖例。
提示:若是這個只被設置爲false,那麼height參數可能須要增長以用來容納圖例
例子:
&hideLegend=false
默認值:false
若是設置爲true,那麼x和y座標就不會被繪製出來
例子:
&hideAxes=true
默認值:false
若是設置爲true,那麼x座標就不會被繪製出來
默認值:false
若是設置爲true,那麼y座標就不會被繪製出來
默認值:false
若是設置爲true,那麼網格線就不會被繪製出來
例子:
&hideGrid=true
默認值:250
設置圖片的高度,單位是像素
例子:
&width=650&height=250
默認值: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
默認值:1.2
能夠設置爲任意的浮點型數或者整形數,表明線條的寬度,單位是像素。
例子:
&lineWidth=5
默認值:False
若是設置爲True,則只訪問本地graphite服務器裏面的指標,不訪問遠端graphite服務器裏面的指標。
默認值:Template.conf文件裏面[default]下面指定的值
設置網格線的顏色
例子:
&majorGridLineColor=FF22FF
默認值:10
設置圖片周圍的邊距,單位是像素。
例子:
&margin=20
當返回json格式的數據時,可使用這個參數限制返回的最大數據點個數。
若是選定時間段內的數據點數大於這個值,則整個時間段內的數據點會進行合併操做
默認值:Template.conf文件裏面[default]下面指定的值
設置minor grid line的顏色
例子:
&minorGridLineColor=darkgrey
Sets the number of minor grid lines per major line on the y-axis.
例子:
&minorY=3
默認值:False
若是設置爲true,則禁用圖片緩存功能
默認值:default
用來指定一個定義在graphTemplates.conf裏面的模板,模板裏面定義了一下默認的顏色和圖片風格。
例子:
&template=plain
默認值:不設置
爲圖像設置一個標題
例子:
&title=test
默認值:定義在local_settings.py文件裏面的時區
例子:
&tz=America/Los_Angeles &tz=UTC
能夠經過修改local_settings.py文件來修改默認時區
默認值:false
只顯示惟一的legend,去掉重複的
默認值:不設置
設置y軸的名稱,若是沒有設置,那麼y軸上就沒有名稱
例子:
&vtitle=number
默認值:330
設置圖片的寬度
例子:
&width=650&height=250
默認值:基於x軸的時間長度動態設置
Sets the time format used when displaying the X-axis. See datetime.date.strftime() for format specification details.
默認值:left
設置y軸的位置,可使用的值有left和right
例子:
yAxisSide=right
默認值:指標數據裏面的最小值
設置y軸的最小值,能夠是任意的浮點型或者整形數
例子:
&yMin=0
默認值:指標數據裏面的最大值
設置y軸的最大值,能夠是任意的浮點型或者整形數
例子:
&yMax=100
默認值:根據指標數據動態設置
設置y軸的步長
&yStep=5
-----------------------------------------------------
歡迎關注個人微信公衆號 ^_^