Ascii.Pieces.Sparkline (Ascii v0.3.0)

Copy Markdown View Source

Three live block sparklines scrolling left, values at right.

Live metrics as one-row block sparklines, scrolling left as new samples arrive, each with its label, its latest value and the span's range. As upstream draws it, three made-up signals play; give each series its values and it shows yours.

Options

Give them to Ascii.new/2 as options:, and new ones while it plays with Ascii.put_options/2 (or a Phoenix player's options) as samples come: a series' values show as given, the newest at the right. Ascii.Telemetry.sparkline/2 gives a series a metric from your app's telemetry, and Ascii.BEAM.sparkline/2 this BEAM's memory, processes and run queue.

  • series - up to five, each a map of:

    • label - its name, on the left.
    • values - its samples, oldest first, up to 10^15 either way; the newest that fit show. Without, it plays a sample signal.
    • lo, hi - the scale's ends; without, it fits what is shown.
    • unit, digits - after the latest value, and its decimals.

    Spaced a row apart when there are three or fewer. Default upstream's cpu, memory and requests. Upstream's format function is not taken: options are data.

  • range - false drops the min and max columns, and the lines grow longer. Default true.

  • rate - samples a second, 0 to 100, which labels the time axis. Default 4.

  • cols - the frame's width, 40 to 200; the lines take what the label, value and range leave. Default 72.

  • rows - the frame's height, 3 to 32, never fewer than the series and their header and axis need. Default 9.

A value too wide for its column, which upstream writes past it, is written to fit: with fewer decimals, then compactly, in thousands, millions and on (17.5M, 3.02G; see Ascii.Kit.Number).

Colours

In one ink, or a gradient, with :ink and :gradient (see Ascii.Ink); part by part with :parts (see Ascii.Parts), parts: true taking the colours suggested here:

  • title - the headings over the range, grey.
  • label - a series' name.
  • spark - the sparklines, blue, and spark.1 to spark.5, one series each from the top: spark.1 as spark, spark.2 cyan, spark.3 purple, spark.4 pink, spark.5 orange.
  • axis - the mark closing each line at now, grey.
  • value, unit - a series' latest value.
  • value.min, value.max - its range, grey.
  • scale - the time axis under them, grey.

Keys and clicks

It takes none: it shows samples, and Ascii.handle_event/2 ignores every event. A Phoenix player given interactive and notify still tells your LiveView where it was clicked, and on which part (Ascii.part_at/4): spark.2, say, for the second series.

Screen readers

Ascii.describe/1 reads each series given values, its label and latest value: "sparkline: cpu 34%, memory 2.1 gb". With no series given values, it gives the piece's name and note.

Example

cpu = %{label: "cpu", unit: "%", lo: 0, hi: 100, values: [12, 30, 25, 60]}
spark = Ascii.new!("sparkline", options: %{series: [cpu], range: false, rows: 3}, parts: true)

spark = Ascii.put_options!(spark, series: [%{cpu | values: cpu.values ++ [45]}])
Ascii.describe(spark)
#=> "sparkline: cpu 45%"

{frame, _spark} = Ascii.frame(spark, 1.0)
frame.text =~ "45%"
#=> true
<Ascii.Phoenix.live_player id="history" piece="sparkline" options={%{series: [%{label: "cpu", unit: "%", values: @cpu}]}} parts />

Ported from src/pieces/sparkline.ts in bas3line/ascii (MIT).