@marble-sh/backstage-plugin-grafana-common 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @marble-sh/backstage-plugin-grafana-common
 
+## 1.2.1
+
+### Patch Changes
+
+- c9c9f23: Documentation: a full entity-annotation reference (exact matching semantics,
+  how the annotations combine, visibility gating, and error behavior for
+  unknown instance names) in the frontend and common READMEs, and a new
+  "Creating the Grafana service account and token" walkthrough in the backend
+  README — UI steps, the Grafana Cloud `glsa_` vs `glc_` token distinction,
+  and a per-feature permission table (Viewer covers all read paths;
+  `datasources:query` caveat for panel graphs under Enterprise/Cloud data
+  source permissions; Editor / `fixed:dashboards:writer` for the scaffolder
+  module).
+
+## 1.2.0
+
+### Minor Changes
+
+- a31b91d: Added: the dashboards tab now renders real graphs and the alerts tab a live
+  detail table. The backend gained read-only panel routes
+  (`GET …/dashboards/:uid/panels` and `GET …/panels/:panelId/data?from&to`)
+  that read a dashboard's model, resolve its template variables' current
+  values, query the panel targets through Grafana's `/api/ds/query`, and
+  return normalized time series — gated by the new `grafana.allowPanelQueries`
+  flag and cached per `grafana.panelDataCacheTtl` (default 30s). The frontend
+  draws `timeseries`/`graph` panels as charts and `stat`/`gauge`/`singlestat`
+  panels as value tiles, per-dashboard and lazily, with a time-range picker
+  and refresh. Alerts are enriched with rule uid (deep links), health,
+  active-since, active instance count, dashboard/panel links, and the
+  `summary` annotation. `GrafanaClient`/`GrafanaService` gained _optional_
+  `getPanels`/`getPanelData` members, so existing custom implementations
+  remain compatible.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -12,16 +12,28 @@ It provides:
 
 ## Entity annotations
 
-| Annotation                     | Helper                   | Meaning                                                            |
-| ------------------------------ | ------------------------ | ------------------------------------------------------------------ |
-| `grafana/instance`             | `getGrafanaInstanceName` | Which configured Grafana instance the entity belongs to.           |
-| `grafana/dashboard-selector`   | `getDashboardSelector`   | Comma-separated title substrings; any match selects the dashboard. |
-| `grafana/dashboard-uid`        | `getDashboardUid`        | A single dashboard uid (exact, case-sensitive match).              |
-| `grafana/tag-selector`         | `getTagSelector`         | A comma-separated list of dashboard tags.                          |
-| `grafana/alert-label-selector` | `getAlertLabelSelector`  | A `key=value,...` list of alert label matchers.                    |
-
-`isGrafanaAvailable(entity)` returns `true` when an entity carries any of the
-above annotations, and is used to gate the Grafana entity tabs and cards.
+| Annotation                     | Helper                   | Meaning                                                                                                          |
+| ------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `grafana/instance`             | `getGrafanaInstanceName` | The `grafana.instances[].name` the entity belongs to (exact match). Absent = query all configured instances.     |
+| `grafana/dashboard-selector`   | `getDashboardSelector`   | Comma-separated, case-insensitive title substrings; **any** match selects the dashboard.                         |
+| `grafana/dashboard-uid`        | `getDashboardUid`        | A single dashboard uid (exact, case-sensitive match). Written by catalog discovery on its dashboard `Resource`s. |
+| `grafana/tag-selector`         | `getTagSelector`         | Comma-separated dashboard tags; the dashboard must carry **all** of them.                                        |
+| `grafana/alert-label-selector` | `getAlertLabelSelector`  | `key=value,...` alert label matchers; the rule's labels must contain **all** pairs.                              |
+
+The dashboard annotations combine with AND — a dashboard must pass every one
+the entity carries. Empty annotation values are treated as absent. The full
+matching semantics are documented in the
+[frontend plugin README](../grafana/README.md#entity-annotations).
+
+Three gating helpers decide whether an entity has Grafana content to show:
+
+- `isDashboardsAvailable(entity)` — any of `grafana/instance`,
+  `grafana/dashboard-selector`, `grafana/dashboard-uid`, or
+  `grafana/tag-selector` is present.
+- `isAlertsAvailable(entity)` — `grafana/instance` or
+  `grafana/alert-label-selector` is present.
+- `isGrafanaAvailable(entity)` — either of the above; used to gate the Grafana
+  entity tabs and cards.
 
 ```ts
 import {

package/dist/index.d.ts

@@ -146,6 +146,12 @@ type GrafanaDashboard = {
  * @public
  */
 type GrafanaAlertState = 'firing' | 'pending' | 'inactive' | 'normal' | 'no_data' | 'error' | 'unknown';
+/**
+ * The evaluation health of a Grafana alert rule.
+ *
+ * @public
+ */
+type GrafanaAlertHealth = 'ok' | 'error' | 'nodata' | 'unknown';
 /**
  * A Grafana alert rule together with its current state.
  *
@@ -164,6 +170,90 @@ type GrafanaAlert = {
     folderTitle?: string;
     /** The name of the instance this alert was read from. */
     instanceName: string;
+    /** The alert rule uid, when the source API provides one. */
+    uid?: string;
+    /** The evaluation health of the rule. */
+    health?: GrafanaAlertHealth;
+    /** The rule's `summary` annotation, if any. */
+    summary?: string;
+    /** ISO-8601 timestamp of when the rule became active, when it is. */
+    activeAt?: string;
+    /** The number of currently active (pending or firing) alert instances. */
+    activeCount?: number;
+    /** The uid of the dashboard the rule is linked to, if any. */
+    dashboardUid?: string;
+    /** The id of the panel the rule is linked to, if any. */
+    panelId?: number;
+};
+/**
+ * How a Grafana panel is rendered by the frontend.
+ *
+ * - `timeseries`: rendered as a chart (Grafana `timeseries` and legacy `graph`
+ *   panels).
+ * - `stat`: rendered as a single-value tile (Grafana `stat`, `gauge`, and
+ *   legacy `singlestat` panels).
+ * - `unsupported`: not rendered; shown as a link into Grafana.
+ *
+ * @public
+ */
+type GrafanaPanelKind = 'timeseries' | 'stat' | 'unsupported';
+/**
+ * A single panel of a Grafana dashboard, as listed by the backend.
+ *
+ * @public
+ */
+type GrafanaPanel = {
+    /** The panel id, unique within its dashboard. */
+    id: number;
+    /** The panel title. */
+    title: string;
+    /** The raw Grafana panel type (`timeseries`, `stat`, `table`, ...). */
+    type: string;
+    /** How the frontend renders this panel. */
+    kind: GrafanaPanelKind;
+    /** The panel description, if any. */
+    description?: string;
+    /** The uid of the dashboard containing the panel. */
+    dashboardUid: string;
+    /** The name of the instance the panel was read from. */
+    instanceName: string;
+};
+/**
+ * A single point of a time series: a timestamp and a value.
+ *
+ * @public
+ */
+type GrafanaPanelPoint = {
+    /** The point's timestamp, in epoch milliseconds. */
+    timeMs: number;
+    /** The point's value; `null` marks a gap in the series. */
+    value: number | null;
+};
+/**
+ * A single named series of a panel's query results.
+ *
+ * @public
+ */
+type GrafanaPanelSeries = {
+    /** The display name of the series. */
+    name: string;
+    /** The labels attached to the series, if any. */
+    labels?: Record<string, string>;
+    /** The data points, ordered by time. */
+    points: GrafanaPanelPoint[];
+};
+/**
+ * The queried data of a single panel, normalized from Grafana data frames.
+ *
+ * @public
+ */
+type GrafanaPanelData = {
+    /** The id of the panel the data belongs to. */
+    panelId: number;
+    /** The normalized series, across all of the panel's queries. */
+    series: GrafanaPanelSeries[];
+    /** Human-readable notes about queries that failed or were skipped. */
+    warnings?: string[];
 };
 /**
  * Response body for `GET /instances`.
@@ -189,6 +279,20 @@ type ListDashboardsResponse = {
 type ListAlertsResponse = {
     items: GrafanaAlert[];
 };
+/**
+ * Response body for the panel listing endpoint.
+ *
+ * @public
+ */
+type ListPanelsResponse = {
+    items: GrafanaPanel[];
+};
+/**
+ * Response body for the panel data endpoint.
+ *
+ * @public
+ */
+type GetPanelDataResponse = GrafanaPanelData;
 
 export { GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR, GRAFANA_ANNOTATION_DASHBOARD_UID, GRAFANA_ANNOTATION_INSTANCE, GRAFANA_ANNOTATION_TAG_SELECTOR, getAlertLabelSelector, getDashboardSelector, getDashboardUid, getGrafanaInstanceName, getTagSelector, isAlertsAvailable, isDashboardsAvailable, isGrafanaAvailable, parseLabelSelector, parseTagSelector };
-export type { GrafanaAlert, GrafanaAlertState, GrafanaDashboard, GrafanaInstanceInfo, ListAlertsResponse, ListDashboardsResponse, ListInstancesResponse };
+export type { GetPanelDataResponse, GrafanaAlert, GrafanaAlertHealth, GrafanaAlertState, GrafanaDashboard, GrafanaInstanceInfo, GrafanaPanel, GrafanaPanelData, GrafanaPanelKind, GrafanaPanelPoint, GrafanaPanelSeries, ListAlertsResponse, ListDashboardsResponse, ListInstancesResponse, ListPanelsResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marble-sh/backstage-plugin-grafana-common",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Common functionality for the Grafana Backstage plugins (types, annotations, and API contracts)",
   "main": "./dist/index.cjs.js",
   "types": "./dist/index.d.ts",