Graphite
Docs » The Render URL API
Note
You are not reading the most recent version of this documentation. 1.1.8 is the latest version available.
The Render URL API
The graphite webapp provides a /render endpoint for generating graphs and retreiving raw data. This endpoint accepts various arguments via query string parameters. These parameters are separated by an ampersand (&) and are supplied in the format:
&name=value
To verify that the api is running and able to generate images, open http://GRAPHITE_HOST:GRAPHITE_PORT/render in a browser. The api should return a simple 330x250 image with the text “No Data”.
Once the api is running and you’ve begun feeding data into carbon, use the parameters below to customize your graphs and pull out raw data. For example:
# 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(deriviative(app.numUsers),"1min")&title=New_Users_Per_Minute
Note
Most of the functions and parameters are case sensitive. For example &linewidth=2 will fail silently. The correct parameter in this case is &lineWidth=2
Graphing Metrics
To begin graphing specific metrics, pass one or more target parameters and specify a time window for the graph via from / until.
target
This will draw one or more metrics
Example:
&target=company.server05.applicationInstance04.requestsHandled (draws one metric)
Let’s say there are 4 identical application instances running on each server.
&target=company.server05.applicationInstance*.requestsHandled (draws 4 metrics / lines)
Now let’s say you have 10 servers.
&target=company.server*.applicationInstance*.requestsHandled (draws 40 metrics / lines)
You can also run any number of functions on the various metrics before graphing.
&target=averageSeries(company.server*.applicationInstance.requestsHandled) (draws 1 aggregate line)
The target param can also be repeated to graph multiple related metrics.
&target=company.server1.loadAvg&target=company.server1.memUsage
Note
If more than 10 metrics are drawn the legend is no longer displayed. See the hideLegend parameter for details.
from / until
These are optional parameters that specify the relative or absolute time period to graph. from specifies the beginning, until specifies the end. If from is omitted, it defaults to 24 hours ago. If until is omitted, it defaults to the current time (now).
There are multiple formats for these functions:
&from=-RELATIVE_TIME &from=ABSOLUTE_TIME
RELATIVE_TIME is a length of time since the current time. It is always preceded my a minus sign ( - ) and follow by a unit of time. Valid units of time:
AbbreviationUnit
sSeconds
minMinutes
hHours
dDays
wWeeks
mon30 Days (month)
y365 Days (year)
ABSOLUTE_TIME is in the format HH:MM_YYMMDD, YYYYMMDD, MM/DD/YY, or any other at(1)-compatible time format.
AbbreviationMeaning
HHHours, in 24h clock format. Times before 12PM must include leading zeroes.
MMMinutes
YYYY4 Digit Year.
MMNumeric month representation with leading zero
DDDay of month with leading zero
&from and &until can mix absolute and relative time if desired.
Examples:
&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)
Data Display Formats
Along with rendering an image, the api can also generate SVG with embedded metadata or return the raw data in various formats for external graphing, analysis or monitoring.
format
Controls the format of data returned. Affects all &targets passed in the URL.
Examples:
&format=png &format=raw &format=csv &format=json &format=svg
png
Renders the graph as a PNG image of size determined by width and height
raw
Renders the data in a custom line-delimited format. Targets are output one per line and are of the format
<target name>,<start timestamp>,<end timestamp>,<series step>|[data]*
entries,1311836008,1311836013,1|1.0,2.0,3.0,5.0,6.0
csv
Renders the data in a CSV format suitable for import into a spreadsheet or for processing in a script
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
Renders the data as a json object. The jsonp option can be used to wrap this data in a named call for cross-domain access
[{ "target": "entries", "datapoints": [ [1.0, 1311836008], [2.0, 1311836009], [3.0, 1311836010], [5.0, 1311836011], [6.0, 1311836012] ] }]
svg
Renders the graph as SVG markup of size determined by width and height. Metadata about the drawn graph is saved as an embedded script with the variable metadata being set to an object describing the graph
<script> <![CDATA[ metadata = { "area": { "xmin": 39.195507812499997, "ymin": 33.96875, "ymax": 623.794921875, "xmax": 1122 }, "series": [ { "start": 1335398400, "step": 1800, "end": 1335425400, "name": "summarize(test.data, \"30min\", \"sum\")", "color": "#859900", "data": [null, null, 1.0, null, 1.0, null, 1.0, null, 1.0, null, 1.0, null, null, null, null], "options": {}, "valuesPerPoint": 1 } ], "y": { "labelValues": [0, 0.25, 0.5, 0.75, 1.0], "top": 1.0, "labels": ["0 ", "0.25 ", "0.50 ", "0.75 ", "1.00 "], "step": 0.25, "bottom": 0 }, "x": { "start": 1335398400, "end": 1335423600 }, "font": { "bold": false, "name": "Sans", "italic": false, "size": 10 }, "options": { "lineWidth": 1.2 } } ]]> </script>
pickle
Returns a Python pickle (serialized Python object). The response will have the MIME type ‘application/pickle’. The pickled object is a list of dictionaries with the keys: name, start, end, step, and values as below:
[ { 'name' : 'summarize(test.data, "30min", "sum")', 'start': 1335398400, 'end' : 1335425400, 'step' : 1800, 'values' : [None, None, 1.0, None, 1.0, None, 1.0, None, 1.0, None, 1.0, None, None, None, None], }]
rawData
Deprecated since version 0.9.9: This option is deprecated in favor of format_
Used to get numerical data out of the webapp instead of an image. Can be set to true, false, csv. Affects all &targets passed in the URL.
Example:
&target=carbon.agents.graphiteServer01.cpuUsage&from=-5min&rawData=true
Returns the following text:
carbon.agents.graphiteServer01.cpuUsage,1306217160,1306217460,60|0.0,0.00666666520965,0.00666666624282,0.0,0.0133345399694
Graph Parameters
areaAlpha
Default: 1.0
Takes a floating point number between 0.0 and 1.0 Sets the alpha (transparency) value of filled areas when using an areaMode
areaMode
Default: none
Enables filling of the area below the graphed lines. Fill area is the same color as the line color associated with it. See areaAlpha to make this area transparent. Takes one of the following parameters which determines the fill mode to use:
none
Disables areaMode
first
Fills the area under the first target and no other
all
Fills the areas under each target
stacked
Creates a graph where the filled area of each target is stacked on one another. Each target line is displayed as the sum of all previous lines plus the value of the current line.
bgcolor
Default: value from the [default] template in graphTemplates.conf
Sets the background color of the graph.
Color NamesRGB Value
black0,0,0
white255,255,255
blue100,100,255
green0,200,0
red200,0,50
yellow255,255,0
orange255, 165, 0
purple200,100,255
brown150,100,50
aqua0,150,150
gray175,175,175
grey175,175,175
magenta255,0,255
pink255,100,100
gold200,200,0
rose200,150,200
darkblue0,0,255
darkgreen0,255,0
darkred255,0,0
darkgray111,111,111
darkgrey111,111,111
RGB can be passed directly in the format #RRGGBB where RR, GG, and BB are 2-digit hex vaules for red, green and blue, respectively.
Examples:
&bgcolor=blue &bgcolor=#2222FF
cacheTimeout
Default: The value of DEFAULT_CACHE_DURATION from local_settings.py
The time in seconds for the rendered graph to be cached (only relevant if memcached is configured)
colorList
Default: value from the [default] template in graphTemplates.conf
Takes one or more comma-separated color names or RGB values (see bgcolor for a list of color names) and uses that list in order as the colors of the lines. If more lines / metrics are drawn than colors passed, the list is reused in order.
Example:
&colorList=green,yellow,orange,red,purple,#DECAFF
drawNullAsZero
Default: false
Converts any None (null) values in the displayed metrics to zero at render time.
fgcolor
Default: value from the [default] template in graphTemplates.conf
Sets the foreground color. This only affects the title, legend text, and axis labels.
See majorGridLineColor, and minorGridLineColor for further control of colors.
See bgcolor for a list of color names and details on formatting this parameter.
fontBold
Default: value from the [default] template in graphTemplates.conf
If set to true, makes the font bold.
Example:
&fontBold=true
fontItalic
Default: value from the [default] template in graphTemplates.conf
If set to true, makes the font italic / oblique. Default is false.
Example:
&fontItalic=true
fontName
Default: value from the [default] template in graphTemplates.conf
Change the font used to render text on the graph. The font must be installed on the Graphite Server.
Example:
&fontName=FreeMono
fontSize
Default: value from the [default] template in graphTemplates.conf
Changes the font size. Must be passed a positive floating point number or integer equal to or greater than 1. Default is 10
Example:
&fontSize=8
format
See: Data Display Formats
from
See: from / until
graphOnly
Default: False
Display only the graph area with no grid lines, axes, or legend
graphTypes
Default: line
Sets the type of graph to be rendered. Currently there are only two graph types:
line
A line graph displaying metrics as lines over time
pie
A pie graph with each slice displaying an aggregate of each metric calculated using the function specified by pieMode
hideLegend
Default: <unset>
If set to true, the legend is not drawn. If set to false, the legend is drawn. If unset, the LEGEND_MAX_ITEMS settings in local_settings.py is used to determine whether or not to display the legend.
Hint: If set to false the &height parameter may need to be increased to accommodate the additional text.
Example:
&hideLegend=false
hideAxes
Default: False
If set to true the X and Y axes will not be rendered Example:
&hideAxes=true
hideYAxis
Default: False
If set to true the Y Axis will not be rendered
hideGrid
Default: False
If set to true the grid lines will not be rendered
Example:
&hideGrid=true
height
Default: 250
Sets the height of the generated graph image in pixels.
See also: width
Example:
&width=650&height=250
jsonp
Default: <unset>
If set and combined with format=json, wraps the JSON response in a function call named by the parameter specified.
leftColor
Default: color chosen from colorList
In dual Y-axis mode, sets the color of all metrics associated with the left Y-axis.
leftDashed
Default: False
In dual Y-axis mode, draws all metrics associated with the left Y-axis using dashed lines
leftWidth
Default: value of the parameter lineWidth
In dual Y-axis mode, sets the line width of all metrics associated with the left Y-axis
lineMode
Default: slope
Sets the line drawing behavior. Takes one of the following parameters:
slope
Slope line mode draws a line from each point to the next. Periods will 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
Example:
&lineMode=staircase
lineWidth
Default: 1.2
Takes any floating point or integer (negative numbers do not error but will cause no line to be drawn). Changes the width of the line in pixels.
Example:
&lineWidth=2
logBase
Default: <unset>
If set, draws the graph with a logarithmic scale of the specified base (e.g. 10 for common logarithm)
localOnly
Default: False
Set to prevent fetching from remote Graphite servers, only returning metrics which are accessible locally
majorGridLineColor
Default: value from the [default] template in graphTemplates.conf
Sets the color of the major grid lines.
See bgcolor for valid color names and formats.
Example:
&majorGridLineColor=#FF22FF
margin
Default: 10 Sets the margin around a graph image in pixels on all sides.
Example:
&margin=20
max
Deprecated since version 0.9.0: See yMax
minorGridLineColor
Default: value from the [default] template in graphTemplates.conf
Sets the color of the minor grid lines.
See bgcolor for valid color names and formats.
Example:
&minorGridLineColor=darkgrey
minorY
Sets the number of minor grid lines per major line on the y-axis.
Example:
&minorY=3
min
Deprecated since version 0.9.0: See yMin
minXStep
Default: 1
Sets the minimum pixel-step to use between datapoints drawn. Any value below this will trigger a point consolidation of the series at render time. The default value of 1 combined with the default lineWidth of 1.2 will cause a minimal amount of line overlap between close-together points. To disable render-time point consolidation entirely, set this to 0 though note that series with more points than there are pixels in the graph area (e.g. a few month’s worth of per-minute data) will look very ‘smooshed’ as there will be a good deal of line overlap. In response, one may use lineWidth to compensate for this.
noCache
Default: False
Set to disable caching of rendered images
pickle
Deprecated since version 0.9.10: See Data Display Formats
pieMode
Default: average
The type of aggregation to use to calculate slices of a pie when graphType=pie. One of:
average
The average of non-null points in the series
maximum
The maximum of non-null points in the series
minimum
THe minimum of non-null points in the series
rightColor
Default: color chosen from colorList
In dual Y-axis mode, sets the color of all metrics associated with the right Y-axis.
rightDashed
Default: False
In dual Y-axis mode, draws all metrics associated with the right Y-axis using dashed lines
rightWidth
Default: value of the parameter lineWidth
In dual Y-axis mode, sets the line width of all metrics associated with the right Y-axis
template
Default: default
Used to specify a template from graphTemplates.conf to use for default colors and graph styles.
Example:
&template=plain
thickness
Deprecated since version 0.9.0: See: lineWidth
title
Default: <unset>
Puts a title at the top of the graph, center aligned. If unset, no title is displayed.
Example:
&title=Apache Busy Threads, All Servers, Past 24h
tz
Default: The timezone specified in local_settings.py
Time zone to convert all times into.
Examples:
&tz=America/Los_Angeles &tz=UTC
Note
To change the default timezone, edit webapp/graphite/local_settings.py​.
uniqueLegend
Default: False
Display only unique legend items, removing any duplicates
until
See: from / until
vtitle
Default: <unset>
Labels the y-axis with vertical text. If unset, no y-axis label is displayed.
Example:
&vtitle=Threads
vtitleRight
Default: <unset>
In dual Y-axis mode, sets the title of the right Y-Axis (See: vtitle)
width
Default: 330
Sets the width of the generated graph image in pixels.
See also: height
Example:
&width=650&height=250
xFormat
Default: Determined automatically based on the time-width of the X axis
Sets the time format used when displaying the X-axis. See datetime.date.strftime() for format specification details.
yAxisSide
Default: left
Sets the side of the graph on which to render the Y-axis. Accepts values of left or right
yDivisor
Default: 4,5,6
Supplies the preferred number of intermediate values for the Y-axis to display (Y values between the min and max). Note that Graphite will ultimately choose what values (and how many) to display based on a set of ‘pretty’ values. To explicitly set the Y-axis values, see yStep
yLimit
Reserved for future use See: yMax
yLimitLeft
Reserved for future use See: yMaxLeft
yLimitRight
Reserved for future use See: yMaxRight
yMin
Default: The lowest value of any of the series displayed
Manually sets the lower bound of the graph. Can be passed any integer or floating point number.
Example:
&yMin=0
yMax
Default: The highest value of any of the series displayed
Manually sets the upper bound of the graph. Can be passed any integer or floating point number.
Example:
&yMax=0.2345
yMaxLeft
In dual Y-axis mode, sets the upper bound of the left Y-Axis (See: yMax)
yMaxRight
In dual Y-axis mode, sets the upper bound of the right Y-Axis (See: yMax)
yMinLeft
In dual Y-axis mode, sets the lower bound of the left Y-Axis (See: yMin)
yMinRight
In dual Y-axis mode, sets the lower bound of the right Y-Axis (See: yMin)
yStep
Default: Calculated automatically
Manually set the value step between Y-axis labels and grid lines
yStepLeft
In dual Y-axis mode, Manually set the value step between the left Y-axis labels and grid lines (See: yStep)
yStepRight
In dual Y-axis mode, Manually set the value step between the right Y-axis labels and grid lines (See: yStep)
yUnitSystem
Default: si
Set the unit system for compacting Y-axis values (e.g. 23,000,000 becomes 23M). Value can be one of:
si
Use si units (powers of 1000) - K, M, G, T, P
binary
Use binary units (powers of 1024) - Ki, Mi, Gi, Ti, Pi
none
Dont compact values, display the raw number
Next
Previous
LaunchDarkly: Learn how feature management is shaping the future of DevOps!
Ad by EthicalAds   ·   Monetize your site
© Copyright 2011, Chris Davis.
Sphinx theme provided by Read the Docs
GraphiteOverviewAbout the projectThe architecture in a nutshellInstalling GraphiteDependenciesFulfilling DependenciesDefault Installation LayoutInstalling GraphiteInitial ConfigurationHelp! It didn’t work!Post-Install TasksThe Carbon Daemonscarbon-cache.pycarbon-relay.pycarbon-aggregator.pyConfiguring Carboncarbon.confstorage-schemas.confstorage-aggregation.confrelay-rules.confaggregation-rules.confwhitelist and blacklistFeeding In Your DataThe plaintext protocolThe pickle protocolUsing AMQPConfiguring The WebappAdministering The WebappUsing The ComposerGraphing MetricsData Display FormatsGraph ParametersFunctionsUsageList of functionsThe Dashboard UIThe Whisper DatabaseData PointsArchives: Retention and PrecisionRollup AggregationMulti-Archive Storage and Retrieval BehaviorDisk Space EfficiencyDifferences Between Whisper and RRDPerformanceDatabase FormatGraphite TerminologyTools That Work With GraphiteBackstopBuckycollectdCollectlCharcoalDescartesDiamondEvenflowGangliaGDashGiraffeGraphitusGraph-ExplorerGrapheneGraphite-relayGraphite-TattleGraphitiGraphitoidGraphiosGraphitejsGraphskyGrocketsHoardDHost sFlowhubot-scriptsjmxtransLedbetterLogsterPencilRocksteadyScalesSeyrenShinkenstatsdStructured MetricsTasseoTherryTimeseriesWidgetWho is using Graphite?Release Notes0.9.100.9.110.9.120.9.20.9.30.9.40.9.50.9.60.9.70.9.80.9.9
Graphite