Grafana

Grafana shows fenecdb two ways: the server's health through Prometheus, and the data itself — visitors, top pages, price candles — through fenecdb's own data source, each panel one FenecQL statement with the dashboard's range and variables bound as parameters, alert rules included. The repository's monitoring/ runs all of it with one docker compose up.

Metrics and data

The dashboards read different things, by different paths, with different tokens.

Run it

FENEC_HTTP_TOKEN=secret FENEC_METRICS_TOKEN=scrape \
FENEC_JWT_SECRET=$(openssl rand -hex 32) \
  docker compose -f monitoring/docker-compose.yml up -d --build
# the data:     http://127.0.0.1:3000/d/fenecdb-data-plugin
# the metrics:  http://127.0.0.1:3000/d/fenecdb

# down, the data and the token with it
docker compose -f monitoring/docker-compose.yml down -v

• Seeded data. The first start writes thirty days of a product site's events, made by the traffic simulator of examples/analytics, and a week of trades in twenty invented symbols, 60 000 a day: about 108 000 events and 470 000 trades, written in two seconds.
• Grafana 13.2.2 with the plugin built from the checkout (integrations/grafana/Dockerfile: webpack for its frontend, mage for its backend), unsigned and let in by name; the Infinity plugin 4.1.1 beside it. The first build took 1 min 25 s on an M1 Air.
• No code in fenecdb's server. Both data sources speak the HTTP endpoint every client speaks; the plugin through the Go SDK.

apiVersion: 1
datasources:
  - name: fenecdb
    type: fenecdb-datasource
    uid: fenecdb
    url: http://fenecdb:8080
    jsonData:
      tenant: acme          # optional: requests go to /t/acme/
    secureJsonData:
      token: $__file{/run/fenec/grafana.jwt}

A panel's query

A panel's query is FenecQL. Grafana's range and interval, and the dashboard's variables, are named in it; the plugin's backend makes each name a $n parameter and sends the statement with the values beside it, never in its text.

get ticks select bucket(at, $__interval_ms) as time, sym, sum(qty) as volume
  where sym in $syms and at >= $__from and at < $__to
  group time, sym order time

{"query": "get ticks select bucket(at, $1) as time, sym, sum(qty) as volume where sym in [$2, $3, $4] and at >= $5 and at < $6 group time, sym order time",
 "params": [900000, "S19", "S04", "S03", 1791072000000, 1791683333856]}

• $__from and $__to are the range in epoch milliseconds, which a timestamp field compares with as it is; $__interval_ms is the interval Grafana picks for the panel's width, which bucket takes as milliseconds; $__max_data_points its width in points, which limit $__max_data_points holds a series to. The backend works them out from the request, so an alert rule has them as a panel does.
• A dashboard variable is $sym or ${sym}, a text; ${n:int} reads it as number, int, float, bool, timestamp or json. A name used twice is one parameter.
• A multi-value variable goes after in: sym in $syms is sent as sym in [$2, $3, $4], a parameter a value, since FenecQL's in takes a list of values and a parameter binds one. Nothing picked is in [], no rows.
• The columns come in the select list's order, typed: numbers, times, text, JSON, a geo point as its longitude and latitude. No transformation between the answer and the panel.
• A time series when the statement groups by its first column, a time — or when the editor's format says so. Text columns beside it are labels, so a group by time and symbol is a series a symbol.

-- Events, visitors and signups
get events select count(*) as Events, count(distinct user) as Visitors, sum(case when name = "signup_completed" then 1 else 0 end) as Signups where at >= $__from and at < $__to
-- Visitors over time
get events select bucket(at, $__interval_ms) as Time, count(*) as Events, count(distinct user) as Visitors where at >= $__from and at < $__to group Time order Time
-- Top pages
get events select path as Page, count(*) as Views, count(distinct user) as Visitors where name = "pageview" and at >= $__from and at < $__to group Page order Views desc limit 10
-- Distinct users per day
get events select bucket(at, 1d) as Day, count(distinct user) as Users where at >= $__from and at < $__to group Day order Day
-- The symbol variable, and the symbols, most traded first
get ticks select sym, count(*) as trades group sym order sym
get ticks select sym, sum(qty) as volume group sym order volume desc
-- Candles of $sym, and each day's high of it as annotations
get ticks select bucket(at, $__interval_ms) as Time, first(px by at) as open, max(px) as high, min(px) as low, last(px by at) as close, sum(qty) as volume where sym = $sym and at >= $__from and at < $__to group Time order Time
get ticks select last(at by px) as time, max(px) as text, bucket(at, 1d) as day where sym = $sym and at >= $__from and at < $__to group day order day
-- Latest price per symbol
get ticks select sym as Symbol, last(px by at) as Price, (last(px by at) - first(px by at)) / first(px by at) * 100 as Change, sum(qty) as Volume where at >= $__from and at < $__to group Symbol order Symbol
-- Volume by symbol: a series each
get ticks select bucket(at, $__interval_ms) as Time, sym, sum(qty) as volume where sym in $syms and at >= $__from and at < $__to group Time, sym order Time

Alert rules

A rule runs its query in Grafana's backend, with no browser to fill in a value, so it needs a data source that binds them itself. The compose provisions one over the trades: the last ten minutes' volume of each symbol, firing above 2 000.

# monitoring/grafana/provisioning/alerting/fenecdb.yml (its query)
datasourceUid: fenecdb
relativeTimeRange: {from: 21600, to: 0}
model:
  format: time_series
  intervalMs: 600000
  queryText: >-
    get ticks select bucket(at, $__interval_ms) as time, sym, sum(qty) as volume
    where at >= $__from and at < $__to group time, sym order time

• An instance a symbol, labelled sym=S01, ...: the group by time and symbol is a series a symbol, which the rule's reduce and threshold take one at a time.
• The rule's range and interval are bound as a panel's are: the plugin reads them off the request Grafana's backend makes.
• A dashboard variable has no value in a rule, and a query naming one is refused saying so rather than run without it.

Refreshes

The plugin keeps the answer to each statement and its parameters with its ETag, and sends the same request again with If-None-Match: a 304 is answered from the kept answer (Polling a read).

Over the seeded week, the median of 21 runs of each, the ways in turns, from the host into Docker on an M1 Air: fenec-server directly, Grafana through Infinity, Grafana through the plugin with a new answer each time (the range's end moved a millisecond a run, as a refresh's now moves), and the same request again, answered 304 — with the read-only JWT and with the server's token.

• The plugin adds 2 to 5 ms a panel over the direct request, Infinity 3 to 8.
• With the server's token a 304 runs nothing: the server answers it from its change counter while nothing the statement reads was written, 3 to 5 ms whatever the statement.
• With a scoped token it runs the statement and compares a digest of the answer, which saves the transfer and the plugin's parsing only: a 304 by the counter would tell the token when anyone wrote to what it reads.
• A range ending at now is a new request every refresh. A variable's query, an absolute range, or one rounded (now/h) ask the same one again. Grafana's own query caching is Grafana Enterprise's and Cloud's, not the open-source build's.

node monitoring/grafana/bench.mjs measures it against a running stack.

The plugin or Infinity

The Infinity plugin reads fenecdb with nothing to build or install beyond Grafana's catalog; monitoring/ keeps its dashboard (/d/fenecdb-data) beside the plugin's.

{
  "query": "get ticks select bucket(at, $4) as t, first(px by at) as open, max(px) as high, min(px) as low, last(px by at) as close, sum(qty) as volume where sym = $3 and at >= $1 and at < $2 group t order t",
  "params": [${__from}, ${__to}, ${sym:doublequote}, $__interval_ms]
}

apiVersion: 1
datasources:
  - name: fenecdb data
    type: yesoreyeram-infinity-datasource
    uid: fenecdb-data
    url: http://fenecdb:8080
    jsonData:
      auth_method: bearerToken
      allowedHosts:
        - http://fenecdb:8080/query
    secureJsonData:
      bearerToken: $__file{/run/fenec/grafana.jwt}

The read-only token

Both data sources read with a JSON Web Token whose role the server's policy lets read two collections and write nothing.

# monitoring/policy.txt
events          read                   for grafana
ticks           read                   for grafana

• It decides what a Grafana user reads. Any viewer can send a data source any query, through POST /api/ds/query, whatever its dashboards say. A put, set or del is 403, and so is a schema change or /_changes; /_metrics and the statement counts take no JSON Web Token at all, and a collection the policy does not name does not exist for it.
• It is a secret of the data source, encrypted in Grafana's database and handed to the plugin's backend alone: in no dashboard JSON, query, inspector or page's settings.
• A variable is a value. Opened with a symbol written to close a string and send a statement of its own, the plugin sends it as one parameter and the candles show no data.

Checked end to end

make grafana-check starts monitoring/'s compose on ports of its own and asks Grafana's /api/ds/query for every panel's, variable's and annotation's query of both data dashboards, as a viewer, holding each frame to the same FenecQL sent to fenec-server directly — through the plugin, column by column in the select list's order, the statement it sent included, and a series a label where it made one. Then the alert rule must have evaluated, an instance a symbol, firing where the server's rows say; and the refusals: a write, symbols written to close their string, the token in no page's reach. CI runs it with the plugin's own tests and its backend built for linux/amd64 and arm64.