HTTP API¶

target¶

The target parameter specifies a path identifying one or several metrics, optionally with functions acting on those metrics. Paths are documented below, while functions are listed on the functions page.

&target=company.server05.applicationInstance04.requestsHandled
(draws one metric)

&target=company.server05.applicationInstance*.requestsHandled
(draws 4 metrics / lines)

&target=company.server*.applicationInstance*.requestsHandled
(draws 40 metrics / lines)

&target=averageSeries(company.server*.applicationInstance.requestsHandled)
(draws 1 aggregate line)

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

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 possible 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 by a minus sign (-) and followed by a unit of time. Valid units of time:

ABSOLUTE_TIME is in the format HH:MM_YYMMDD, YYYYMMDD, MM/DD/YY, or any other at(1)-compatible time format.

&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)

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

entries,1311836008,1311836013,1|1.0,2.0,3.0,5.0,6.0

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

[{
  "target": "entries",
  "datapoints": [
    [1.0, 1311836008],
    [2.0, 1311836009],
    [3.0, 1311836010],
    [5.0, 1311836011],
    [6.0, 1311836012]
  ]
}]

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

rawData¶

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

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: white

Sets the background color of the graph.

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 cache.default_timeout in your configuration file. By default, 60 seconds.

colorList¶

Default: blue,green,red,purple,brown,yellow,aqua,grey,magenta,pink,gold,rose

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: black

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: false

If set to true, makes the font bold.

Example:

&fontBold=true

fontItalic¶

Default: false

If set to true, makes the font italic / oblique.

Example:

&fontItalic=true

fontName¶

Default: ‘Sans’

Change the font used to render text on the graph The font must be installed on the Graphite-API server.

Example:

&fontName=FreeMono

fontSize¶

Default: 10

Changes the font size Must be passed a positive floating point number or integer equal to or greater than 1.

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.

graphType¶

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 is displayed if there are less than 10 items.

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

hideXAxis¶

Default: false

If set to true the X Axis will not be rendered.

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: 300

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

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

majorGridLineColor¶

Default: rose

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¶

maxDataPoints¶

Set the maximum numbers of datapoints returned when using json content.

If the number of datapoints in a selected range exceeds the maxDataPoints value then the datapoints over the whole period are consolidated.

minorGridLineColor¶

Default: grey

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¶

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 it to disable caching in rendered graphs.

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¶

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 the graphite-api configuration

Time zone to convert all times into.

Examples:

&tz=America/Los_Angeles
&tz=UTC

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.

yDivisors¶

Default: 4,5,6

Sets the preferred number of intermediate values to display on the Y-axis (Y values between the minimum and maximum). Note that Graphite will ultimately choose what values (and how many) to display based on a ‘pretty’ factor, which tries to maintain a sensible scale (e.g. preferring intermediary values like 25%,50%,75% over 33.3%,66.6%). 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.