@marble-sh/backstage-plugin-grafana-common 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @marble-sh/backstage-plugin-grafana-common
 
+## 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
+
+- 476051b: Catalog discovery no longer leaves the `defaultOwner` relation dangling, and
+  every discovered dashboard `Resource` now shows exactly its own dashboard.
+
+  - The entity provider creates a placeholder `Group` (`spec.type: virtual`) for
+    `defaultOwner` while no other catalog source defines that ref; a definition
+    from any other source (e.g. a hand-written catalog-info.yaml) always takes
+    precedence. Disable with `grafana.catalog.emitOwnerGroup: false` — also the
+    handover switch for replacing an existing placeholder with your own
+    definition (see the module README).
+  - New `grafana/dashboard-uid` annotation (exact, case-sensitive uid match),
+    supported end-to-end: `getDashboardUid` in `-common`, `DashboardFilter.uid`
+    in `-node`, a `uid` query parameter on the backend dashboard routes,
+    `ListDashboardsRequest.uid` + `DashboardsCard` support in the frontend, and
+    emitted by catalog discovery on every dashboard `Resource`.
+
 ## 1.0.2
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,7 @@ It provides:
 | ------------------------------ | ------------------------ | ------------------------------------------------------------------ |
 | `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.                    |
 

package/dist/annotations.cjs.js

@@ -2,6 +2,7 @@
 
 const GRAFANA_ANNOTATION_INSTANCE = "grafana/instance";
 const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = "grafana/dashboard-selector";
+const GRAFANA_ANNOTATION_DASHBOARD_UID = "grafana/dashboard-uid";
 const GRAFANA_ANNOTATION_TAG_SELECTOR = "grafana/tag-selector";
 const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = "grafana/alert-label-selector";
 const read = (entity, key) => {
@@ -10,20 +11,23 @@ const read = (entity, key) => {
 };
 const getGrafanaInstanceName = (entity) => read(entity, GRAFANA_ANNOTATION_INSTANCE);
 const getDashboardSelector = (entity) => read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);
+const getDashboardUid = (entity) => read(entity, GRAFANA_ANNOTATION_DASHBOARD_UID);
 const getTagSelector = (entity) => read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);
 const getAlertLabelSelector = (entity) => read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);
 const isDashboardsAvailable = (entity) => Boolean(
-  getGrafanaInstanceName(entity) || getDashboardSelector(entity) || getTagSelector(entity)
+  getGrafanaInstanceName(entity) || getDashboardSelector(entity) || getDashboardUid(entity) || getTagSelector(entity)
 );
 const isAlertsAvailable = (entity) => Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));
 const isGrafanaAvailable = (entity) => isDashboardsAvailable(entity) || isAlertsAvailable(entity);
 
 exports.GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR;
 exports.GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = GRAFANA_ANNOTATION_DASHBOARD_SELECTOR;
+exports.GRAFANA_ANNOTATION_DASHBOARD_UID = GRAFANA_ANNOTATION_DASHBOARD_UID;
 exports.GRAFANA_ANNOTATION_INSTANCE = GRAFANA_ANNOTATION_INSTANCE;
 exports.GRAFANA_ANNOTATION_TAG_SELECTOR = GRAFANA_ANNOTATION_TAG_SELECTOR;
 exports.getAlertLabelSelector = getAlertLabelSelector;
 exports.getDashboardSelector = getDashboardSelector;
+exports.getDashboardUid = getDashboardUid;
 exports.getGrafanaInstanceName = getGrafanaInstanceName;
 exports.getTagSelector = getTagSelector;
 exports.isAlertsAvailable = isAlertsAvailable;

package/dist/annotations.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.cjs.js","sources":["../src/annotations.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity } from '@backstage/catalog-model';\n\n/**\n * Selects which configured Grafana instance an entity belongs to. The value\n * must match an instance `name` in the backend configuration.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_INSTANCE = 'grafana/instance';\n\n/**\n * Selects the dashboards shown for an entity: a comma-separated list of\n * case-insensitive title substrings, matching any dashboard whose title\n * contains at least one of the values.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR =\n  'grafana/dashboard-selector';\n\n/**\n * A comma-separated list of dashboard tags used to select the dashboards shown\n * for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_TAG_SELECTOR = 'grafana/tag-selector';\n\n/**\n * A comma-separated list of `key=value` label matchers used to select the\n * alerts shown for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR =\n  'grafana/alert-label-selector';\n\nconst read = (entity: Entity, key: string): string | undefined => {\n  const value = entity.metadata.annotations?.[key];\n  return value ? value : undefined;\n};\n\n/**\n * Returns the configured Grafana instance name for an entity, if any.\n *\n * @public\n */\nexport const getGrafanaInstanceName = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_INSTANCE);\n\n/**\n * Returns the dashboard selector expression for an entity, if any.\n *\n * @public\n */\nexport const getDashboardSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);\n\n/**\n * Returns the dashboard tag selector for an entity, if any.\n *\n * @public\n */\nexport const getTagSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);\n\n/**\n * Returns the alert label selector for an entity, if any.\n *\n * @public\n */\nexport const getAlertLabelSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * dashboards, and therefore has dashboard content to display.\n *\n * @public\n */\nexport const isDashboardsAvailable = (entity: Entity): boolean =>\n  Boolean(\n    getGrafanaInstanceName(entity) ||\n      getDashboardSelector(entity) ||\n      getTagSelector(entity),\n  );\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * alerts, and therefore has alert content to display.\n *\n * @public\n */\nexport const isAlertsAvailable = (entity: Entity): boolean =>\n  Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));\n\n/**\n * Returns `true` when an entity carries any Grafana annotation, and therefore\n * has Grafana content to display.\n *\n * @public\n */\nexport const isGrafanaAvailable = (entity: Entity): boolean =>\n  isDashboardsAvailable(entity) || isAlertsAvailable(entity);\n"],"names":[],"mappings":";;AAwBO,MAAM,2BAAA,GAA8B;AASpC,MAAM,qCAAA,GACX;AAQK,MAAM,+BAAA,GAAkC;AAQxC,MAAM,uCAAA,GACX;AAEF,MAAM,IAAA,GAAO,CAAC,MAAA,EAAgB,GAAA,KAAoC;AAChE,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,QAAA,CAAS,WAAA,GAAc,GAAG,CAAA;AAC/C,EAAA,OAAO,QAAQ,KAAA,GAAQ,MAAA;AACzB,CAAA;AAOO,MAAM,sBAAA,GAAyB,CAAC,MAAA,KACrC,IAAA,CAAK,QAAQ,2BAA2B;AAOnC,MAAM,oBAAA,GAAuB,CAAC,MAAA,KACnC,IAAA,CAAK,QAAQ,qCAAqC;AAO7C,MAAM,cAAA,GAAiB,CAAC,MAAA,KAC7B,IAAA,CAAK,QAAQ,+BAA+B;AAOvC,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,IAAA,CAAK,QAAQ,uCAAuC;AAQ/C,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,OAAA;AAAA,EACE,uBAAuB,MAAM,CAAA,IAC3B,qBAAqB,MAAM,CAAA,IAC3B,eAAe,MAAM;AACzB;AAQK,MAAM,iBAAA,GAAoB,CAAC,MAAA,KAChC,OAAA,CAAQ,uBAAuB,MAAM,CAAA,IAAK,qBAAA,CAAsB,MAAM,CAAC;AAQlE,MAAM,qBAAqB,CAAC,MAAA,KACjC,sBAAsB,MAAM,CAAA,IAAK,kBAAkB,MAAM;;;;;;;;;;;;"}
+{"version":3,"file":"annotations.cjs.js","sources":["../src/annotations.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity } from '@backstage/catalog-model';\n\n/**\n * Selects which configured Grafana instance an entity belongs to. The value\n * must match an instance `name` in the backend configuration.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_INSTANCE = 'grafana/instance';\n\n/**\n * Selects the dashboards shown for an entity: a comma-separated list of\n * case-insensitive title substrings, matching any dashboard whose title\n * contains at least one of the values.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR =\n  'grafana/dashboard-selector';\n\n/**\n * Selects a single dashboard by its Grafana uid (exact, case-sensitive match).\n * Written by catalog discovery onto the `Resource` it emits per dashboard, so\n * that the entity shows exactly its own dashboard; it can also be set by hand.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_DASHBOARD_UID = 'grafana/dashboard-uid';\n\n/**\n * A comma-separated list of dashboard tags used to select the dashboards shown\n * for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_TAG_SELECTOR = 'grafana/tag-selector';\n\n/**\n * A comma-separated list of `key=value` label matchers used to select the\n * alerts shown for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR =\n  'grafana/alert-label-selector';\n\nconst read = (entity: Entity, key: string): string | undefined => {\n  const value = entity.metadata.annotations?.[key];\n  return value ? value : undefined;\n};\n\n/**\n * Returns the configured Grafana instance name for an entity, if any.\n *\n * @public\n */\nexport const getGrafanaInstanceName = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_INSTANCE);\n\n/**\n * Returns the dashboard selector expression for an entity, if any.\n *\n * @public\n */\nexport const getDashboardSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);\n\n/**\n * Returns the dashboard uid selector for an entity, if any.\n *\n * @public\n */\nexport const getDashboardUid = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_DASHBOARD_UID);\n\n/**\n * Returns the dashboard tag selector for an entity, if any.\n *\n * @public\n */\nexport const getTagSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);\n\n/**\n * Returns the alert label selector for an entity, if any.\n *\n * @public\n */\nexport const getAlertLabelSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * dashboards, and therefore has dashboard content to display.\n *\n * @public\n */\nexport const isDashboardsAvailable = (entity: Entity): boolean =>\n  Boolean(\n    getGrafanaInstanceName(entity) ||\n      getDashboardSelector(entity) ||\n      getDashboardUid(entity) ||\n      getTagSelector(entity),\n  );\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * alerts, and therefore has alert content to display.\n *\n * @public\n */\nexport const isAlertsAvailable = (entity: Entity): boolean =>\n  Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));\n\n/**\n * Returns `true` when an entity carries any Grafana annotation, and therefore\n * has Grafana content to display.\n *\n * @public\n */\nexport const isGrafanaAvailable = (entity: Entity): boolean =>\n  isDashboardsAvailable(entity) || isAlertsAvailable(entity);\n"],"names":[],"mappings":";;AAwBO,MAAM,2BAAA,GAA8B;AASpC,MAAM,qCAAA,GACX;AASK,MAAM,gCAAA,GAAmC;AAQzC,MAAM,+BAAA,GAAkC;AAQxC,MAAM,uCAAA,GACX;AAEF,MAAM,IAAA,GAAO,CAAC,MAAA,EAAgB,GAAA,KAAoC;AAChE,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,QAAA,CAAS,WAAA,GAAc,GAAG,CAAA;AAC/C,EAAA,OAAO,QAAQ,KAAA,GAAQ,MAAA;AACzB,CAAA;AAOO,MAAM,sBAAA,GAAyB,CAAC,MAAA,KACrC,IAAA,CAAK,QAAQ,2BAA2B;AAOnC,MAAM,oBAAA,GAAuB,CAAC,MAAA,KACnC,IAAA,CAAK,QAAQ,qCAAqC;AAO7C,MAAM,eAAA,GAAkB,CAAC,MAAA,KAC9B,IAAA,CAAK,QAAQ,gCAAgC;AAOxC,MAAM,cAAA,GAAiB,CAAC,MAAA,KAC7B,IAAA,CAAK,QAAQ,+BAA+B;AAOvC,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,IAAA,CAAK,QAAQ,uCAAuC;AAQ/C,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,OAAA;AAAA,EACE,sBAAA,CAAuB,MAAM,CAAA,IAC3B,oBAAA,CAAqB,MAAM,KAC3B,eAAA,CAAgB,MAAM,CAAA,IACtB,cAAA,CAAe,MAAM;AACzB;AAQK,MAAM,iBAAA,GAAoB,CAAC,MAAA,KAChC,OAAA,CAAQ,uBAAuB,MAAM,CAAA,IAAK,qBAAA,CAAsB,MAAM,CAAC;AAQlE,MAAM,qBAAqB,CAAC,MAAA,KACjC,sBAAsB,MAAM,CAAA,IAAK,kBAAkB,MAAM;;;;;;;;;;;;;;"}

package/dist/annotations.esm.js

@@ -1,5 +1,6 @@
 const GRAFANA_ANNOTATION_INSTANCE = "grafana/instance";
 const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = "grafana/dashboard-selector";
+const GRAFANA_ANNOTATION_DASHBOARD_UID = "grafana/dashboard-uid";
 const GRAFANA_ANNOTATION_TAG_SELECTOR = "grafana/tag-selector";
 const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = "grafana/alert-label-selector";
 const read = (entity, key) => {
@@ -8,13 +9,14 @@ const read = (entity, key) => {
 };
 const getGrafanaInstanceName = (entity) => read(entity, GRAFANA_ANNOTATION_INSTANCE);
 const getDashboardSelector = (entity) => read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);
+const getDashboardUid = (entity) => read(entity, GRAFANA_ANNOTATION_DASHBOARD_UID);
 const getTagSelector = (entity) => read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);
 const getAlertLabelSelector = (entity) => read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);
 const isDashboardsAvailable = (entity) => Boolean(
-  getGrafanaInstanceName(entity) || getDashboardSelector(entity) || getTagSelector(entity)
+  getGrafanaInstanceName(entity) || getDashboardSelector(entity) || getDashboardUid(entity) || getTagSelector(entity)
 );
 const isAlertsAvailable = (entity) => Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));
 const isGrafanaAvailable = (entity) => isDashboardsAvailable(entity) || isAlertsAvailable(entity);
 
-export { GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR, GRAFANA_ANNOTATION_INSTANCE, GRAFANA_ANNOTATION_TAG_SELECTOR, getAlertLabelSelector, getDashboardSelector, getGrafanaInstanceName, getTagSelector, isAlertsAvailable, isDashboardsAvailable, isGrafanaAvailable };
+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 };
 //# sourceMappingURL=annotations.esm.js.map

package/dist/annotations.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.esm.js","sources":["../src/annotations.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity } from '@backstage/catalog-model';\n\n/**\n * Selects which configured Grafana instance an entity belongs to. The value\n * must match an instance `name` in the backend configuration.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_INSTANCE = 'grafana/instance';\n\n/**\n * Selects the dashboards shown for an entity: a comma-separated list of\n * case-insensitive title substrings, matching any dashboard whose title\n * contains at least one of the values.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR =\n  'grafana/dashboard-selector';\n\n/**\n * A comma-separated list of dashboard tags used to select the dashboards shown\n * for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_TAG_SELECTOR = 'grafana/tag-selector';\n\n/**\n * A comma-separated list of `key=value` label matchers used to select the\n * alerts shown for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR =\n  'grafana/alert-label-selector';\n\nconst read = (entity: Entity, key: string): string | undefined => {\n  const value = entity.metadata.annotations?.[key];\n  return value ? value : undefined;\n};\n\n/**\n * Returns the configured Grafana instance name for an entity, if any.\n *\n * @public\n */\nexport const getGrafanaInstanceName = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_INSTANCE);\n\n/**\n * Returns the dashboard selector expression for an entity, if any.\n *\n * @public\n */\nexport const getDashboardSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);\n\n/**\n * Returns the dashboard tag selector for an entity, if any.\n *\n * @public\n */\nexport const getTagSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);\n\n/**\n * Returns the alert label selector for an entity, if any.\n *\n * @public\n */\nexport const getAlertLabelSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * dashboards, and therefore has dashboard content to display.\n *\n * @public\n */\nexport const isDashboardsAvailable = (entity: Entity): boolean =>\n  Boolean(\n    getGrafanaInstanceName(entity) ||\n      getDashboardSelector(entity) ||\n      getTagSelector(entity),\n  );\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * alerts, and therefore has alert content to display.\n *\n * @public\n */\nexport const isAlertsAvailable = (entity: Entity): boolean =>\n  Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));\n\n/**\n * Returns `true` when an entity carries any Grafana annotation, and therefore\n * has Grafana content to display.\n *\n * @public\n */\nexport const isGrafanaAvailable = (entity: Entity): boolean =>\n  isDashboardsAvailable(entity) || isAlertsAvailable(entity);\n"],"names":[],"mappings":"AAwBO,MAAM,2BAAA,GAA8B;AASpC,MAAM,qCAAA,GACX;AAQK,MAAM,+BAAA,GAAkC;AAQxC,MAAM,uCAAA,GACX;AAEF,MAAM,IAAA,GAAO,CAAC,MAAA,EAAgB,GAAA,KAAoC;AAChE,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,QAAA,CAAS,WAAA,GAAc,GAAG,CAAA;AAC/C,EAAA,OAAO,QAAQ,KAAA,GAAQ,MAAA;AACzB,CAAA;AAOO,MAAM,sBAAA,GAAyB,CAAC,MAAA,KACrC,IAAA,CAAK,QAAQ,2BAA2B;AAOnC,MAAM,oBAAA,GAAuB,CAAC,MAAA,KACnC,IAAA,CAAK,QAAQ,qCAAqC;AAO7C,MAAM,cAAA,GAAiB,CAAC,MAAA,KAC7B,IAAA,CAAK,QAAQ,+BAA+B;AAOvC,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,IAAA,CAAK,QAAQ,uCAAuC;AAQ/C,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,OAAA;AAAA,EACE,uBAAuB,MAAM,CAAA,IAC3B,qBAAqB,MAAM,CAAA,IAC3B,eAAe,MAAM;AACzB;AAQK,MAAM,iBAAA,GAAoB,CAAC,MAAA,KAChC,OAAA,CAAQ,uBAAuB,MAAM,CAAA,IAAK,qBAAA,CAAsB,MAAM,CAAC;AAQlE,MAAM,qBAAqB,CAAC,MAAA,KACjC,sBAAsB,MAAM,CAAA,IAAK,kBAAkB,MAAM;;"}
+{"version":3,"file":"annotations.esm.js","sources":["../src/annotations.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity } from '@backstage/catalog-model';\n\n/**\n * Selects which configured Grafana instance an entity belongs to. The value\n * must match an instance `name` in the backend configuration.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_INSTANCE = 'grafana/instance';\n\n/**\n * Selects the dashboards shown for an entity: a comma-separated list of\n * case-insensitive title substrings, matching any dashboard whose title\n * contains at least one of the values.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR =\n  'grafana/dashboard-selector';\n\n/**\n * Selects a single dashboard by its Grafana uid (exact, case-sensitive match).\n * Written by catalog discovery onto the `Resource` it emits per dashboard, so\n * that the entity shows exactly its own dashboard; it can also be set by hand.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_DASHBOARD_UID = 'grafana/dashboard-uid';\n\n/**\n * A comma-separated list of dashboard tags used to select the dashboards shown\n * for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_TAG_SELECTOR = 'grafana/tag-selector';\n\n/**\n * A comma-separated list of `key=value` label matchers used to select the\n * alerts shown for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR =\n  'grafana/alert-label-selector';\n\nconst read = (entity: Entity, key: string): string | undefined => {\n  const value = entity.metadata.annotations?.[key];\n  return value ? value : undefined;\n};\n\n/**\n * Returns the configured Grafana instance name for an entity, if any.\n *\n * @public\n */\nexport const getGrafanaInstanceName = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_INSTANCE);\n\n/**\n * Returns the dashboard selector expression for an entity, if any.\n *\n * @public\n */\nexport const getDashboardSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);\n\n/**\n * Returns the dashboard uid selector for an entity, if any.\n *\n * @public\n */\nexport const getDashboardUid = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_DASHBOARD_UID);\n\n/**\n * Returns the dashboard tag selector for an entity, if any.\n *\n * @public\n */\nexport const getTagSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);\n\n/**\n * Returns the alert label selector for an entity, if any.\n *\n * @public\n */\nexport const getAlertLabelSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * dashboards, and therefore has dashboard content to display.\n *\n * @public\n */\nexport const isDashboardsAvailable = (entity: Entity): boolean =>\n  Boolean(\n    getGrafanaInstanceName(entity) ||\n      getDashboardSelector(entity) ||\n      getDashboardUid(entity) ||\n      getTagSelector(entity),\n  );\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * alerts, and therefore has alert content to display.\n *\n * @public\n */\nexport const isAlertsAvailable = (entity: Entity): boolean =>\n  Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));\n\n/**\n * Returns `true` when an entity carries any Grafana annotation, and therefore\n * has Grafana content to display.\n *\n * @public\n */\nexport const isGrafanaAvailable = (entity: Entity): boolean =>\n  isDashboardsAvailable(entity) || isAlertsAvailable(entity);\n"],"names":[],"mappings":"AAwBO,MAAM,2BAAA,GAA8B;AASpC,MAAM,qCAAA,GACX;AASK,MAAM,gCAAA,GAAmC;AAQzC,MAAM,+BAAA,GAAkC;AAQxC,MAAM,uCAAA,GACX;AAEF,MAAM,IAAA,GAAO,CAAC,MAAA,EAAgB,GAAA,KAAoC;AAChE,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,QAAA,CAAS,WAAA,GAAc,GAAG,CAAA;AAC/C,EAAA,OAAO,QAAQ,KAAA,GAAQ,MAAA;AACzB,CAAA;AAOO,MAAM,sBAAA,GAAyB,CAAC,MAAA,KACrC,IAAA,CAAK,QAAQ,2BAA2B;AAOnC,MAAM,oBAAA,GAAuB,CAAC,MAAA,KACnC,IAAA,CAAK,QAAQ,qCAAqC;AAO7C,MAAM,eAAA,GAAkB,CAAC,MAAA,KAC9B,IAAA,CAAK,QAAQ,gCAAgC;AAOxC,MAAM,cAAA,GAAiB,CAAC,MAAA,KAC7B,IAAA,CAAK,QAAQ,+BAA+B;AAOvC,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,IAAA,CAAK,QAAQ,uCAAuC;AAQ/C,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,OAAA;AAAA,EACE,sBAAA,CAAuB,MAAM,CAAA,IAC3B,oBAAA,CAAqB,MAAM,KAC3B,eAAA,CAAgB,MAAM,CAAA,IACtB,cAAA,CAAe,MAAM;AACzB;AAQK,MAAM,iBAAA,GAAoB,CAAC,MAAA,KAChC,OAAA,CAAQ,uBAAuB,MAAM,CAAA,IAAK,qBAAA,CAAsB,MAAM,CAAC;AAQlE,MAAM,qBAAqB,CAAC,MAAA,KACjC,sBAAsB,MAAM,CAAA,IAAK,kBAAkB,MAAM;;"}

package/dist/index.cjs.js

@@ -7,10 +7,12 @@ var selectors = require('./selectors.cjs.js');
 
 exports.GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = annotations.GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR;
 exports.GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = annotations.GRAFANA_ANNOTATION_DASHBOARD_SELECTOR;
+exports.GRAFANA_ANNOTATION_DASHBOARD_UID = annotations.GRAFANA_ANNOTATION_DASHBOARD_UID;
 exports.GRAFANA_ANNOTATION_INSTANCE = annotations.GRAFANA_ANNOTATION_INSTANCE;
 exports.GRAFANA_ANNOTATION_TAG_SELECTOR = annotations.GRAFANA_ANNOTATION_TAG_SELECTOR;
 exports.getAlertLabelSelector = annotations.getAlertLabelSelector;
 exports.getDashboardSelector = annotations.getDashboardSelector;
+exports.getDashboardUid = annotations.getDashboardUid;
 exports.getGrafanaInstanceName = annotations.getGrafanaInstanceName;
 exports.getTagSelector = annotations.getTagSelector;
 exports.isAlertsAvailable = annotations.isAlertsAvailable;

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -15,6 +15,14 @@ declare const GRAFANA_ANNOTATION_INSTANCE = "grafana/instance";
  * @public
  */
 declare const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = "grafana/dashboard-selector";
+/**
+ * Selects a single dashboard by its Grafana uid (exact, case-sensitive match).
+ * Written by catalog discovery onto the `Resource` it emits per dashboard, so
+ * that the entity shows exactly its own dashboard; it can also be set by hand.
+ *
+ * @public
+ */
+declare const GRAFANA_ANNOTATION_DASHBOARD_UID = "grafana/dashboard-uid";
 /**
  * A comma-separated list of dashboard tags used to select the dashboards shown
  * for an entity.
@@ -41,6 +49,12 @@ declare const getGrafanaInstanceName: (entity: Entity) => string | undefined;
  * @public
  */
 declare const getDashboardSelector: (entity: Entity) => string | undefined;
+/**
+ * Returns the dashboard uid selector for an entity, if any.
+ *
+ * @public
+ */
+declare const getDashboardUid: (entity: Entity) => string | undefined;
 /**
  * Returns the dashboard tag selector for an entity, if any.
  *
@@ -132,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.
  *
@@ -150,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`.
@@ -175,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_INSTANCE, GRAFANA_ANNOTATION_TAG_SELECTOR, getAlertLabelSelector, getDashboardSelector, getGrafanaInstanceName, getTagSelector, isAlertsAvailable, isDashboardsAvailable, isGrafanaAvailable, parseLabelSelector, parseTagSelector };
-export type { GrafanaAlert, GrafanaAlertState, GrafanaDashboard, GrafanaInstanceInfo, ListAlertsResponse, ListDashboardsResponse, ListInstancesResponse };
+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 { GetPanelDataResponse, GrafanaAlert, GrafanaAlertHealth, GrafanaAlertState, GrafanaDashboard, GrafanaInstanceInfo, GrafanaPanel, GrafanaPanelData, GrafanaPanelKind, GrafanaPanelPoint, GrafanaPanelSeries, ListAlertsResponse, ListDashboardsResponse, ListInstancesResponse, ListPanelsResponse };

package/dist/index.esm.js

@@ -1,3 +1,3 @@
-export { GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR, GRAFANA_ANNOTATION_INSTANCE, GRAFANA_ANNOTATION_TAG_SELECTOR, getAlertLabelSelector, getDashboardSelector, getGrafanaInstanceName, getTagSelector, isAlertsAvailable, isDashboardsAvailable, isGrafanaAvailable } from './annotations.esm.js';
+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 } from './annotations.esm.js';
 export { parseLabelSelector, parseTagSelector } from './selectors.esm.js';
 //# sourceMappingURL=index.esm.js.map

package/package.json

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