Functions

Functions are used to transform, combine, and perform computations on series data. Functions are applied using the Composer interface or by manipulating the target parameters in the Render API.

Usage

Most functions are applied to one series list. Functions with the parameter *seriesLists can take an arbitrary number of series lists. To pass multiple series lists to a function which only takes one, use the group() function.

List of functions

absolute(seriesList)

Takes one metric or a wildcard seriesList and applies the mathematical abs function to each datapoint transforming it to its absolute value.

Example:

&target=absolute(Server.instance01.threads.busy)
&target=absolute(Server.instance*.threads.busy)
alias(seriesList, newName)

Takes one metric or a wildcard seriesList and a string in quotes. Prints the string instead of the metric name in the legend.

&target=alias(Sales.widgets.largeBlue,"Large Blue Widgets")
aliasByMetric(seriesList)

Takes a seriesList and applies an alias derived from the base metric name.

&target=aliasByMetric(carbon.agents.graphite.creates)
aliasByNode(seriesList, *nodes)

Takes a seriesList and applies an alias derived from one or more “node” portion/s of the target name. Node indices are 0 indexed.

&target=aliasByNode(ganglia.*.cpu.load5,1)
aliasSub(seriesList, search, replace)

Runs series names through a regex search/replace.

&target=aliasSub(ip.*TCP*,"^.*TCP(\d+)","\1")
alpha(seriesList, alpha)

Assigns the given alpha transparency setting to the series. Takes a float value between 0 and 1.

areaBetween(seriesList)

Draws the area in between the two series in seriesList

asPercent(seriesList, total=None)

Calculates a percentage of the total of a wildcard series. If total is specified, each series will be calculated as a percentage of that total. If total is not specified, the sum of all points in the wildcard series will be used instead.

The total parameter may be a single series or a numeric value.

Example:

&target=asPercent(Server01.connections.{failed,succeeded}, Server01.connections.attempted)
&target=asPercent(apache01.threads.busy,1500)
&target=asPercent(Server01.cpu.*.jiffies)
averageAbove(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N. Out of all metrics passed, draws only the metrics with an average value above N for the time period specified.

Example:

&target=averageAbove(server*.instance*.threads.busy,25)

Draws the servers with average values above 25.

averageBelow(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N. Out of all metrics passed, draws only the metrics with an average value below N for the time period specified.

Example:

&target=averageBelow(server*.instance*.threads.busy,25)

Draws the servers with average values below 25.

averageSeries(*seriesLists)

Short Alias: avg()

Takes one metric or a wildcard seriesList. Draws the average value of all metrics passed at each time.

Example:

&target=averageSeries(company.server.*.threads.busy)
averageSeriesWithWildcards(seriesList, *position)

Call averageSeries after inserting wildcards at the given position(s).

Example:

&target=averageSeriesWithWildcards(host.cpu-[0-7].cpu-{user,system}.value, 1)

This would be the equivalent of target=averageSeries(host.*.cpu-user.value)&target=averageSeries(host.*.cpu-system.value)

cactiStyle(seriesList)

Takes a series list and modifies the aliases to provide column aligned output with Current, Max, and Min values in the style of cacti. NOTE: column alignment only works with monospace fonts such as terminus.

&target=cactiStyle(ganglia.*.net.bytes_out)
color(seriesList, theColor)

Assigns the given color to the seriesList

Example:

&target=color(collectd.hostname.cpu.0.user, 'green')
&target=color(collectd.hostname.cpu.0.system, 'ff0000')
&target=color(collectd.hostname.cpu.0.idle, 'gray')
&target=color(collectd.hostname.cpu.0.idle, '6464ffaa')
constantLine(value)

Takes a float F.

Draws a horizontal line at value F across the graph.

Example:

&target=constantLine(123.456)
cumulative(seriesList)

Takes one metric or a wildcard seriesList.

By default, when a graph is drawn, and the width of the graph in pixels is smaller than the number of datapoints to be graphed, Graphite averages the value at each pixel. The cumulative() function changes the consolidation function to sum from average. This is especially useful in sales graphs, where fractional values make no sense (How can you have half of a sale?)

&target=cumulative(Sales.widgets.largeBlue)
currentAbove(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N. Out of all metrics passed, draws only the metrics whose value is above N at the end of the time period specified.

Example:

&target=highestAbove(server*.instance*.threads.busy,50)

Draws the servers with more than 50 busy threads.

currentBelow(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N. Out of all metrics passed, draws only the metrics whose value is below N at the end of the time period specified.

Example:

&target=currentBelow(server*.instance*.threads.busy,3)

Draws the servers with less than 3 busy threads.

dashed(*seriesList)

Takes one metric or a wildcard seriesList, followed by a float F.

Draw the selected metrics with a dotted line with segments of length F If omitted, the default length of the segments is 5.0

Example:

&target=dashed(server01.instance01.memory.free,2.5)
derivative(seriesList)

This is the opposite of the integral function. This is useful for taking a running total metric and showing how many requests per minute were handled.

Example:

&target=derivative(company.server.application01.ifconfig.TXPackets)

Each time you run ifconfig, the RX and TXPackets are higher (assuming there is network traffic.) By applying the derivative function, you can get an idea of the packets per minute sent or received, even though you’re only recording the total.

diffSeries(*seriesLists)

Can take two or more metrics, or a single metric and a constant. Subtracts parameters 2 through n from parameter 1.

Example:

&target=diffSeries(service.connections.total,service.connections.failed)
&target=diffSeries(service.connections.total,5)
divideSeries(dividendSeriesList, divisorSeriesList)

Takes a dividend metric and a divisor metric and draws the division result. A constant may not be passed. To divide by a constant, use the scale() function (which is essentially a multiplication operation) and use the inverse of the dividend. (Division by 8 = multiplication by 1/8 or 0.125)

Example:

&target=divideSeries(Series.dividends,Series.divisors)
drawAsInfinite(seriesList)

Takes one metric or a wildcard seriesList. If the value is zero, draw the line at 0. If the value is above zero, draw the line at infinity. If the value is null or less than zero, do not draw the line.

Useful for displaying on/off metrics, such as exit codes. (0 = success, anything else = failure.)

Example:

drawAsInfinite(Testing.script.exitCode)
events(*tags)

Returns the number of events at this point in time. Usable with drawAsInfinite.

Example:

&target=events("tag-one", "tag-two")
&target=events("*")

Returns all events tagged as “tag-one” and “tag-two” and the second one returns all events.

exclude(seriesList, pattern)

Takes a metric or a wildcard seriesList, followed by a regular expression in double quotes. Excludes metrics that match the regular expression.

Example:

&target=exclude(servers*.instance*.threads.busy,"server02")
group(*seriesLists)

Takes an arbitrary number of seriesLists and adds them to a single seriesList. This is used to pass multiple seriesLists to a function which only takes one

groupByNode(seriesList, nodeNum, callback)

Takes a serieslist and maps a callback to subgroups within as defined by a common node

&target=groupByNode(ganglia.by-function.*.*.cpu.load5,2,"sumSeries")

Would return multiple series which are each the result of applying the "sumSeries" function
to groups joined on the second node (0 indexed) resulting in a list of targets like
sumSeries(ganglia.by-function.server1.*.cpu.load5),sumSeries(ganglia.by-function.server2.*.cpu.load5),...
highestAverage(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N. Out of all metrics passed, draws only the top N metrics with the highest average value for the time period specified.

Example:

&target=highestAverage(server*.instance*.threads.busy,5)

Draws the top 5 servers with the highest average value.

highestCurrent(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N. Out of all metrics passed, draws only the N metrics with the highest value at the end of the time period specified.

Example:

&target=highestCurrent(server*.instance*.threads.busy,5)

Draws the 5 servers with the highest busy threads.

highestMax(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N.

Out of all metrics passed, draws only the N metrics with the highest maximum value in the time period specified.

Example:

&target=highestCurrent(server*.instance*.threads.busy,5)

Draws the top 5 servers who have had the most busy threads during the time period specified.

hitcount(seriesList, intervalString, alignToInterval=False)

Estimate hit counts from a list of time series.

This function assumes the values in each time series represent hits per second. It calculates hits per some larger interval such as per day or per hour. This function is like summarize(), except that it compensates automatically for different time scales (so that a similar graph results from using either fine-grained or coarse-grained records) and handles rarely-occurring events gracefully.

holtWintersAberration(seriesList, delta=3)

Performs a Holt-Winters forecast using the series as input data and plots the positive or negative deviation of the series data from the forecast.

holtWintersConfidenceArea(seriesList, delta=3)

Performs a Holt-Winters forecast using the series as input data and plots the area between the upper and lower bands of the predicted forecast deviations.

holtWintersConfidenceBands(seriesList, delta=3)

Performs a Holt-Winters forecast using the series as input data and plots upper and lower bands with the predicted forecast deviations.

holtWintersForecast(seriesList)

Performs a Holt-Winters forecast using the series as input data. Data from one week previous to the series is used to bootstrap the initial forecast.

integral(seriesList)

This will show the sum over time, sort of like a continuous addition function. Useful for finding totals or trends in metrics that are collected per minute.

Example:

&target=integral(company.sales.perMinute)

This would start at zero on the left side of the graph, adding the sales each minute, and show the total sales for the time period selected at the right side, (time now, or the time specified by ‘&until=’).

keepLastValue(seriesList)

Takes one metric or a wildcard seriesList. Continues the line with the last received value when gaps (‘None’ values) appear in your data, rather than breaking your line.

Example:

&target=keepLastValue(Server01.connections.handled)
legendValue(seriesList, *valueTypes)

Takes one metric or a wildcard seriesList and a string in quotes. Appends a value to the metric name in the legend. Currently one or several of: last, avg, total, min, max. The last argument can be si (default) or binary, in that case values will be formatted in the corresponding system.

&target=legendValue(Sales.widgets.largeBlue, ‘avg’, ‘max’, ‘si’)

limit(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N.

Only draw the first N metrics. Useful when testing a wildcard in a metric.

Example:

&target=limit(server*.instance*.memory.free,5)

Draws only the first 5 instance’s memory free.

lineWidth(seriesList, width)

Takes one metric or a wildcard seriesList, followed by a float F.

Draw the selected metrics with a line width of F, overriding the default value of 1, or the &lineWidth=X.X parameter.

Useful for highlighting a single metric out of many, or having multiple line widths in one graph.

Example:

&target=lineWidth(server01.instance01.memory.free,5)
logarithm(seriesList, base=10)

Takes one metric or a wildcard seriesList, a base, and draws the y-axis in logarithmic format. If base is omitted, the function defaults to base 10.

Example:

&target=log(carbon.agents.hostname.avgUpdateTime,2)
lowestAverage(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N. Out of all metrics passed, draws only the bottom N metrics with the lowest average value for the time period specified.

Example:

&target=lowestAverage(server*.instance*.threads.busy,5)

Draws the bottom 5 servers with the lowest average value.

lowestCurrent(seriesList, n)

Takes one metric or a wildcard seriesList followed by an integer N. Out of all metrics passed, draws only the N metrics with the lowest value at the end of the time period specified.

Example:

&target=lowestCurrent(server*.instance*.threads.busy,5)

Draws the 5 servers with the least busy threads right now.

maxSeries(*seriesLists)

Takes one metric or a wildcard seriesList. For each datapoint from each metric passed in, pick the maximum value and graph it.

Example:

&target=maxSeries(Server*.connections.total)
maximumAbove(seriesList, n)

Takes one metric or a wildcard seriesList followed by a constant n. Draws only the metrics with a maximum value above n.

Example:

&target=maximumAbove(system.interface.eth*.packetsSent,1000)

This would only display interfaces which sent more than 1000 packets/min.

maximumBelow(seriesList, n)

Takes one metric or a wildcard seriesList followed by a constant n. Draws only the metrics with a maximum value below n.

Example:

&target=maximumBelow(system.interface.eth*.packetsSent,1000)

This would only display interfaces which sent less than 1000 packets/min.

minSeries(*seriesLists)

Takes one metric or a wildcard seriesList. For each datapoint from each metric passed in, pick the minimum value and graph it.

Example:

&target=minSeries(Server*.connections.total)
minimumAbove(seriesList, n)

Takes one metric or a wildcard seriesList followed by a constant n. Draws only the metrics with a minimum value above n.

Example:

&target=minimumAbove(system.interface.eth*.packetsSent,1000)

This would only display interfaces which sent more than 1000 packets/min.

mostDeviant(n, seriesList)

Takes an integer N followed by one metric or a wildcard seriesList. Draws the N most deviant metrics. To find the deviant, the average across all metrics passed is determined, and then the average of each metric is compared to the overall average.

Example:
&target=mostDeviant(5, server*.instance*.memory.free)

Draws the 5 instances furthest from the average memory free.

movingAverage(seriesList, windowSize)

Takes one metric or a wildcard seriesList followed by a number N of datapoints and graphs the average of N previous datapoints. N-1 datapoints are set to None at the beginning of the graph.

&target=movingAverage(Server.instance01.threads.busy,10)
movingMedian(seriesList, windowSize)

Takes one metric or a wildcard seriesList followed by a number N of datapoints and graphs the median of N previous datapoints. N-1 datapoints are set to None at the beginning of the graph.

&target=movingMedian(Server.instance01.threads.busy,10)
multiplySeries(*seriesLists)

Takes two or more series and multiplies their points. A constant may not be used. To multiply by a constant, use the scale() function.

Example:

&target=multiplySeries(Series.dividends,Series.divisors)
nPercentile(seriesList, n)

Returns n-percent of each series in the seriesList.

nonNegativeDerivative(seriesList, maxValue=None)

Same as the derivative function above, but ignores datapoints that trend down. Useful for counters that increase for a long time, then wrap or reset. (Such as if a network interface is destroyed and recreated by unloading and re-loading a kernel module, common with USB / WiFi cards.

Example:

&target=derivative(company.server.application01.ifconfig.TXPackets)
offset(seriesList, factor)

Takes one metric or a wildcard seriesList followed by a constant, and adds the constant to each datapoint.

Example:

&target=offset(Server.instance01.threads.busy,10)
percentileOfSeries(seriesList, n, interpolate=False)

percentileOfSeries returns a single series which is composed of the n-percentile values taken across a wildcard series at each point. Unless interpolate is set to True, percentile values are actual values contained in one of the supplied series.

randomWalkFunction(name)

Short Alias: randomWalk()

Returns a random walk starting at 0. This is great for testing when there is no real data in whisper.

Example:

&target=randomWalk("The.time.series")

This would create a series named “The.time.series” that contains points where x(t) == x(t-1)+random()-0.5, and x(0) == 0.

rangeOfSeries(*seriesLists)

Takes a wildcard seriesList. Distills down a set of inputs into the range of the series

Example:

&target=rangeOfSeries(Server*.connections.total)
removeAbovePercentile(seriesList, n)

Removes data above the nth percentile from the series or list of series provided. Values below this percentile are assigned a value of None.

removeAboveValue(seriesList, n)

Removes data above the given threshold from the series or list of series provided. Values below this threshole are assigned a value of None

removeBelowPercentile(seriesList, n)

Removes data above the nth percentile from the series or list of series provided. Values below this percentile are assigned a value of None.

removeBelowValue(seriesList, n)

Removes data above the given threshold from the series or list of series provided. Values below this threshole are assigned a value of None

scale(seriesList, factor)

Takes one metric or a wildcard seriesList followed by a constant, and multiplies the datapoint by the constant provided at each point.

Example:

&target=scale(Server.instance01.threads.busy,10)
&target=scale(Server.instance*.threads.busy,10)
scaleToSeconds(seriesList, seconds)

Takes one metric or a wildcard seriesList and returns “value per seconds” where seconds is a last argument to this functions.

Useful in conjunction with derivative or integral function if you want to normalize its result to a known resolution for arbitrary retentions

secondYAxis(seriesList)

Graph the series on the secondary Y axis.

sinFunction(name, amplitude=1)

Short Alias: sin()

Just returns the sine of the current time. The optional amplitude parameter changes the amplitude of the wave.

Example:

&target=sin("The.time.series", 2)

This would create a series named “The.time.series” that contains sin(x)*2.

smartSummarize(seriesList, intervalString, func='sum', alignToFrom=False)

Smarter experimental version of summarize.

The alignToFrom parameter has been deprecated, it no longer has any effect. Alignment happens automatically for days, hours, and minutes.

sortByMaxima(seriesList)

Takes one metric or a wildcard seriesList.

Sorts the list of metrics by the maximum value across the time period specified. Useful with the &areaMode=all parameter, to keep the lowest value lines visible.

Example:

&target=sortByMaxima(server*.instance*.memory.free)
sortByMinima(seriesList)

Takes one metric or a wildcard seriesList.

Sorts the list of metrics by the lowest value across the time period specified.

Example:

&target=sortByMinima(server*.instance*.memory.free)
stacked(seriesLists, stackName='__DEFAULT__')

Takes one metric or a wildcard seriesList and change them so they are stacked. This is a way of stacking just a couple of metrics without having to use the stacked area mode (that stacks everything). By means of this a mixed stacked and non stacked graph can be made

It can also take an optional argument with a name of the stack, in case there is more than one, e.g. for input and output metrics.

Example:

&target=stacked(company.server.application01.ifconfig.TXPackets, 'tx')
stdev(seriesList, points, windowTolerance=0.1)

Takes one metric or a wildcard seriesList followed by an integer N. Draw the Standard Deviation of all metrics passed for the past N datapoints. If the ratio of null points in the window is greater than windowTolerance, skip the calculation. The default for windowTolerance is 0.1 (up to 10% of points in the window can be missing). Note that if this is set to 0.0, it will cause large gaps in the output anywhere a single point is missing.

Example:

&target=stdev(server*.instance*.threads.busy,30)
&target=stdev(server*.instance*.cpu.system,30,0.0)
substr(seriesList, start=0, stop=0)

Takes one metric or a wildcard seriesList followed by 1 or 2 integers. Assume that the metric name is a list or array, with each element separated by dots. Prints n - length elements of the array (if only one integer n is passed) or n - m elements of the array (if two integers n and m are passed). The list starts with element 0 and ends with element (length - 1).

Example:

&target=substr(carbon.agents.hostname.avgUpdateTime,2,4)

The label would be printed as “hostname.avgUpdateTime”.

sumSeries(*seriesLists)

Short form: sum()

This will add metrics together and return the sum at each datapoint. (See integral for a sum over time)

Example:

&target=sum(company.server.application*.requestsHandled)

This would show the sum of all requests handled per minute (provided requestsHandled are collected once a minute). If metrics with different retention rates are combined, the coarsest metric is graphed, and the sum of the other metrics is averaged for the metrics with finer retention rates.

sumSeriesWithWildcards(seriesList, *position)

Call sumSeries after inserting wildcards at the given position(s).

Example:

&target=sumSeriesWithWildcards(host.cpu-[0-7].cpu-{user,system}.value, 1)

This would be the equivalent of target=sumSeries(host.*.cpu-user.value)&target=sumSeries(host.*.cpu-system.value)

summarize(seriesList, intervalString, func='sum', alignToFrom=False)

Summarize the data into interval buckets of a certain size.

By default, the contents of each interval bucket are summed together. This is useful for counters where each increment represents a discrete event and retrieving a “per X” value requires summing all the events in that interval.

Specifying ‘avg’ instead will return the mean for each bucket, which can be more useful when the value is a gauge that represents a certain value in time.

‘max’, ‘min’ or ‘last’ can also be specified.

By default, buckets are caculated by rounding to the nearest interval. This works well for intervals smaller than a day. For example, 22:32 will end up in the bucket 22:00-23:00 when the interval=1hour.

Passing alignToFrom=true will instead create buckets starting at the from time. In this case, the bucket for 22:32 depends on the from time. If from=6:30 then the 1hour bucket for 22:32 is 22:30-23:30.

Example:

&target=summarize(counter.errors, "1hour") # total errors per hour
&target=summarize(nonNegativeDerivative(gauge.num_users), "1week") # new users per week
&target=summarize(queue.size, "1hour", "avg") # average queue size per hour
&target=summarize(queue.size, "1hour", "max") # maximum queue size during each hour
&target=summarize(metric, "13week", "avg", true)&from=midnight+20100101 # 2010 Q1-4
threshold(value, label=None, color=None)

Takes a float F, followed by a label (in double quotes) and a color. (See bgcolor in the render_api_ for valid color names & formats.)

Draws a horizontal line at value F across the graph.

Example:

&target=threshold(123.456, "omgwtfbbq", red)
timeFunction(name)

Short Alias: time()

Just returns the timestamp for each X value. T

Example:

&target=time("The.time.series")

This would create a series named “The.time.series” that contains in Y the same value (in seconds) as X.

timeShift(seriesList, timeShift)

Takes one metric or a wildcard seriesList, followed by a quoted string with the length of time (See from / until in the render_api_ for examples of time formats).

Draws the selected metrics shifted in time. If no sign is given, a minus sign ( - ) is implied which will shift the metric back in time. If a plus sign ( + ) is given, the metric will be shifted forward in time.

Useful for comparing a metric against itself at a past periods or correcting data stored at an offset.

Example:

&target=timeShift(Sales.widgets.largeBlue,"7d")
&target=timeShift(Sales.widgets.largeBlue,"-7d")
&target=timeShift(Sales.widgets.largeBlue,"+1h")
transformNull(seriesList, default=0)

Takes a metric or wild card seriesList and an optional value to transform Nulls to. Default is 0. This method compliments drawNullAsZero flag in graphical mode but also works in text only mode. Example:

&target=transformNull(webapp.pages.*.views,-1)

This would take any page that didn’t have values and supply negative 1 as a default. Any other numeric value may be used as well.

useSeriesAbove(seriesList, value, search, replace)

Compares the maximum of each series against the given value. If the series maximum is greater than value, the regular expression search and replace is applied against the series name to plot a related metric

e.g. given useSeriesAbove(ganglia.metric1.reqs,10,’reqs’,’time’), the response time metric will be plotted only when the maximum value of the corresponding request/s metric is > 10

&target=useSeriesAbove(ganglia.metric1.reqs,10,"reqs","time")

Project Versions

Table Of Contents

Previous topic

The Render URL API

Next topic

The Dashboard UI

This Page