@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/promql-check.ts

@@ -0,0 +1,189 @@
+/**
+ * GRAF108: the PromQL a dashboard sends to Prometheus, syntax-checked with
+ * the prometheus lexicon's `checkPromql` (the grammar behind the Prometheus
+ * web UI's editor, `@prometheus-io/lezer-promql`).
+ *
+ * Only queries that reach a Prometheus datasource are parsed, as
+ * `datasourceUses()` resolves them: a query's own ref, else its panel's, a
+ * datasource variable's plugin type, or an undeclared ref's own `type`. A
+ * query whose datasource can't be told (no ref at all, a `-- Mixed --` panel
+ * query with none of its own) is left alone.
+ *
+ * Grafana interpolates template variables before Prometheus sees the query,
+ * so `$var`, `${var}`, `${var:format}`, `[[var]]` and the `$__` macros are
+ * replaced with a placeholder that parses where they stand: a duration
+ * inside `[...]` or after `offset`, a number for the `_ms`/`_s` macros and
+ * `$__from`/`$__to`, an identifier anywhere else. Inside a string literal
+ * they are left as they are.
+ */
+
+import { checkPromql } from "@intentius/chant-lexicon-prometheus/promql";
+import { datasourceUses, variablesOf, type KnownDatasource } from "./datasource-refs";
+
+type Json = Record<string, unknown>;
+
+const DURATION = "5m";
+const NUMBER = "1";
+const IDENTIFIER = "grafana_var";
+
+/** A template variable reference starting at the regex's lastIndex. */
+const VARIABLE = /\$\{([^}]*)\}|\[\[([A-Za-z_][^\]]*)\]\]|\$([A-Za-z_][A-Za-z0-9_]*)/y;
+
+function isNumericMacro(name: string): boolean {
+  if (name === "__from" || name === "__to") return true;
+  return (name.startsWith("__") || name === "interval_ms") && /_(ms|s)$/.test(name);
+}
+
+/** A span of substituted text and the original text it replaced. */
+interface Span {
+  at: number;
+  length: number;
+  original: number;
+  originalLength: number;
+}
+
+export interface Substituted {
+  text: string;
+  /** Maps an offset in `text` back to one in the original query. */
+  originalOffset(at: number): number;
+}
+
+/** Replace every template variable outside a string literal with a placeholder that parses in its place. */
+export function substituteTemplateVariables(query: string): Substituted {
+  let out = "";
+  const spans: Span[] = [];
+  let quote: string | undefined;
+  let depth = 0;
+  let i = 0;
+  while (i < query.length) {
+    const c = query[i];
+    if (quote) {
+      out += c;
+      if (c === "\\" && quote !== "`" && i + 1 < query.length) {
+        out += query[i + 1];
+        i += 2;
+        continue;
+      }
+      if (c === quote) quote = undefined;
+      i++;
+      continue;
+    }
+    if (c === "$" || (c === "[" && query[i + 1] === "[")) {
+      VARIABLE.lastIndex = i;
+      const m = VARIABLE.exec(query);
+      if (m) {
+        const name = (m[1] ?? m[2] ?? m[3]).split(/[:.]/)[0].trim();
+        const before = out.trimEnd();
+        let value: string;
+        if (depth > 0 || /\boffset$/i.test(before)) {
+          // `[${n}m]`: the unit follows, so only the number is substituted.
+          value = /[a-z]/i.test(query[i + m[0].length] ?? "") ? NUMBER : DURATION;
+        } else if (isNumericMacro(name) || before.endsWith("@")) {
+          value = NUMBER;
+        } else {
+          value = IDENTIFIER;
+        }
+        spans.push({ at: out.length, length: value.length, original: i, originalLength: m[0].length });
+        out += value;
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (c === '"' || c === "'" || c === "`") quote = c;
+    else if (c === "[") depth++;
+    else if (c === "]" && depth > 0) depth--;
+    out += c;
+    i++;
+  }
+  return {
+    text: out,
+    originalOffset(at: number): number {
+      let shift = 0;
+      for (const s of spans) {
+        if (at < s.at) break;
+        if (at < s.at + s.length) return s.original;
+        shift = s.original + s.originalLength - (s.at + s.length);
+      }
+      return at + shift;
+    },
+  };
+}
+
+export type PromqlSyntax = { ok: true } | { ok: false; message: string };
+
+/** Check one query's PromQL syntax after substituting its template variables. */
+export function checkGrafanaPromql(query: string): PromqlSyntax {
+  const substituted = substituteTemplateVariables(query);
+  const checked = checkPromql(substituted.text);
+  if (checked.ok) return { ok: true };
+  const at = Math.min(substituted.originalOffset(checked.position), query.length);
+  if (at >= query.length) return { ok: false, message: `the expression ends early (after "${query.slice(Math.max(0, at - 30)).trim()}")` };
+  const before = query.slice(Math.max(0, at - 30), at);
+  const after = query.slice(at, at + 30);
+  return { ok: false, message: `syntax error at offset ${at}: "${before}" >>> "${after}"` };
+}
+
+/**
+ * The PromQL inside a Prometheus query variable's query. Grafana handles
+ * `label_names()`, `label_values(selector, label)`, `metrics(regex)` and
+ * `query_result(expr)` itself and sends only the selector or expression; any
+ * other text is a series selector (`/api/v1/series?match[]=`).
+ */
+export function variablePromql(query: string): string[] {
+  const q = query.trim();
+  if (q === "" || /^label_names\(\s*\)$/.test(q)) return [];
+  let m = /^label_names\((.+)\)$/.exec(q);
+  if (m) return [m[1]];
+  m = /^label_values\((?:(.+),\s*)?([a-zA-Z_$][a-zA-Z0-9_]*)\)$/.exec(q);
+  if (m) return m[1] ? [m[1]] : [];
+  if (/^metrics\((.+)\)$/.test(q)) return [];
+  m = /^query_result\((.+)\)$/.exec(q);
+  if (m) return [m[1]];
+  return [q];
+}
+
+function variableQueryText(variable: Json): string | undefined {
+  const q = variable.query;
+  if (typeof q === "string") return q;
+  if (q && typeof q === "object" && typeof (q as Json).query === "string") return (q as Json).query as string;
+  return undefined;
+}
+
+/** One piece of PromQL a dashboard sends to Prometheus, and where it is written. */
+export interface PromqlUse {
+  where: string;
+  expr: string;
+}
+
+/** The PromQL of one dashboard (or, for a library panel, a one-panel stand-in); `library` names the `__elements` key. */
+function usesOf(dashboard: Json, known: ReadonlyMap<string, KnownDatasource>, library?: string): PromqlUse[] {
+  const out: PromqlUse[] = [];
+  for (const use of datasourceUses(dashboard, known)) {
+    if (use.resolved.type !== "prometheus") continue;
+    if (use.kind === "query") {
+      const expr = use.target?.expr;
+      if (typeof expr !== "string" || expr.trim() === "") continue;
+      out.push({ where: library ? `library panel "${library}" query ${String(use.target?.refId ?? "?")}` : use.where, expr });
+    } else if (use.kind === "variable" && use.variable && !library) {
+      const text = variableQueryText(use.variable);
+      if (text) for (const expr of variablePromql(text)) out.push({ where: `${use.where} query`, expr });
+    }
+  }
+  return out;
+}
+
+/** Every PromQL query a dashboard sends to Prometheus: panel queries, query variables and the library panels an export embeds in `__elements`. */
+export function prometheusQueries(dashboard: Json, known: ReadonlyMap<string, KnownDatasource>): PromqlUse[] {
+  const out = usesOf(dashboard, known);
+  const elements = dashboard.__elements;
+  if (elements && typeof elements === "object" && !Array.isArray(elements)) {
+    // The dashboard's variables, so a library panel's `${DS_...}` ref resolves as the dashboard's would.
+    const templating = { list: variablesOf(dashboard) };
+    for (const [key, element] of Object.entries(elements as Json)) {
+      const model = element && typeof element === "object" ? (element as Json).model : undefined;
+      if (!model || typeof model !== "object" || Array.isArray(model)) continue;
+      out.push(...usesOf({ templating, panels: [model] }, known, key));
+    }
+  }
+  return out;
+}

package/src/query.ts

@@ -3,10 +3,11 @@
  * `TempoQuery` (TraceQL) and `LokiQuery` (LogQL), each typed from that
  * plugin's query schema at `GRAFANA_SCHEMA_PIN`.
  *
- * The expression is a string; this lexicon does not parse PromQL, TraceQL or
- * LogQL. What it does check is where the query goes: `datasource` only
- * accepts a datasource of the query's own plugin type, and GRAF101, GRAF102
- * and GRAF103 check the emitted references after a build.
+ * The expression is a string. What the lexicon checks is where the query
+ * goes: `datasource` only accepts a datasource of the query's own plugin
+ * type, and GRAF101, GRAF102 and GRAF103 check the emitted references after
+ * a build. GRAF108 parses the PromQL of every query that reaches a
+ * Prometheus; TraceQL and LogQL are not parsed.
  *
  * `defineQuery` is the extension point for any other datasource plugin, and
  * the three built-ins are defined through it.
@@ -14,15 +15,19 @@
 
 import { createProperty } from "@intentius/chant/runtime";
 import type { Declarable } from "@intentius/chant/declarable";
-import type { DatasourceEntity, DatasourceRef } from "./datasource";
+import type { DatasourceEntity, DatasourceRef, ExternalDatasourceEntity } from "./datasource";
 import type { DatasourceVariableEntity } from "./variables";
 import type { SchemaName } from "./pin";
 import type { Dataquery as PrometheusDataquery } from "./schema/prometheus.gen";
 import type { Dataquery as TempoDataquery } from "./schema/tempo.gen";
 import type { Dataquery as LokiDataquery } from "./schema/loki.gen";
 
-/** Where a query or panel sends its request: a declared datasource, a datasource variable, or the ref of one declared elsewhere. */
-export type DatasourceInput<T extends string = string> = DatasourceEntity<T> | DatasourceVariableEntity<T> | DatasourceRef<T>;
+/** Where a query or panel sends its request: a declared or external datasource, a datasource variable, or the ref of one declared elsewhere. */
+export type DatasourceInput<T extends string = string> =
+  | DatasourceEntity<T>
+  | ExternalDatasourceEntity<T>
+  | DatasourceVariableEntity<T>
+  | DatasourceRef<T>;
 
 /** A query model's fields, less what chant fills in (`datasource`, `refId` stays optional). */
 export type QueryModel<M> = Omit<M, "datasource">;
@@ -108,7 +113,7 @@ function makeQueryClass<T extends string, M>(def: QueryDefinition<T, M>): QueryC
  * });
  * ```
  */
-export function defineQuery<M>() {
+export function defineQuery<M = Record<string, unknown>>() {
   return function <T extends string>(def: Omit<QueryDefinition<T, M>, "builtin">): QueryClass<T, M> {
     return makeQueryClass<T, M>({ ...def, builtin: false });
   };

package/src/schema/barchart.gen.ts

@@ -0,0 +1,221 @@
+// Code generated by chant generate from the vendored Grafana schema
+// src/spec/schemas/barchart.jsonschema.json (see src/pin.ts) and its correction
+// overlay in src/spec/overlay/ (see src/spec/overlay.ts). DO NOT EDIT.
+/* eslint-disable */
+
+export interface Options {
+  /**
+   * Manually select which field from the dataset to represent the x field.
+   */
+  xField?: string;
+  /**
+   * Use the color value for a sibling field to color each bar value.
+   */
+  colorByField?: string;
+  /**
+   * Controls the orientation of the bar chart, either vertical or horizontal.
+   */
+  orientation: VizOrientation;
+  /**
+   * Controls the radius of each bar.
+   */
+  barRadius?: number;
+  /**
+   * Controls the rotation of the x axis labels.
+   */
+  xTickLabelRotation: number;
+  /**
+   * Sets the max length that a label can have before it is truncated.
+   */
+  xTickLabelMaxLength: number;
+  /**
+   * Controls the spacing between x axis labels.
+   * negative values indicate backwards skipping behavior
+   */
+  xTickLabelSpacing?: number;
+  /**
+   * Controls whether bars are stacked or not, either normally or in percent mode.
+   */
+  stacking: StackingMode;
+  /**
+   * This controls whether values are shown on top or to the left of bars.
+   */
+  showValue: VisibilityMode;
+  /**
+   * Controls the width of bars. 1 = Max width, 0 = Min width.
+   */
+  barWidth: number;
+  /**
+   * Controls the width of groups. 1 = max with, 0 = min width.
+   */
+  groupWidth: number;
+  legend: VizLegendOptions;
+  tooltip: VizTooltipOptions;
+  text?: VizTextDisplayOptions;
+  /**
+   * Enables mode which highlights the entire bar area and shows tooltip when cursor
+   * hovers over highlighted area
+   */
+  fullHighlight: boolean;
+}
+
+export interface FieldConfig {
+  /**
+   * Controls line width of the bars.
+   */
+  lineWidth?: number;
+  /**
+   * Controls the fill opacity of the bars.
+   */
+  fillOpacity?: number;
+  /**
+   * Set the mode of the gradient fill. Fill gradient is based on the line color. To change the color, use the standard color scheme field option.
+   * Gradient appearance is influenced by the Fill opacity setting.
+   */
+  gradientMode?: GraphGradientMode;
+  axisPlacement?: AxisPlacement;
+  axisColorMode?: AxisColorMode;
+  axisLabel?: string;
+  axisWidth?: number;
+  axisSoftMin?: number;
+  axisSoftMax?: number;
+  axisGridShow?: boolean;
+  scaleDistribution?: ScaleDistributionConfig;
+  axisCenteredZero?: boolean;
+  hideFrom?: HideSeriesConfig;
+  /**
+   * Threshold rendering
+   */
+  thresholdsStyle?: GraphThresholdsStyleConfig;
+  axisBorderShow?: boolean;
+}
+
+/**
+ * TODO docs
+ */
+export type VizOrientation = "auto" | "vertical" | "horizontal";
+
+/**
+ * TODO docs
+ */
+export type StackingMode = "none" | "normal" | "percent";
+
+/**
+ * TODO docs
+ */
+export type VisibilityMode = "auto" | "never" | "always";
+
+/**
+ * TODO docs
+ */
+export interface VizLegendOptions {
+  displayMode: LegendDisplayMode;
+  placement: LegendPlacement;
+  showLegend: boolean;
+  asTable?: boolean;
+  isVisible?: boolean;
+  sortBy?: string;
+  sortDesc?: boolean;
+  width?: number;
+  calcs: string[];
+}
+
+/**
+ * TODO docs
+ */
+export interface VizTooltipOptions {
+  mode: TooltipDisplayMode;
+  sort: SortOrder;
+  maxWidth?: number;
+  maxHeight?: number;
+  hideZeros?: boolean;
+}
+
+/**
+ * TODO docs
+ */
+export interface VizTextDisplayOptions {
+  /**
+   * Explicit title text size
+   */
+  titleSize?: number;
+  /**
+   * Explicit value text size
+   */
+  valueSize?: number;
+  /**
+   * Explicit percent text size
+   */
+  percentSize?: number;
+}
+
+/**
+ * TODO docs
+ */
+export type GraphGradientMode = "none" | "opacity" | "hue" | "scheme";
+
+/**
+ * TODO docs
+ */
+export type AxisPlacement = "auto" | "top" | "right" | "bottom" | "left" | "hidden";
+
+/**
+ * TODO docs
+ */
+export type AxisColorMode = "text" | "series";
+
+/**
+ * TODO docs
+ */
+export interface ScaleDistributionConfig {
+  type: ScaleDistribution;
+  log?: number;
+  linearThreshold?: number;
+}
+
+/**
+ * TODO docs
+ */
+export interface HideSeriesConfig {
+  tooltip: boolean;
+  legend: boolean;
+  viz: boolean;
+}
+
+/**
+ * TODO docs
+ */
+export interface GraphThresholdsStyleConfig {
+  mode: GraphThresholdsStyleMode;
+}
+
+/**
+ * TODO docs
+ * Note: "hidden" needs to remain as an option for plugins compatibility
+ */
+export type LegendDisplayMode = "list" | "table" | "hidden";
+
+/**
+ * TODO docs
+ */
+export type LegendPlacement = "bottom" | "right";
+
+/**
+ * TODO docs
+ */
+export type TooltipDisplayMode = "single" | "multi" | "none";
+
+/**
+ * TODO docs
+ */
+export type SortOrder = "asc" | "desc" | "none";
+
+/**
+ * TODO docs
+ */
+export type ScaleDistribution = "linear" | "log" | "ordinal" | "symlog";
+
+/**
+ * TODO docs
+ */
+export type GraphThresholdsStyleMode = "off" | "line" | "dashed" | "area" | "line+area" | "dashed+area" | "series";

package/src/schema/bargauge.gen.ts

@@ -0,0 +1,111 @@
+// Code generated by chant generate from the vendored Grafana schema
+// src/spec/schemas/bargauge.jsonschema.json (see src/pin.ts) and its correction
+// overlay in src/spec/overlay/ (see src/spec/overlay.ts). DO NOT EDIT.
+/* eslint-disable */
+
+export interface Options {
+  displayMode: BarGaugeDisplayMode;
+  valueMode: BarGaugeValueMode;
+  namePlacement: BarGaugeNamePlacement;
+  showUnfilled: boolean;
+  sizing: BarGaugeSizing;
+  minVizWidth: number;
+  minVizHeight: number;
+  legend: VizLegendOptions;
+  reduceOptions: ReduceDataOptions;
+  text?: VizTextDisplayOptions;
+  maxVizHeight: number;
+  orientation: VizOrientation;
+}
+
+/**
+ * Enum expressing the possible display modes
+ * for the bar gauge component of Grafana UI
+ */
+export type BarGaugeDisplayMode = "basic" | "lcd" | "gradient";
+
+/**
+ * Allows for the table cell gauge display type to set the gauge mode.
+ */
+export type BarGaugeValueMode = "color" | "text" | "hidden";
+
+/**
+ * Allows for the bar gauge name to be placed explicitly
+ */
+export type BarGaugeNamePlacement = "auto" | "top" | "left" | "hidden";
+
+/**
+ * Allows for the bar gauge size to be set explicitly
+ */
+export type BarGaugeSizing = "auto" | "manual";
+
+/**
+ * TODO docs
+ */
+export interface VizLegendOptions {
+  displayMode: LegendDisplayMode;
+  placement: LegendPlacement;
+  showLegend: boolean;
+  asTable?: boolean;
+  isVisible?: boolean;
+  sortBy?: string;
+  sortDesc?: boolean;
+  width?: number;
+  calcs: string[];
+}
+
+/**
+ * TODO docs
+ */
+export interface ReduceDataOptions {
+  /**
+   * If true show each row value
+   */
+  values?: boolean;
+  /**
+   * if showing all values limit
+   */
+  limit?: number;
+  /**
+   * When !values, pick one value for the whole field
+   */
+  calcs: string[];
+  /**
+   * Which fields to show.  By default this is only numeric fields
+   */
+  fields?: string;
+}
+
+/**
+ * TODO docs
+ */
+export interface VizTextDisplayOptions {
+  /**
+   * Explicit title text size
+   */
+  titleSize?: number;
+  /**
+   * Explicit value text size
+   */
+  valueSize?: number;
+  /**
+   * Explicit percent text size
+   */
+  percentSize?: number;
+}
+
+/**
+ * TODO docs
+ */
+export type VizOrientation = "auto" | "vertical" | "horizontal";
+
+/**
+ * TODO docs
+ * Note: "hidden" needs to remain as an option for plugins compatibility
+ */
+export type LegendDisplayMode = "list" | "table" | "hidden";
+
+/**
+ * TODO docs
+ */
+export type LegendPlacement = "bottom" | "right";