Introduction

The Graph API is the primary means to retrieve data from an Atlas store.

The default response is a PNG image plotting data matching the Atlas Stack Language expression along with optional parameters to control time ranges, size, style, labels, etc. For a quick overview by example see the examples page.

If graphs look familiar, that's because the design and language were inspired by RRDtool. RRD style graphs offer concise and highly customizable views of time series data. While a number of observability tools offer dynamic charts, a major benefit of these PNG graphs is the ability to snapshot data in time, particularly when that data may expire from a high throughput data store; PNGs are forever. Additionally, the majority of email and on-call systems support images out of the box without having to worry about porting a dynamic graphing library to various browsers and clients.

The API only supports HTTP query strings at this time. This makes it easy to construct queries with tooling and share the URIs with other users. No JSON request payloads needed.

Additional Output formats, including JSON, can be found in Outputs.

URI

/api/v1/graph?q=<expr>[&OPTIONS]

HTTP Method

GET - Only the GET method is allowed at this time.

Query Parameters

Data

The only required query param is q which is the query expression used by the user to select and manipulate data. The simplest API query you can make is /api/v1/graph?q=42. This will produce a graph from Atlas with a straight line having a value of 42 for 3 hours* with a legend including statistics for the query period.

All query params related to fetching data:

Name	Description	Default	Type
q	Query expression	must be specified by user	expr
step	Step size for data	auto	duration

Warning

In most cases users should not set step directly. The step parameter is deprecated.

Time

There are three parameters to control the time range used for a graph:

Name	Description	Default	Type
s	Start time	e-3h*	Time
e	End time	now*	Time
tz	Time zone	US/Pacific*	Time zone ID

For more information on the behavior see the time parameters page.

Image Flags

Name	Description	Default	Type
title	Set the graph title	no title	String
no_legend	Suppresses the legend	0	boolean
no_legend_stats	Suppresses summary stats for the legend	0	boolean
axis_per_line	Put each line on a separate Y-axis	0	boolean
only_graph	Only show the graph canvas	0	boolean
vision	Simulate different vision types	normal	vision type

Image Size

There are four parameters to control the image size and layout used for a graph:

Name	Description	Default	Type
layout	Mode for controlling exact or relative sizing	canvas	layout mode
w	Width of the canvas or image	700*	int
h	Height of the canvas or image	300*	int
zoom	Transform the size by a zoom factor	1.0	float

For more information on the behavior see the graph layout page.

Y-Axis

Name	Description	Default	Type
stack	Set the default line style to stack	0	boolean
l	Lower bound for the axis	auto-style	axis bound
u	Upper bound for the axis	auto-style	axis bound
ylabel	Label for the axis	no label	String
palette	Color palette to use	armytage	palette
o	Use a logarithmic scale (deprecated in 1.6)	0	boolean
scale	Set the axis scale to use (since 1.6)	linear	scale
tick_labels	Set the mode to use for tick labels	decimal	tick label mode
sort	Set the mode to use for sorting the legend	expr order	sort mode
order	Set the order ascending or descending for the sort	asc	order

Output Format

Name	Description	Default	Type
format	Output format to use	png	output format
callback	Method name to use for JSONP callback	none	String

Defaults

If marked with an * the default shown can be changed by the administrator for the Atlas server. As a result the default in the table may not match the default you see. The defaults listed do match those used for the primary Atlas backends in use at Netflix.

For users running their own server, the config settings and corresponding query params are:

Key	Query Param
atlas.webapi.graph.start-time	s
atlas.webapi.graph.end-time	e
atlas.webapi.graph.timezone	tz
atlas.webapi.graph.width	w
atlas.webapi.graph.height	h
atlas.webapi.graph.palette	palette

Boolean Flags

Flags with a true or false value are specified using 1 for true and 0 for false.