@oneuptime/common 11.6.1 → 11.7.0

package/Tests/Utils/Traces/CriticalPath.test.ts

@@ -0,0 +1,178 @@
+import CriticalPathUtil, {
+  CriticalPathResult,
+  ServiceBreakdown,
+  SpanData,
+  SpanSelfTime,
+} from "../../../Utils/Traces/CriticalPath";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * CriticalPathUtil is a zero-dependency interval/graph engine over trace spans.
+ * The math is subtle (overlapping-child interval merge, longest-weighted path
+ * with self-time), and its output drives the "where did the latency go" views,
+ * so these tests pin the numeric behavior with hand-computed fixtures.
+ */
+
+function span(
+  spanId: string,
+  parentSpanId: string | undefined,
+  start: number,
+  end: number,
+  primaryEntityId?: string,
+): SpanData {
+  return {
+    spanId,
+    parentSpanId,
+    startTimeUnixNano: start,
+    endTimeUnixNano: end,
+    durationUnixNano: end - start,
+    primaryEntityId,
+    name: spanId,
+  };
+}
+
+describe("CriticalPathUtil.computeSelfTimes", () => {
+  test("a leaf span's self-time equals its whole duration", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("a", undefined, 0, 100),
+    ]);
+
+    const a: SpanSelfTime = times.get("a")!;
+    expect(a.selfTimeUnixNano).toBe(100);
+    expect(a.childTimeUnixNano).toBe(0);
+    expect(a.selfTimePercent).toBe(100);
+  });
+
+  test("subtracts a single child's covered time", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("root", undefined, 0, 100),
+      span("child", "root", 10, 40),
+    ]);
+
+    expect(times.get("root")!.selfTimeUnixNano).toBe(70);
+    expect(times.get("root")!.childTimeUnixNano).toBe(30);
+    expect(times.get("root")!.selfTimePercent).toBe(70);
+  });
+
+  test("sums two non-overlapping children", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("root", undefined, 0, 100),
+      span("c1", "root", 10, 30),
+      span("c2", "root", 50, 80),
+    ]);
+    // covered = 20 + 30 = 50 -> self = 50
+    expect(times.get("root")!.childTimeUnixNano).toBe(50);
+    expect(times.get("root")!.selfTimeUnixNano).toBe(50);
+  });
+
+  test("merges overlapping children into one interval", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("root", undefined, 0, 100),
+      span("c1", "root", 10, 50),
+      span("c2", "root", 30, 70),
+    ]);
+    // merged interval [10,70] = 60 -> self = 40
+    expect(times.get("root")!.childTimeUnixNano).toBe(60);
+    expect(times.get("root")!.selfTimeUnixNano).toBe(40);
+  });
+
+  test("clamps children that spill past the parent window", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("root", undefined, 0, 100),
+      span("c1", "root", -50, 150),
+    ]);
+    // clamped to [0,100] = 100 -> self = 0
+    expect(times.get("root")!.childTimeUnixNano).toBe(100);
+    expect(times.get("root")!.selfTimeUnixNano).toBe(0);
+  });
+
+  test("self-time is floored at zero and percent is zero for a zero-duration span", () => {
+    const zero: SpanData = span("z", undefined, 5, 5);
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      zero,
+    ]);
+    expect(times.get("z")!.selfTimeUnixNano).toBe(0);
+    expect(times.get("z")!.selfTimePercent).toBe(0);
+  });
+});
+
+describe("CriticalPathUtil.computeCriticalPath", () => {
+  test("returns all-zero result for an empty trace", () => {
+    const result: CriticalPathResult = CriticalPathUtil.computeCriticalPath([]);
+    expect(result).toEqual({
+      criticalPathSpanIds: [],
+      totalTraceDurationUnixNano: 0,
+      criticalPathDurationUnixNano: 0,
+    });
+  });
+
+  test("a single span is its own critical path", () => {
+    const result: CriticalPathResult = CriticalPathUtil.computeCriticalPath([
+      span("only", undefined, 0, 100),
+    ]);
+    expect(result.criticalPathSpanIds).toEqual(["only"]);
+    expect(result.totalTraceDurationUnixNano).toBe(100);
+    expect(result.criticalPathDurationUnixNano).toBe(100);
+  });
+
+  test("follows the heavier of two parallel children", () => {
+    const result: CriticalPathResult = CriticalPathUtil.computeCriticalPath([
+      span("root", undefined, 0, 100),
+      span("fast", "root", 10, 40), // duration 30
+      span("slow", "root", 10, 90), // duration 80
+    ]);
+
+    expect(result.criticalPathSpanIds).toEqual(["root", "slow"]);
+    expect(result.totalTraceDurationUnixNano).toBe(100);
+    // root self-time (100 - merged[10,90]=80 => 20) + slow weight 80 = 100
+    expect(result.criticalPathDurationUnixNano).toBe(100);
+  });
+
+  test("treats a span whose parent is absent from the set as a root", () => {
+    const result: CriticalPathResult = CriticalPathUtil.computeCriticalPath([
+      span("orphan", "missing-parent", 0, 50),
+    ]);
+    expect(result.criticalPathSpanIds).toEqual(["orphan"]);
+    expect(result.criticalPathDurationUnixNano).toBe(50);
+  });
+});
+
+describe("CriticalPathUtil.computeServiceBreakdown", () => {
+  test("aggregates self-time per service and sorts descending", () => {
+    const breakdown: Array<ServiceBreakdown> =
+      CriticalPathUtil.computeServiceBreakdown([
+        span("root", undefined, 0, 100, "A"),
+        span("child", "root", 20, 60, "B"),
+      ]);
+
+    // root self = 100 - 40 = 60 (service A); child self = 40 (service B)
+    expect(breakdown).toHaveLength(2);
+    expect(breakdown[0]!.primaryEntityId).toBe("A");
+    expect(breakdown[0]!.selfTimeUnixNano).toBe(60);
+    expect(breakdown[0]!.percentOfTrace).toBe(60);
+    expect(breakdown[1]!.primaryEntityId).toBe("B");
+    expect(breakdown[1]!.selfTimeUnixNano).toBe(40);
+    expect(breakdown[1]!.percentOfTrace).toBe(40);
+  });
+
+  test("groups spans without a service id under 'unknown'", () => {
+    const breakdown: Array<ServiceBreakdown> =
+      CriticalPathUtil.computeServiceBreakdown([span("a", undefined, 0, 10)]);
+
+    expect(breakdown).toHaveLength(1);
+    expect(breakdown[0]!.primaryEntityId).toBe("unknown");
+    expect(breakdown[0]!.spanCount).toBe(1);
+  });
+
+  test("accumulates span counts and durations per service", () => {
+    const breakdown: Array<ServiceBreakdown> =
+      CriticalPathUtil.computeServiceBreakdown([
+        span("s1", undefined, 0, 100, "A"),
+        span("s2", undefined, 100, 150, "A"),
+      ]);
+
+    expect(breakdown).toHaveLength(1);
+    expect(breakdown[0]!.spanCount).toBe(2);
+    expect(breakdown[0]!.totalDurationUnixNano).toBe(150);
+  });
+});

package/Types/AnalyticsDatabase/AnalyticsTableName.ts

@@ -8,6 +8,7 @@ enum AnalyticsTableName {
   Profile = "ProfileItemV3",
   ProfileSample = "ProfileSampleItemV3",
   AuditLog = "AuditLogV2",
+  KubernetesCostAllocation = "KubernetesCostAllocationV1",
   /*
    * Materialized-view target tables. These hold AggregateFunction
    * states populated by attached MVs on the source `Metric` table.
@@ -33,6 +34,15 @@ enum AnalyticsTableName {
   MetricItemAggMV1mByContainer = "MetricItemAggMV1mByContainer",
   MetricBaselineHourly = "MetricBaselineHourly",
   MutableMetric = "MutableMetricItem",
+  /*
+   * SLO / Error Budget history rollup. ReplacingMergeTree keyed by
+   * (projectId, sloId, metricName, bucketStart) with a `version` column
+   * so at-least-once evaluator writes and trailing re-writes dedupe to
+   * the latest value. Deliberately NOT MetricItemV3: its own monthly
+   * partitions + 400-day TTL keep long-lived SLO rows from pinning the
+   * daily raw-telemetry partitions (ttl_only_drop_parts hazard).
+   */
+  SloHistory = "SloHistory",
 }
 
 export default AnalyticsTableName;

package/Types/BaseDatabase/EqualTo.ts

@@ -15,7 +15,15 @@ export default class EqualTo<T extends CompareType> extends CompareBase<T> {
   public override toJSON(): JSONObject {
     return {
       _type: ObjectType.EqualTo,
-      value: (this as EqualTo<T>).toString(),
+      /*
+       * The RAW value is serialized (like GreaterThan / InBetween), not
+       * toString(): toString() stringifies a Date into a locale- and
+       * timezone-dependent form that loses milliseconds, and coerces a number
+       * into a string. JSON.stringify emits a raw Date as its full ISO
+       * timestamp, which the server binds at full precision — and which is
+       * what lets an equality filter survive a round trip through the URL.
+       */
+      value: (this as EqualTo<T>).value,
     };
   }
 

package/Types/BaseDatabase/EqualToOrNull.ts

@@ -17,7 +17,15 @@ export default class EqualToOrNull<
   public override toJSON(): JSONObject {
     return {
       _type: ObjectType.EqualToOrNull,
-      value: (this as EqualToOrNull<T>).toString(),
+      /*
+       * The RAW value is serialized (like GreaterThan / InBetween), not
+       * toString(): toString() stringifies a Date into a locale- and
+       * timezone-dependent form that loses milliseconds, and coerces a number
+       * into a string. JSON.stringify emits a raw Date as its full ISO
+       * timestamp, which the server binds at full precision — and which is
+       * what lets an equality filter survive a round trip through the URL.
+       */
+      value: (this as EqualToOrNull<T>).value,
     };
   }
 

package/Types/BaseDatabase/NotEqual.ts

@@ -14,7 +14,15 @@ export default class NotEqual<T extends CompareType> extends CompareBase<T> {
   public override toJSON(): JSONObject {
     return {
       _type: ObjectType.NotEqual,
-      value: (this as NotEqual<T>).toString(),
+      /*
+       * The RAW value is serialized (like GreaterThan / InBetween), not
+       * toString(): toString() stringifies a Date into a locale- and
+       * timezone-dependent form that loses milliseconds, and coerces a number
+       * into a string. JSON.stringify emits a raw Date as its full ISO
+       * timestamp, which the server binds at full precision — and which is
+       * what lets an equality filter survive a round trip through the URL.
+       */
+      value: (this as NotEqual<T>).value,
     };
   }
 

package/Types/Dashboard/DashboardComponentType.ts

@@ -12,6 +12,7 @@ enum DashboardComponentType {
   IncidentList = `IncidentList`,
   AlertList = `AlertList`,
   MonitorList = `MonitorList`,
+  Slo = `Slo`,
   KubernetesPodList = `KubernetesPodList`,
   KubernetesNodeList = `KubernetesNodeList`,
   KubernetesNamespaceList = `KubernetesNamespaceList`,

package/Types/Dashboard/DashboardComponents/ComponentArgument.ts

@@ -27,6 +27,7 @@ export enum EntityFilterModelType {
   AlertState = "AlertState",
   MonitorStatus = "MonitorStatus",
   Monitor = "Monitor",
+  ServiceLevelObjective = "ServiceLevelObjective",
   Label = "Label",
   KubernetesCluster = "KubernetesCluster",
   DockerHost = "DockerHost",

package/Types/Dashboard/DashboardComponents/DashboardSloComponent.ts

@@ -0,0 +1,42 @@
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+
+/**
+ * Which of the SLO's three tracked numbers the widget renders.
+ *
+ * These values are persisted inside the dashboard's JSON config, so they
+ * must never be renamed — only added to.
+ */
+export enum SloWidgetMetric {
+  Sli = "Sli",
+  ErrorBudgetRemaining = "ErrorBudgetRemaining",
+  BurnRate = "BurnRate",
+}
+
+/**
+ * Tile renders the single current number (read from the SLO row that the
+ * evaluation worker keeps up to date). Chart renders the SloHistory
+ * series for the same metric over the dashboard's selected time range.
+ */
+export enum SloWidgetDisplayType {
+  Tile = "Tile",
+  Chart = "Chart",
+}
+
+export default interface DashboardSloComponent extends BaseComponent {
+  componentType: DashboardComponentType.Slo;
+  componentId: ObjectID;
+  arguments: {
+    /*
+     * ObjectID of the ServiceLevelObjective, held as a string because the
+     * EntityDropdown argument editor writes the raw `_id` and the whole
+     * component tree round-trips through the dashboard's JSON config.
+     * The renderer wraps it in `new ObjectID(...)` before querying.
+     */
+    serviceLevelObjectiveId?: string | undefined;
+    sloMetric?: SloWidgetMetric | undefined;
+    displayType?: SloWidgetDisplayType | undefined;
+    widgetTitle?: string | undefined;
+  };
+}

package/Types/Dashboard/DashboardTemplates.ts

@@ -27,6 +27,7 @@ export enum DashboardTemplateType {
   Incident = "Incident",
   Alert = "Alert",
   Kubernetes = "Kubernetes",
+  KubernetesCost = "KubernetesCost",
   Host = "Host",
   Proxmox = "Proxmox",
   Ceph = "Ceph",
@@ -110,6 +111,14 @@ export const DashboardTemplates: Array<DashboardTemplate> = [
     icon: IconProp.Kubernetes,
     category: DashboardTemplateCategory.Infrastructure,
   },
+  {
+    type: DashboardTemplateType.KubernetesCost,
+    name: "Kubernetes Cost Dashboard",
+    description:
+      "Node hourly cost trends, CPU/RAM unit costs, persistent volume and load balancer spend from your in-cluster cost engine (OpenCost / Kubecost).",
+    icon: IconProp.Billing,
+    category: DashboardTemplateCategory.Infrastructure,
+  },
   {
     type: DashboardTemplateType.Host,
     name: "Hosts Dashboard",
@@ -1639,6 +1648,209 @@ function createKubernetesDashboardConfig(): DashboardViewConfig {
   };
 }
 
+function createKubernetesCostDashboardConfig(): DashboardViewConfig {
+  /*
+   * Built on the cost metrics the kubernetes-agent chart scrapes from an
+   * in-cluster cost engine (OpenCost / Kubecost cost-model) when
+   * `cost.metrics` is enabled — node_total_hourly_cost,
+   * node_cpu_hourly_cost, node_ram_hourly_cost, pv_hourly_cost,
+   * kubecost_load_balancer_cost. Per-workload allocation (namespace /
+   * controller spend, idle, efficiency) is NOT charted here — those come
+   * from the Allocation API poller and live on the cluster's Costs page.
+   *
+   * Layout notes:
+   *
+   * - Every cost metric here is a per-resource gauge (one series per
+   *   node / volume / load balancer) re-emitted on every scrape, so a
+   *   `Sum` aggregation would multiply by the scrape count over the
+   *   window — the same trap the Kubernetes template documents for
+   *   k8s.pod.phase. All widgets therefore use `Avg`, and the charts fan
+   *   out per resource via groupByAttributeKeys so a stacked area still
+   *   reads as the cluster total per bucket.
+   *
+   * - The engine's metric labels are plain Prometheus labels ("node",
+   *   "persistentvolume", "service_name"), not OTel resource attributes,
+   *   so group keys have no `resource.` prefix.
+   */
+  const components: Array<DashboardBaseComponent> = [
+    // Row 0: Title
+    createTextComponent({
+      text: "Kubernetes Cost Dashboard",
+      top: 0,
+      left: 0,
+      width: 12,
+      height: 1,
+      isBold: true,
+    }),
+
+    // Row 1: Unit-cost stat tiles. Rising cost is "worse" for all four.
+    createValueComponent({
+      title: "Node Cost $/hr (avg per node)",
+      top: 1,
+      left: 0,
+      width: 3,
+      metricConfig: {
+        metricName: "node_total_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+    createValueComponent({
+      title: "CPU Cost $/core-hr (avg)",
+      top: 1,
+      left: 3,
+      width: 3,
+      metricConfig: {
+        metricName: "node_cpu_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+    createValueComponent({
+      title: "RAM Cost $/GiB-hr (avg)",
+      top: 1,
+      left: 6,
+      width: 3,
+      metricConfig: {
+        metricName: "node_ram_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+    createValueComponent({
+      title: "PV Cost $/hr (avg per volume)",
+      top: 1,
+      left: 9,
+      width: 3,
+      metricConfig: {
+        metricName: "pv_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+
+    /*
+     * Row 2-5: Hourly cost per node, stacked — the stack height is the
+     * cluster's total node $/hr per bucket.
+     */
+    createChartComponent({
+      title: "Node Hourly Cost ($/hr, stacked by node)",
+      chartType: DashboardChartType.StackedArea,
+      top: 2,
+      left: 0,
+      width: 12,
+      height: 3,
+      metricConfig: {
+        metricName: "node_total_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Node",
+        legendUnit: "$/hr",
+        groupByAttributeKeys: ["node"],
+      },
+    }),
+
+    // Row 5-8: Unit-cost trends per node — catches spot/instance-type churn.
+    createChartComponent({
+      title: "CPU Cost per Core Hour by Node",
+      chartType: DashboardChartType.Line,
+      top: 5,
+      left: 0,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "node_cpu_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Node",
+        legendUnit: "$/core-hr",
+        groupByAttributeKeys: ["node"],
+      },
+    }),
+    createChartComponent({
+      title: "RAM Cost per GiB Hour by Node",
+      chartType: DashboardChartType.Line,
+      top: 5,
+      left: 6,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "node_ram_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Node",
+        legendUnit: "$/GiB-hr",
+        groupByAttributeKeys: ["node"],
+      },
+    }),
+
+    // Row 8-11: Storage and load balancer spend.
+    createChartComponent({
+      title: "Persistent Volume Hourly Cost (stacked by volume)",
+      chartType: DashboardChartType.StackedArea,
+      top: 8,
+      left: 0,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "pv_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Volume",
+        legendUnit: "$/hr",
+        groupByAttributeKeys: ["persistentvolume"],
+      },
+    }),
+    createChartComponent({
+      title: "Load Balancer Hourly Cost (stacked by service)",
+      chartType: DashboardChartType.StackedArea,
+      top: 8,
+      left: 6,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "kubecost_load_balancer_cost",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Service",
+        legendUnit: "$/hr",
+        groupByAttributeKeys: ["service_name"],
+      },
+    }),
+
+    // Row 11-14: Per-node cost table for quick ranking.
+    createTableComponent({
+      title: "Cost by Node ($/hr)",
+      top: 11,
+      left: 0,
+      width: 12,
+      height: 3,
+      maxRows: 20,
+      metricConfig: {
+        metricName: "node_total_hourly_cost",
+        aggregationType: MetricsAggregationType.Avg,
+        groupByAttributeKeys: ["node"],
+      },
+    }),
+  ];
+
+  /*
+   * Cluster picker so multi-cluster projects can scope every widget from
+   * the toolbar. The deployment collector stamps k8s.cluster.name on the
+   * scraped cost metrics, so the binding key matches the other
+   * Kubernetes dashboards.
+   */
+  const variables: Array<DashboardVariable> = [
+    createTelemetryAttributeVariable({
+      name: "cluster",
+      label: "Cluster",
+      attributeKey: "resource.k8s.cluster.name",
+    }),
+  ];
+
+  return {
+    _type: ObjectType.DashboardViewConfig,
+    components,
+    variables,
+    heightInDashboardUnits: Math.max(DashboardSize.heightInDashboardUnits, 14),
+  };
+}
+
 function createMetricsDashboardConfig(): DashboardViewConfig {
   /*
    * Layout notes:
@@ -2697,6 +2909,8 @@ export function getTemplateConfig(
       return createAlertDashboardConfig();
     case DashboardTemplateType.Kubernetes:
       return createKubernetesDashboardConfig();
+    case DashboardTemplateType.KubernetesCost:
+      return createKubernetesCostDashboardConfig();
     case DashboardTemplateType.Host:
       return createHostDashboardConfig();
     case DashboardTemplateType.Proxmox:

package/Types/Email/EmailTemplateType.ts

@@ -32,6 +32,8 @@ enum EmailTemplateType {
   MonitorProbesStatus = "MonitorProbesStatus.hbs",
   MonitorOwnerStatusChanged = "MonitorOwnerStatusChanged.hbs",
 
+  SloOwnerStatusChanged = "SloOwnerStatusChanged.hbs",
+
   IncidentOwnerAdded = "IncidentOwnerAdded.hbs",
   IncidentOwnerStateChanged = "IncidentOwnerStateChanged.hbs",
   IncidentOwnerNotePosted = "IncidentOwnerNotePosted.hbs",

package/Types/Kubernetes/KubernetesCostIngest.ts

@@ -0,0 +1,79 @@
+/*
+ * Wire contract for POST /kubernetes-cost/ingest — the payload the
+ * Kubernetes agent's cost poller ships after querying an in-cluster cost
+ * engine's Allocation API (OpenCost `/allocation/compute`, Kubecost
+ * `/model/allocation`). One request carries one cluster's allocation rows
+ * for one or more closed time windows.
+ *
+ * The route is mounted under both "/telemetry" and "/" (TELEMETRY_PREFIXES).
+ * The agent posts to the "/telemetry" prefix — see the note in
+ * KubernetesCostAgent/Shipper.ts for why.
+ *
+ * The agent projects are standalone (no dependency on Common), so the
+ * poller carries its own mirror of these interfaces
+ * (KubernetesCostAgent/Types.ts) — keep the two in sync.
+ */
+
+export interface KubernetesCostAllocationIngestRow {
+  /** ISO-8601 start of the allocation window. Required. */
+  windowStart: string;
+  /** ISO-8601 end of the allocation window. Required. */
+  windowEnd: string;
+
+  /*
+   * Workload identity. All optional — idle / unallocated rows carry the
+   * engine's sentinel in `namespace` ("__idle__" / "__unallocated__") and
+   * nothing else.
+   */
+  namespace?: string | undefined;
+  controllerKind?: string | undefined;
+  controllerName?: string | undefined;
+  podName?: string | undefined;
+  containerName?: string | undefined;
+  nodeName?: string | undefined;
+  providerId?: string | undefined;
+  labels?: Record<string, string> | undefined;
+
+  // Usage / request measures.
+  cpuCoreHours?: number | undefined;
+  cpuCoreRequestAverage?: number | undefined;
+  cpuCoreUsageAverage?: number | undefined;
+  gpuHours?: number | undefined;
+  ramByteHours?: number | undefined;
+  ramBytesRequestAverage?: number | undefined;
+  ramBytesUsageAverage?: number | undefined;
+  pvByteHours?: number | undefined;
+
+  // Pre-priced cost components (in `currency` of the payload).
+  cpuCost?: number | undefined;
+  gpuCost?: number | undefined;
+  ramCost?: number | undefined;
+  pvCost?: number | undefined;
+  networkCost?: number | undefined;
+  loadBalancerCost?: number | undefined;
+  sharedCost?: number | undefined;
+  externalCost?: number | undefined;
+  totalCost?: number | undefined;
+
+  // Efficiency ratios (usage / request, 0..1+).
+  cpuEfficiency?: number | undefined;
+  ramEfficiency?: number | undefined;
+  totalEfficiency?: number | undefined;
+}
+
+export interface KubernetesCostIngestPayload {
+  /**
+   * Cluster identifier — must match the k8s.cluster.name the agent stamps
+   * on metrics so cost rows land on the same KubernetesCluster resource.
+   */
+  clusterName: string;
+  /** Currency code of all cost figures (e.g. "USD"). Optional. */
+  currency?: string | undefined;
+  allocations: Array<KubernetesCostAllocationIngestRow>;
+}
+
+/**
+ * Upper bound on `allocations.length` per request. The poller chunks its
+ * output to stay under this; the ingest endpoint rejects anything larger.
+ */
+export const MAX_KUBERNETES_COST_ALLOCATIONS_PER_REQUEST: number = 5000;

package/Types/Monitor/CriteriaFilter.ts

@@ -119,6 +119,14 @@ export interface ServerMonitorOptions {
 
 export interface SnmpMonitorOptions {
   oid?: string | undefined;
+  /*
+   * Optional interface scope for the interface CheckOns (down /
+   * utilization / errors). When set, only interfaces whose name or alias
+   * equals this value (case-insensitive) are evaluated — so "uplink Gi0/1
+   * above 80%" does not fire because an access port got busy. Empty =
+   * every monitored interface, the historical behavior.
+   */
+  interfaceName?: string | undefined;
 }
 
 export enum EvaluateOverTimeType {
@@ -429,6 +437,7 @@ export const CriteriaFilterSchema: ZodSchema = Zod.object({
   }).optional(),
   snmpMonitorOptions: Zod.object({
     oid: Zod.string().optional(),
+    interfaceName: Zod.string().optional(),
   }).optional(),
   filterType: Zod.string().optional(),
   value: Zod.union([Zod.string(), Zod.number()]).optional(),