@intentius/chant-lexicon-prometheus 0.106.3 → 0.107.1

package/src/describe-resources.test.ts

@@ -0,0 +1,325 @@
+/**
+ * `describeResources` (#3371) against a fake Mimir ruler and a fake
+ * Alertmanager behind real HTTP servers on localhost (./api/fake-servers.ts),
+ * so the default fetch transport, the tenant header and the token are on
+ * the path; and the shared observation conformance suite over the same
+ * fakes.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { describeObservationConformance } from "@intentius/chant-test-utils";
+import { normalizeObservation } from "@intentius/chant/observation";
+import { describeResources, type PrometheusObserveOptions } from "./describe-resources";
+import { fakeAlertmanager, fakeHttp, fakeRuler, serveFake, type FakeAlertmanagerState, type FakeRulerState } from "./api/fake-servers";
+import { prometheusPlugin } from "./plugin";
+import { RuleGroup, ruleGroupConfig, type RuleGroupEntity } from "./rules";
+import { InhibitRule, Receiver, Route, TimeInterval, AlertmanagerSettings } from "./alertmanager";
+import { SCRAPE_CONFIG_TYPE } from "./prometheus-config";
+import type { RawRuleGroup } from "./api/ruler";
+
+type Entities = PrometheusObserveOptions["entities"];
+
+const api = new RuleGroup({
+  name: "api",
+  interval: "30s",
+  rules: [
+    { record: "job:http_requests:rate5m", expr: "sum by (job) (rate(http_requests_total[5m]))" },
+    { alert: "ApiDown", expr: "up{job=\"api\"} == 0", for: "5m", labels: { severity: "page" } },
+  ],
+});
+const infra = new RuleGroup({ name: "infra", rules: [{ record: "node:up:sum", expr: "sum(up{job=\"node\"})" }] });
+const missing = new RuleGroup({ name: "missing", rules: [{ record: "x:y", expr: "sum(x)" }] });
+
+const team = new Receiver({ name: "team", webhook_configs: [{ url: "http://hooks.example.com/team" }] });
+const pager = new Receiver({ name: "pager", email_configs: [{ to: "oncall@example.com" }] });
+const ghost = new Receiver({ name: "ghost" });
+const weekends = new TimeInterval({ name: "weekends", time_intervals: [{ weekdays: ["saturday", "sunday"] }] });
+const pageRoute = new Route({ receiver: "pager", matchers: ['severity = "page"'], mute_time_intervals: [weekends] });
+const root = new Route({ receiver: team, group_by: ["alertname"], routes: [pageRoute] });
+const inhibit = new InhibitRule({ source_matchers: ['severity="page"'], target_matchers: ['severity="ticket"'], equal: ["alertname"] });
+const settings = new AlertmanagerSettings({ global: { smtp_from: "am@example.com", smtp_smarthost: "smtp.example.com:587" } });
+
+function entities(pairs: Record<string, { entityType: string; props: unknown }>): Entities {
+  return new Map(Object.entries(pairs).map(([n, e]) => [n, { entityType: e.entityType, props: e.props as Record<string, unknown> }]));
+}
+
+const ALL = entities({
+  api,
+  infra,
+  missing,
+  team,
+  pager,
+  ghost,
+  weekends,
+  pageRoute,
+  root,
+  inhibit,
+  settings,
+  scrape: { entityType: SCRAPE_CONFIG_TYPE, props: { job_name: "node" } },
+});
+
+const raw = (g: RuleGroupEntity) => ruleGroupConfig(g) as unknown as RawRuleGroup;
+
+function rulerState(overrides: Partial<FakeRulerState> = {}): FakeRulerState {
+  return {
+    kind: "mimir",
+    tenant: "shop",
+    namespaces: {
+      shop: [raw(api), { name: "checkout", rules: [] }],
+      platform: [raw(infra)],
+      // Not declared by the project: never read.
+      other: [{ name: "foreign", rules: [{ record: "a:b", expr: "sum(a)" }] }],
+    },
+    evaluated: [
+      {
+        name: "api",
+        file: "shop",
+        interval: 30,
+        rules: [
+          { type: "recording", name: "job:http_requests:rate5m", query: "sum by (job) (rate(http_requests_total[5m]))", health: "err", lastError: "many-to-many matching not allowed" },
+          { type: "alerting", name: "ApiDown", query: 'up{job="api"} == 0', duration: 300, health: "ok", state: "firing" },
+        ],
+      },
+      { name: "infra", file: "platform", interval: 60, rules: [{ type: "recording", name: "node:up:sum", query: 'sum(up{job="node"})', health: "ok" }] },
+    ],
+    ...overrides,
+  };
+}
+
+const original = readFileSync(join(import.meta.dirname, "api", "testdata", "am-status-original.yml"), "utf8");
+const amState = (overrides: Partial<FakeAlertmanagerState> = {}): FakeAlertmanagerState => ({ kind: "alertmanager", original, version: "0.34.1", ...overrides });
+
+const ENV = { MIMIR_TOKEN: "t0k" };
+let rulerUrl = "";
+let amUrl = "";
+let closeRuler: () => Promise<void>;
+let closeAm: () => Promise<void>;
+const rulerCalls: string[] = [];
+let ruler = rulerState();
+
+beforeAll(async () => {
+  // The handler reads `ruler` on every request, so a test can swap the state.
+  const r = await serveFake((req) => {
+    if (req.headers.authorization !== "Bearer t0k") return { status: 401, text: "bad token" };
+    return fakeRuler(ruler, rulerCalls)(req);
+  });
+  const a = await serveFake(fakeAlertmanager(amState()));
+  rulerUrl = r.url;
+  amUrl = a.url;
+  closeRuler = r.close;
+  closeAm = a.close;
+});
+afterAll(async () => {
+  await closeRuler?.();
+  await closeAm?.();
+});
+
+function config(over: { tenant?: string; withAlertmanager?: boolean } = {}) {
+  return {
+    prometheus: {
+      profiles: {
+        prod: {
+          ruler: {
+            kind: "mimir" as const,
+            url: rulerUrl,
+            tenant: over.tenant ?? "shop",
+            namespace: "shop",
+            groupNamespaces: { infra: "platform" },
+            token: { env: "MIMIR_TOKEN" },
+          },
+          ...(over.withAlertmanager === false ? {} : { alertmanager: { url: amUrl } }),
+        },
+      },
+    },
+  };
+}
+
+function run(opts: Partial<PrometheusObserveOptions> = {}, over: Parameters<typeof config>[0] = {}) {
+  return describeResources({
+    environment: "prod",
+    entityNames: [...ALL.keys()],
+    entities: ALL,
+    config: config(over),
+    env: ENV,
+    ...opts,
+  });
+}
+
+describe("describeResources: rule groups", () => {
+  it("reads each group in the namespace the profile gives it, over the config API, with the tenant header", async () => {
+    ruler = rulerState();
+    const { resources, queried, unobserved } = normalizeObservation(await run());
+    expect(resources.api).toMatchObject({ type: "Prometheus::Rules::RuleGroup", physicalId: "shop/api", status: "PRESENT", ownership: "unknown" });
+    expect(resources.infra).toMatchObject({ physicalId: "platform/infra", attributes: { namespace: "platform", rules: 1, health: "ok" } });
+    expect(queried.api).toBe("/prometheus/config/v1/rules/shop/api");
+    expect(queried.infra).toBe("/prometheus/config/v1/rules/platform/infra");
+    expect(resources.missing).toBeUndefined();
+    expect(unobserved.missing).toBeUndefined();
+    expect(queried.missing).toBe("/prometheus/config/v1/rules/shop/missing");
+  });
+
+  it("reports each group's health from /api/v1/rules: err with the first rule error, firing and pending counted", async () => {
+    ruler = rulerState();
+    const { resources } = normalizeObservation(await run());
+    expect(resources.api.attributes).toMatchObject({
+      namespace: "shop",
+      rules: 2,
+      interval: "30s",
+      health: "err",
+      lastError: "job:http_requests:rate5m: many-to-many matching not allowed",
+      failing: 1,
+      firing: 1,
+      pending: 0,
+    });
+  });
+
+  it("never reads a namespace the project does not declare", async () => {
+    ruler = rulerState();
+    rulerCalls.length = 0;
+    await run();
+    expect(rulerCalls.length).toBeGreaterThan(0);
+    expect(rulerCalls.filter((c) => c.includes("/other"))).toEqual([]);
+    // No list of every namespace, either.
+    expect(rulerCalls).not.toContain("GET /prometheus/config/v1/rules");
+  });
+
+  it("a group the ruler has not evaluated yet, or a health API that is down, leaves the group present with health unknown", async () => {
+    ruler = rulerState({ evaluated: [] });
+    let { resources } = normalizeObservation(await run());
+    expect(resources.api.attributes).toMatchObject({ health: "unknown" });
+    ruler = rulerState({ evaluatedStatus: 503 });
+    ({ resources } = normalizeObservation(await run()));
+    expect(resources.api).toMatchObject({ status: "PRESENT", attributes: { health: "unknown" } });
+    expect(String(resources.api.attributes?.healthDetail)).toContain("returned 503");
+  });
+
+  it("a wrong tenant is no-credentials and a 500 is read-failed, never absent; the Alertmanager entities are still read", async () => {
+    ruler = rulerState();
+    let { unobserved, resources } = normalizeObservation(await run({}, { tenant: "someone-else" }));
+    expect(unobserved.api.reason).toBe("no-credentials");
+    expect(unobserved.missing.reason).toBe("no-credentials");
+    expect(resources.team).toBeDefined();
+    ruler = rulerState({ status: 500 });
+    ({ unobserved } = normalizeObservation(await run()));
+    expect(unobserved.api.reason).toBe("read-failed");
+  });
+
+  it("a token variable that is not set makes every group no-credentials", async () => {
+    ruler = rulerState();
+    const { unobserved } = normalizeObservation(await run({ env: {} }));
+    expect(unobserved.api).toMatchObject({ reason: "no-credentials" });
+    expect(unobserved.api.detail).toContain("MIMIR_TOKEN");
+  });
+
+  it("on a plain Prometheus, groups are read from /api/v1/rules by name", async () => {
+    const state: FakeRulerState = {
+      kind: "prometheus",
+      namespaces: { "/etc/prometheus/rules.yml": [raw(api)] },
+    };
+    const { resources, queried } = normalizeObservation(
+      await describeResources({
+        environment: "prod",
+        entityNames: ["api", "missing"],
+        entities: ALL,
+        config: { prometheus: { profiles: { prod: { ruler: { kind: "prometheus", url: "http://prometheus.test" } } } } },
+        env: {},
+        http: { ruler: fakeHttp(fakeRuler(state)) },
+      }),
+    );
+    expect(resources.api).toMatchObject({ physicalId: "/etc/prometheus/rules.yml/api", attributes: { file: "/etc/prometheus/rules.yml", rules: 2, health: "ok" } });
+    expect(resources.missing).toBeUndefined();
+    expect(queried.missing).toBe("/api/v1/rules");
+  });
+});
+
+describe("describeResources: Alertmanager", () => {
+  it("finds receivers and time intervals by name, routes by receiver and matchers, inhibit rules by matchers", async () => {
+    ruler = rulerState();
+    const { resources, queried } = normalizeObservation(await run());
+    expect(resources.team).toMatchObject({ type: "Prometheus::Alertmanager::Receiver", physicalId: "receiver/team", attributes: { integrations: ["webhook_configs"] } });
+    expect(resources.pager.attributes).toMatchObject({ integrations: ["email_configs", "pagerduty_configs"] });
+    expect(resources.ghost).toBeUndefined();
+    expect(queried.ghost).toBe("/api/v2/status");
+    expect(resources.weekends).toMatchObject({ physicalId: "time_interval/weekends" });
+    expect(resources.root).toMatchObject({ physicalId: "route/team{}", attributes: { receiver: "team", routes: 1 } });
+    // Declared with spaces around the operator; Alertmanager writes severity="page".
+    expect(resources.pageRoute).toMatchObject({ physicalId: 'route/pager{severity="page"}' });
+    expect(resources.inhibit).toMatchObject({ physicalId: "inhibit_rule/0" });
+  });
+
+  it("carries the cluster status and version on every entity, and a config digest on the settings", async () => {
+    ruler = rulerState();
+    const { resources } = normalizeObservation(await run());
+    expect(resources.team.attributes).toMatchObject({ cluster: "ready", version: "0.34.1", peers: 1 });
+    expect(resources.settings).toMatchObject({ physicalId: "alertmanager" });
+    expect(String(resources.settings.attributes?.configDigest)).toMatch(/^[0-9a-f]{16}$/);
+  });
+
+  it("no Alertmanager in the profile is no-binding for its entities only", async () => {
+    ruler = rulerState();
+    const { unobserved, resources } = normalizeObservation(await run({}, { withAlertmanager: false }));
+    expect(unobserved.team.reason).toBe("no-binding");
+    expect(unobserved.settings.reason).toBe("no-binding");
+    expect(resources.api).toBeDefined();
+  });
+
+  it("a Mimir tenant with no Alertmanager config has every entity absent", async () => {
+    const state = amState({ kind: "mimir", tenant: "shop" });
+    const { resources, unobserved } = normalizeObservation(
+      await describeResources({
+        environment: "prod",
+        entityNames: ["team", "settings"],
+        entities: ALL,
+        config: { prometheus: { profiles: { prod: { alertmanager: { kind: "mimir", url: "http://mimir.test", tenant: "shop" } } } } },
+        env: {},
+        http: { alertmanager: fakeHttp(fakeAlertmanager(state), { "x-scope-orgid": "shop" }) },
+      }),
+    );
+    expect(resources).toEqual({});
+    expect(unobserved).toEqual({});
+  });
+
+  it("prometheus.yml entities are unsupported-kind", async () => {
+    ruler = rulerState();
+    expect(normalizeObservation(await run()).unobserved.scrape.reason).toBe("unsupported-kind");
+  });
+});
+
+it("owned: true withholds everything present as filtered, since nothing carries a marker", async () => {
+  ruler = rulerState();
+  const { resources, unobserved } = normalizeObservation(await run({ owned: true }));
+  expect(resources).toEqual({});
+  expect(unobserved.api.reason).toBe("filtered");
+  expect(unobserved.team.reason).toBe("filtered");
+});
+
+describeObservationConformance({
+  lexicon: "prometheus",
+  ownershipChannel: prometheusPlugin.ownershipChannel,
+  scenarios: [
+    {
+      name: "a Mimir ruler and an Alertmanager",
+      declared: [...ALL.keys()],
+      run: () => {
+        ruler = rulerState();
+        return run();
+      },
+      expectPresent: ["api", "infra", "team", "pager", "weekends", "pageRoute", "root", "inhibit", "settings"],
+      expectAbsent: ["missing", "ghost"],
+      expectUnobserved: ["scrape"],
+    },
+    {
+      name: "owned: true withholds what carries no marker",
+      declared: [...ALL.keys()],
+      owned: true,
+      run: () => {
+        ruler = rulerState();
+        return run({ owned: true });
+      },
+      expectAbsent: ["missing", "ghost"],
+      expectUnobserved: ["api", "infra", "team", "settings", "scrape"],
+    },
+  ],
+});

package/src/describe-resources.ts

@@ -0,0 +1,328 @@
+/**
+ * `describeResources()` for prometheus (#3371): is each declared rule group
+ * loaded on the environment's ruler and is it healthy, and is each declared
+ * Alertmanager entity in the config the environment's Alertmanager runs.
+ *
+ * Runs on core's observer harness. `bind()` resolves the ruler and the
+ * Alertmanager (./api/bind.ts), each on its own, so a project with only rule
+ * groups is not held up by having no Alertmanager. Verdicts:
+ *
+ * | Entity | Read | Absent when |
+ * |---|---|---|
+ * | `RuleGroup` on Mimir, Cortex, Loki | the config API's `/{namespace}/{group}`, in the namespace the profile gives the group | 404 |
+ * | `RuleGroup` on a plain Prometheus | `/api/v1/rules`, by name (and rule file, when the profile names one) | not listed |
+ * | `Receiver`, `TimeInterval` | the loaded Alertmanager config, by name | no entry of that name |
+ * | `Route` | the loaded routing tree, by receiver and matchers | no route with both |
+ * | `InhibitRule` | the loaded inhibit rules, by matchers and `equal` | no equal rule |
+ * | `AlertmanagerSettings` | the loaded config | no config (Mimir: the tenant has none) |
+ * | `ScrapeConfig`, `PrometheusConfig` | none: `prometheus.yml` is a file on disk | `unsupported-kind` |
+ *
+ * A group's health is from `/api/v1/rules` (./api/evaluated.ts): `health`
+ * (`ok`, `err`, `unknown`), the first rule error, and how many alerts are
+ * firing or pending. A failed health read leaves the group present with
+ * `health: "unknown"` and the reason; presence is the config API's answer.
+ * The Alertmanager's cluster status and version ride on its entities.
+ *
+ * Ownership: a rule group and an Alertmanager config carry no marker
+ * (./serializer.ts), so every verdict is `unknown`, and an `owned: true`
+ * read withholds them as `filtered`. What bounds chant on a ruler is the
+ * namespace: groups are only read in the namespaces the profile declares
+ * (./config.ts).
+ */
+
+import { createHash } from "node:crypto";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import {
+  observeEntities,
+  type DeclaredEntity,
+  type DescribeResourcesResult,
+  type EntityObservation,
+  type ObserverAdapter,
+} from "@intentius/chant/observation";
+import { bindEndpoints, classifyPromFailure, type BindOptions, type BoundEndpoints } from "./api/bind";
+import { PromApiError } from "./api/client";
+import { groupHealth } from "./api/evaluated";
+import type { AlertmanagerApi } from "./api/alertmanager";
+import type { RulerApi } from "./api/ruler";
+import { isUnresolvedTarget, namespaceOfGroup, type UnresolvedTarget } from "./config";
+import { INHIBIT_RULE_TYPE, RECEIVER_TYPE, ROUTE_TYPE, SETTINGS_TYPE, TIME_INTERVAL_TYPE } from "./alertmanager";
+import { RULE_GROUP_TYPE } from "./rules";
+import { PROMETHEUS_CONFIG_TYPE, SCRAPE_CONFIG_TYPE } from "./prometheus-config";
+import { loadPrometheusYaml, parseAlertmanagerDocument } from "./import/parser";
+import { stripAlertmanagerDefaults } from "./import/alertmanager-live";
+import type { AlertmanagerConfig, RouteConfig } from "./model";
+
+export interface PrometheusObserveOptions extends Omit<BindOptions, "environment"> {
+  environment: string;
+  buildOutput?: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  owned?: boolean;
+}
+
+type Json = Record<string, unknown>;
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** What `unsupported-kind` says about `prometheus.yml` entities. */
+export const PROMETHEUS_CONFIG_NOT_OBSERVED =
+  "prometheus.yml is a file Prometheus reads from disk, not something its API serves for comparison; observe it through the lexicon that deploys it";
+
+/** A failed read as the harness's per-entity verdict; anything else is rethrown for the harness to record. */
+function unobservedFrom(err: unknown): EntityObservation {
+  if (err instanceof PromApiError) return { unobserved: classifyPromFailure(err) };
+  throw err;
+}
+
+function unbound(u: UnresolvedTarget): EntityObservation {
+  return { unobserved: { reason: u.reason, detail: u.detail } };
+}
+
+const FILTERED_DETAIL = "carries no ownership marker, so an owned-only read cannot show it is chant's";
+
+// ── rule groups ─────────────────────────────────────────────────────
+
+async function healthAttributes(ruler: RulerApi, file: string | undefined, name: string): Promise<Json> {
+  try {
+    const groups = await ruler.evaluated();
+    const g = groups.find((x) => x.name === name && (file === undefined || x.file === file));
+    if (!g) return { health: "unknown", healthDetail: `the ruler does not report "${name}" in ${ruler.evaluatedPath} yet` };
+    const h = groupHealth(g);
+    return {
+      health: h.health,
+      ...(h.lastError ? { lastError: h.lastError } : {}),
+      failing: h.failing,
+      firing: h.firing,
+      pending: h.pending,
+    };
+  } catch (err) {
+    return { health: "unknown", healthDetail: classifyPromFailure(err).detail };
+  }
+}
+
+async function observeRuleGroup(ruler: RulerApi, entity: DeclaredEntity, owned: boolean | undefined): Promise<EntityObservation> {
+  const name = typeof entity.props.name === "string" ? entity.props.name : entity.name;
+  if (ruler.target.kind === "prometheus") {
+    const file = namespaceOfGroup(ruler.target, name);
+    let groups;
+    try {
+      groups = await ruler.evaluated();
+    } catch (err) {
+      return unobservedFrom(err);
+    }
+    const queried = ruler.evaluatedPath;
+    const g = groups.find((x) => x.name === name && (file === undefined || x.file === file));
+    if (!g) return { absent: true, queried };
+    if (owned) return { unobserved: { reason: "filtered", detail: `rule group "${name}" is loaded but ${FILTERED_DETAIL}` }, queried };
+    const h = groupHealth(g);
+    return {
+      present: {
+        type: RULE_GROUP_TYPE,
+        physicalId: `${g.file}/${name}`,
+        status: "PRESENT",
+        ownership: "unknown",
+        attributes: {
+          file: g.file,
+          rules: g.rules.length,
+          health: h.health,
+          ...(h.lastError ? { lastError: h.lastError } : {}),
+          failing: h.failing,
+          firing: h.firing,
+          pending: h.pending,
+        },
+      },
+      queried,
+    };
+  }
+
+  const namespace = namespaceOfGroup(ruler.target, name);
+  if (namespace === undefined) {
+    return { unobserved: { reason: "no-binding", detail: `${ruler.target.source} names no namespace for rule group "${name}"` } };
+  }
+  const queried = ruler.groupPath(namespace, name);
+  let raw;
+  try {
+    raw = await ruler.readGroup(namespace, name);
+  } catch (err) {
+    return unobservedFrom(err);
+  }
+  if (!raw) return { absent: true, queried };
+  if (owned) return { unobserved: { reason: "filtered", detail: `rule group "${name}" is in namespace "${namespace}" but ${FILTERED_DETAIL}` }, queried };
+  const meta: ResourceMetadata = {
+    type: RULE_GROUP_TYPE,
+    physicalId: `${namespace}/${name}`,
+    status: "PRESENT",
+    ownership: "unknown",
+    attributes: {
+      namespace,
+      rules: Array.isArray(raw.rules) ? raw.rules.length : 0,
+      ...(typeof raw.interval === "string" ? { interval: raw.interval } : {}),
+      ...(await healthAttributes(ruler, namespace, name)),
+    },
+  };
+  return { present: meta, queried };
+}
+
+// ── Alertmanager ────────────────────────────────────────────────────
+
+interface LoadedAlertmanager {
+  config: AlertmanagerConfig;
+  address: string;
+  digest: string;
+  health: Json;
+}
+
+async function loadAlertmanager(am: AlertmanagerApi): Promise<LoadedAlertmanager | undefined> {
+  return am.client.once("observe:config", async () => {
+    const live = await am.readConfig();
+    if (!live) return undefined;
+    const loaded = loadPrometheusYaml(live.text);
+    if (!isObject(loaded)) throw new PromApiError(502, "GET", live.address, "the Alertmanager config is not a YAML mapping");
+    const doc = live.remarshalled ? stripAlertmanagerDefaults(loaded) : loaded;
+    const health = (await am.health()) ?? {};
+    return {
+      config: parseAlertmanagerDocument(doc).config,
+      address: live.address,
+      digest: createHash("sha256").update(live.text).digest("hex").slice(0, 16),
+      health: { ...health },
+    };
+  });
+}
+
+/** `name="value"`, whatever spacing and quoting it was written with. */
+function normalMatcher(m: string): string {
+  const match = /^\s*([^=!~\s]+)\s*(=~|!~|!=|=)\s*(.*?)\s*$/.exec(m);
+  if (!match) return m.trim();
+  let value = match[3];
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    try {
+      value = JSON.parse(value) as string;
+    } catch {
+      value = value.slice(1, -1);
+    }
+  }
+  return `${match[1]}${match[2]}${JSON.stringify(value)}`;
+}
+
+function matcherKey(list: unknown): string {
+  return (Array.isArray(list) ? list.map((m) => normalMatcher(String(m))) : []).sort().join(",");
+}
+
+function nameOf(ref: unknown): string | undefined {
+  if (typeof ref === "string") return ref;
+  if (isObject(ref) && isObject(ref.props) && typeof ref.props.name === "string") return ref.props.name;
+  return undefined;
+}
+
+function routeKey(receiver: unknown, matchers: unknown): string {
+  return `${nameOf(receiver) ?? ""}{${matcherKey(matchers)}}`;
+}
+
+function routesOf(root: RouteConfig | undefined): RouteConfig[] {
+  if (!root) return [];
+  const out: RouteConfig[] = [root];
+  for (const child of root.routes ?? []) out.push(...routesOf(child));
+  return out;
+}
+
+function inhibitKey(r: unknown): string {
+  const rule = isObject(r) ? r : {};
+  const equal = Array.isArray(rule.equal) ? [...rule.equal].map(String).sort().join(",") : "";
+  return `${matcherKey(rule.source_matchers)}=>${matcherKey(rule.target_matchers)}/${equal}`;
+}
+
+async function observeAlertmanagerEntity(am: AlertmanagerApi, entity: DeclaredEntity, owned: boolean | undefined): Promise<EntityObservation> {
+  let loaded;
+  try {
+    loaded = await loadAlertmanager(am);
+  } catch (err) {
+    return unobservedFrom(err);
+  }
+  const queried = am.target.kind === "alertmanager" ? am.statusPath : "/api/v1/alerts";
+  if (!loaded) return { absent: true, queried };
+  const { config, health } = loaded;
+  const props = entity.props;
+
+  let physicalId: string | undefined;
+  let attributes: Json = {};
+  switch (entity.type) {
+    case RECEIVER_TYPE: {
+      const r = (config.receivers ?? []).find((x) => x.name === props.name);
+      if (r) {
+        physicalId = `receiver/${r.name}`;
+        attributes = { integrations: Object.keys(r).filter((k) => k.endsWith("_configs")).sort() };
+      }
+      break;
+    }
+    case TIME_INTERVAL_TYPE: {
+      const t = (config.time_intervals ?? []).find((x) => x.name === props.name);
+      if (t) physicalId = `time_interval/${t.name}`;
+      break;
+    }
+    case ROUTE_TYPE: {
+      const key = routeKey(props.receiver, props.matchers);
+      const r = routesOf(config.route).find((x) => routeKey(x.receiver, x.matchers) === key);
+      if (r) {
+        physicalId = `route/${key}`;
+        attributes = { receiver: r.receiver ?? "", routes: (r.routes ?? []).length };
+      }
+      break;
+    }
+    case INHIBIT_RULE_TYPE: {
+      const key = inhibitKey(props);
+      const i = (config.inhibit_rules ?? []).findIndex((x) => inhibitKey(x) === key);
+      if (i >= 0) physicalId = `inhibit_rule/${i}`;
+      break;
+    }
+    case SETTINGS_TYPE:
+      physicalId = "alertmanager";
+      attributes = { configDigest: loaded.digest, ...(config.templates ? { templates: config.templates.length } : {}) };
+      break;
+    default:
+      return { unobserved: { reason: "unsupported-kind", detail: `no prometheus reader for ${entity.type}` } };
+  }
+  if (physicalId === undefined) return { absent: true, queried };
+  if (owned) return { unobserved: { reason: "filtered", detail: `${entity.name} is in the loaded Alertmanager config but ${FILTERED_DETAIL}` }, queried };
+  return {
+    present: { type: entity.type, physicalId, status: "PRESENT", ownership: "unknown", attributes: { ...attributes, ...health } },
+    queried,
+  };
+}
+
+// ── harness ─────────────────────────────────────────────────────────
+
+const ALERTMANAGER_TYPES = new Set([RECEIVER_TYPE, ROUTE_TYPE, INHIBIT_RULE_TYPE, TIME_INTERVAL_TYPE, SETTINGS_TYPE]);
+
+function adapter(options: PrometheusObserveOptions): ObserverAdapter<BoundEndpoints> {
+  return {
+    bind: () => bindEndpoints({ ...options }),
+    classifyBindFailure: (err) => classifyPromFailure(err),
+    async read(endpoints, entity): Promise<EntityObservation> {
+      if (entity.type === RULE_GROUP_TYPE) {
+        return isUnresolvedTarget(endpoints.ruler) ? unbound(endpoints.ruler) : observeRuleGroup(endpoints.ruler, entity, options.owned);
+      }
+      if (ALERTMANAGER_TYPES.has(entity.type)) {
+        return isUnresolvedTarget(endpoints.alertmanager)
+          ? unbound(endpoints.alertmanager)
+          : observeAlertmanagerEntity(endpoints.alertmanager, entity, options.owned);
+      }
+      if (entity.type === SCRAPE_CONFIG_TYPE || entity.type === PROMETHEUS_CONFIG_TYPE) {
+        return { unobserved: { reason: "unsupported-kind", detail: PROMETHEUS_CONFIG_NOT_OBSERVED } };
+      }
+      return { unobserved: { reason: "unsupported-kind", detail: `no prometheus reader for ${entity.type}` } };
+    },
+  };
+}
+
+/** Observe every declared prometheus entity against the environment's ruler and Alertmanager. */
+export async function describeResources(options: PrometheusObserveOptions): Promise<DescribeResourcesResult> {
+  const declared: DeclaredEntity[] = [];
+  for (const name of options.entityNames) {
+    const entity = options.entities.get(name);
+    if (!entity) continue;
+    declared.push({ name, type: entity.entityType, props: entity.props });
+  }
+  return observeEntities(declared, adapter(options));
+}