cardano-tracer | timeseries: Prometheus-aligned HTTP API, node info endpoints, Grafana datasource

[Russoul]

Summary

Query language improvements

• epoch parser bug fixed — epoch now correctly produces Timestamp 0 (Unix epoch); previously it parsed identically to now, making epoch + Nms evaluate to ~year 2082 instead of the intended absolute timestamp
• Metric-name awareness in the elaborator — unknown variable names now produce Undefined name: <x> errors at elaboration time instead of confusing downstream type-mismatch errors; St carries availableMetrics :: Set MetricIdentifier populated from the store
• "Did you mean?" suggestions in Undefined-name errors — the elaborator computes Levenshtein distance (via edit-distance) to known metric names and local bindings, appending the closest match to the error message
• Local name shadowing — let x = 1 in let x = 2 in x now correctly returns 2; previously the elaborator rejected re-use of any name
• RangeVector/Scalar arithmetic — +, -, *, / between a range vector and a scalar are now supported in both elaboration and interpretation
• Unit and List types — Unit, Nil, and Cons constructors added to Value and the semantic Expr; metrics expression returns the metric list as a Cons-list of Text values
• sum_over_time elab bug fixed — Surface.SumOverTime was incorrectly elaborated to Semantic.AvgOverTime (copy-paste error)
• Noncanonical arithmetic rules — four new bidirectional rules let the elaborator infer types in previously-stuck expressions:
  • Duration + Duration : ? → result is Duration (e.g. 1s + 2s now elaborates standalone)
  • ? - Duration : ? → lhs must be Timestamp (e.g. \x -> x - 1s infers x : Timestamp)
  • ? + ? : Duration → both args must be Duration (e.g. \x -> \y -> m[now; now : x + y] infers both lambda args)
  • ? - ? : Timestamp → lhs must be Timestamp, rhs must be Duration (e.g. \x -> \y -> m[x - y; x] infers arg types from the range start position)

Test suite

• 362 tests covering the full stack: parser, elaborator, and interpreter
• Parser suite: full coverage of surface expression parsing including operator precedence and associativity
• Elaboration suite: ~115 cases covering literals, arithmetic (well-typed and ill-typed), comparisons, boolean operators, let/lambda, pairs/projections, to_scalar, abs/round, the metrics builtin, range vectors, instant-vector operations, metric-name resolution, and "Did you mean?" suggestions
• Interpretation suite: scalar arithmetic, boolean logic, timestamp/duration arithmetic, instant-vector operations, range-vector aggregations (avg_over_time, sum_over_time, rate, increase, quantile_over_time), label filtering, metrics query, shadowing, and error cases

cardano-tracer timeseries HTTP server

• Query endpoints:
  • POST /timeseries/query — body: application/x-www-form-urlencoded; parameters:
    • query=<expr> (required) — the query expression
    • time=<unix_s> (optional, float) — evaluation instant; defaults to server time (now)
  • Response: {"status":"success","data":<Value>} or {"status":"error","errorType":"...","error":"..."}
  • GET /timeseries/query — same parameters and response, passed as URL query string
• Node metadata endpoints (new, via TracerEnv):
  • GET /timeseries/nodes — JSON array of connected node ID strings
  • GET /timeseries/node/{id}/info — NodeInfo fields plus server-computed uptimeSeconds
  • GET /timeseries/node/{id}/startup — NodeStartupInfo (era, slot length, epoch length, KES period)
  • GET /timeseries/node/{id}/state (RTVIEW) — {"syncProgress":<pct>} from the NodeAddBlock data point
• Data point key fix — the /state endpoint uses key "NodeAddBlock" (the namespace cardano-node actually registers the data point under) rather than "NodeState", which was always empty

Grafana datasource plugin (bench/grafana-datasource/)

• $__from / $__to support — the plugin pre-processes queries before template substitution, rewriting $__from and $__to to epoch + Nms expressions the query language understands; dashboard panels use [$__from; $__to] ranges driven by the Grafana time picker
• Error handling — server-side errors are surfaced as Grafana DataQueryError with the first line as the panel message and the full elaboration/interpretation trace in the inspector
• Node info query types — four additional query types expose RTView header data per connected node:
  • nodes — list of node IDs (populates the $node_id template variable via metricFindQuery)
  • node-info — name, protocol, version, commit, start time, uptime in seconds
  • node-startup — era, slot length, epoch length, KES period length
  • node-state — sync progress percentage
• Provisioned RTView dashboard — panels covering Resources, Blockchain, Leadership, Transactions, and a Node section with Connected Nodes table and per-node Info/Startup/Sync/Uptime panels (all repeating by $node_id via a multi-select query variable)
• Metric name sanitisation — . and - in EKG metric names are replaced with _ so names match the cardano_node_metrics_* convention used in queries

Workbench profiles

• 6-dense-timeseries-1h — 6-node dense-topology profile with tracer.timeseries = true and tracer.rtview = true; 1-hour duration; replaces the earlier 2-node ci-bench-timeseries profile
• macOS compatibility — ps h --ppid (GNU ps) replaced with pgrep -P in supervisor.sh; the former errors on macOS BSD ps causing noisy output on local runs