XY charts

TL;DR

Ask your agent

Use Plotwork to draw an XY chart of the p50 and p95 latency of our checkout API over the last eight weeks. p95 by week: 310, 330, 345, 420, 455, 440, 350, 335. p50 by week: 120, 125, 128, 160, 170, 165, 135, 130. Draw p95 as bars, p50 as a line, our 400 ms objective as a red line, and note the 2.3 release in week 4 and the cache fix in week 7.

Use Plotwork to draw a stacked bar chart of our cloud cost per month in dollars, January to June, split into compute, storage, network, and other. Start the axis at zero.

Use Plotwork to draw a sideways bar chart that ranks our six slowest endpoints by p95 latency in milliseconds, slowest first, with the 400 ms objective as a line.

Example

Eight weeks of latency against an objective (the SLO, a service level objective). The p95, the 95th percentile of latency, is drawn as bars, so each week that crosses the 400 ms line is red, and the p50, the median, is a line. Each series is named beside its last point, the objective is named at the end of its line, and two notes mark what changed.

PictureSourceOutline

The language

One statement to a line. Text is always in double quotes, options are key=value, a list is in square brackets, and # starts a comment. Write a negative number with its sign in front (-5), and put text that holds +, (, <, #, or a bare / in quotes.

A series has a name that is unique in any case, and one value for each place on the axis. A value is a plain number with an optional fraction. A thousands mark, a percent sign, a unit, and an exponent are errors, and the hint says what to write: 1200, not 1,200, and 40 on a y axis with unit="%", not 40%.

Options

Bars, lines, and areas

A bar draws a bar for each place, up to 28px thick, side by side when there are several bar series. Its top has soft corners and its foot is square. A line joins the points with a 2px line, marks each point, and marks the last point larger. An area is a line with a wash of its tone under it. Draw the one that matches the question: bars to compare sizes, lines to show a trend, areas for a quantity that accumulates.

The series take blue, orange, aqua, violet, amber, green, red, and neutral in turn. A tone= on a series keeps that tone, and the others take the next ones that nobody has claimed, so two series never share a hue until all eight are in use. Nobody writes a color value: the theme owns every color, in light and in dark, and every mark keeps at least 3:1 against the plate.

Axes and ticks

Ticks are on round numbers (1, 2, or 5 times a power of ten), and a free end of the axis is pushed out to the next tick so that the data never touches it. Bars and areas always start at zero. A chart of lines alone starts at zero too, unless its smallest value is more than half its largest, where it starts at the tick below the data, because the question is then the change. min= and max= fix an end exactly, and a min= above zero under bars or areas draws a warning.

A symbol unit ($, %) is written on the numbers, and a word unit (ms, req/s) goes in the title of the axis in brackets: Latency (ms). Pills, thresholds, and the text description always write the unit in full. Large ticks are compact: 250K, 1.5M.

A number axis spreads the values of every series evenly over a range, so each series has the same number of values:

1x "Requests per second" 0 to 10002line "p99" [110 155 330 880 1700]

Naming the series

Up to four series on an upright chart are named by a pill in the gutter at the right of the plot, level with the series' last point, with the last value after the name. A bar series is named level with its last bar, and a stacked series level with its slice. Pills that would touch are spread by the least movement that keeps them apart. The name is in the ink color, with a small mark in the series' tone beside it, because a light hue is not legible as text.

More than four series, and every sideways chart, are named in a legend of pills above the plot, after the title of the axis. A single series under a titled axis is not named at all, since the title says it.

Thresholds

A threshold is a labelled line across the plot, dashed in its tone, named in a pill at its right end. It is the most useful element of an engineering chart: an objective, a quota, a capacity. Bars and points on the wrong side of it are drawn in its tone, and the text description lists which crossed.

breach= chooses the side: above for a limit that must not be passed, below for a floor, and none for a line that is only a reference. The axis grows to hold the line. A stacked bar keeps its own tones, because its segments are not the value the line is about.

Notes

A note is a pill above the plot with a dotted line down to its place. Two notes that would touch go to separate rows. A note is not available on a sideways chart, where a threshold names a number instead.

Capacity against a limit

An area for the quantity, a line for a second one, and a limit in amber. The points of the area that cross the limit are marked in its tone, and the symbol unit rides on the ticks.

PictureSourceOutline

Stacked bars

stack=on stacks the bar series on one another, in the order written, with a gap of the plate between segments. Each stack is named once by its total above it, and each service is named level with its slice. Use it for parts of a total that changes. A stack hides the size of every segment but the lowest, so keep it to a few series.

PictureSourceOutline

A sideways ranking

direction=horizontal puts the places down the side, one row each, which is how a ranking reads and how long names fit. The numbers sit beside the bars, the threshold stands above the plot, and the series is named by the title of the axis.

PictureSourceOutline

Numbers on the bars

A number is written above each bar, in the ink color, when there is room for it. When two numbers would touch, none is written, so a chart never has some numbers and not others for want of room. A number that a line or a threshold would run through is left out alone. values=off leaves them all out. The text description carries every value either way.

Labels on a crowded axis

A place name wraps to two lines at a space. When even the longest word is wider than the room a place has, only every second, third, or later place is named, and lint warns. The other places are still drawn, and the text description names every one. Chart fewer places, or draw the chart sideways, to name them all.

Limits and warnings

Honest charts

A chart can mislead by what it leaves out. Plotwork warns instead of drawing a chart that does. A warning never stops the drawing.

Limits

Errors

Every mistake comes back as a result with a code, a line, a column, and a hint. All the codes are the shared ones.

From Mermaid

Mermaid xychart-beta and xychart convert to an XY chart. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full.

1xychart-beta2    title "Sales Revenue"3    x-axis [jan, feb, mar, apr, may, jun]4    y-axis "Revenue (in $)" 4000 --> 110005    bar [5000, 6000, 7500, 8200, 9500, 10500]6    line [5000, 6000, 7500, 8200, 9500, 10500]

Mermaid does not name its series, so the converter names them Bars and Line and says so (M204). Rename them so the names beside the lines say what each one is. The axis starts at 4,000 because Mermaid said so, and a bar chart that does not start at zero draws a warning:

1xychart "Sales Revenue"2
3x ["jan" "feb" "mar" "apr" "may" "jun"]4y "Revenue (in $)" min=4000 max=110005bar "Bars" [5000 6000 7500 8200 9500 10500]6line "Line" [5000 6000 7500 8200 9500 10500]

See also