@oneuptime/common 12.0.1 → 12.0.3

package/Types/Dashboard/DashboardTemplates.ts

@@ -11,6 +11,7 @@ import MetricsAggregationType from "../Metrics/MetricsAggregationType";
 import IncidentMetricType from "../Incident/IncidentMetricType";
 import AlertMetricType from "../Alerts/AlertMetricType";
 import MonitorMetricType from "../Monitor/MonitorMetricType";
+import MonitorType from "../Monitor/MonitorType";
 import MetricDashboardMetricType from "../Metrics/MetricDashboardMetricType";
 import { DashboardValueTrendDirection } from "./DashboardComponents/DashboardValueComponent";
 
@@ -39,6 +40,7 @@ export enum DashboardTemplateType {
   DockerSwarm = "DockerSwarm",
   Metrics = "Metrics",
   Rum = "Rum",
+  Network = "Network",
 }
 
 /*
@@ -165,6 +167,14 @@ export const DashboardTemplates: Array<DashboardTemplate> = [
     icon: IconProp.Cube,
     category: DashboardTemplateCategory.Infrastructure,
   },
+  {
+    type: DashboardTemplateType.Network,
+    name: "Network Dashboard",
+    description:
+      "Your sites on the world map, SNMP interface throughput, utilization and errors, device reachability and round-trip latency, and the monitors watching them.",
+    icon: IconProp.Map,
+    category: DashboardTemplateCategory.Infrastructure,
+  },
 ];
 
 /*
@@ -796,6 +806,71 @@ function createCephPoolListComponent(data: {
   };
 }
 
+function createNetworkMapComponent(data: {
+  title: string;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  maxSites?: number;
+  statusFilter?: string;
+  showLabels?: boolean;
+}): DashboardBaseComponent {
+  return {
+    _type: ObjectType.DashboardComponent,
+    componentType: DashboardComponentType.NetworkMap,
+    componentId: ObjectID.generate(),
+    topInDashboardUnits: data.top,
+    leftInDashboardUnits: data.left,
+    widthInDashboardUnits: data.width,
+    heightInDashboardUnits: data.height,
+    /*
+     * A map needs room in BOTH axes — the world is roughly 2:1, so a short
+     * tile letterboxes it into a strip. Same floor the widget's own default
+     * declares (Common/Utils/Dashboard/Components/DashboardNetworkMapComponent).
+     */
+    minHeightInDashboardUnits: 4,
+    minWidthInDashboardUnits: 4,
+    arguments: {
+      title: data.title,
+      maxSites: data.maxSites ?? 250,
+      viewMode: "map",
+      showLabels: data.showLabels ?? true,
+      statusFilter: data.statusFilter,
+    },
+  };
+}
+
+function createMonitorListComponent(data: {
+  title: string;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  maxRows?: number;
+  monitorTypes?: Array<string>;
+  statusFilter?: string;
+}): DashboardBaseComponent {
+  return {
+    _type: ObjectType.DashboardComponent,
+    componentType: DashboardComponentType.MonitorList,
+    componentId: ObjectID.generate(),
+    topInDashboardUnits: data.top,
+    leftInDashboardUnits: data.left,
+    widthInDashboardUnits: data.width,
+    heightInDashboardUnits: data.height,
+    minHeightInDashboardUnits: 3,
+    minWidthInDashboardUnits: 6,
+    arguments: {
+      title: data.title,
+      maxRows: data.maxRows ?? 25,
+      viewMode: "list",
+      monitorTypes: data.monitorTypes,
+      statusFilter: data.statusFilter,
+    },
+  };
+}
+
 // -- Dashboard configs --
 
 function createMonitorDashboardConfig(): DashboardViewConfig {
@@ -3411,6 +3486,326 @@ function createCephDashboardConfig(): DashboardViewConfig {
   };
 }
 
+function createNetworkDashboardConfig(): DashboardViewConfig {
+  /*
+   * Layout and metric notes:
+   *
+   * - The map reads the Postgres NetworkSite inventory rather than a metric
+   *   series, so its markers are true right now — the same reasoning the
+   *   Kubernetes / Ceph templates use for their inventory widgets.
+   *
+   * - EVERY metric widget here queries an `oneuptime.monitor.snmp.*` series,
+   *   and those are emitted by exactly one code path:
+   *   NetworkDeviceMetricUtil.saveWalkMetrics, off a network device walk.
+   *   That is deliberate and it is the constraint the rest of this template
+   *   is built around.
+   *
+   *   The obvious tiles to reach for — uptime, round-trip time, packet loss,
+   *   jitter — do NOT belong here, however much a network dashboard wants
+   *   them. `oneuptime.monitor.online` and `oneuptime.monitor.response.time`
+   *   are emitted by MonitorMetricUtil for EVERY probeable monitor in the
+   *   project, and packet loss and jitter come from Ping/IP monitors. A tile
+   *   titled "Round-trip Time" on a network dashboard that silently averages
+   *   every website check in the project is worse than no tile: it is a
+   *   number a reader will act on. Device reachability is on this dashboard
+   *   as the Network Device monitor list, which IS correctly scoped.
+   *
+   * - Because every series here comes from the device walk, every series
+   *   carries `deviceName`, and the per-interface ones also carry
+   *   `interfaceName` — so both template variables bind to something real on
+   *   every widget. Those keys are BARE, not `resource.`-prefixed; see
+   *   NetworkDeviceMetricUtil.buildDeviceMetricRow.
+   *
+   * - No widget aggregates with Sum. The interface series are already
+   *   per-second RATES, and the Value tile reduces across time buckets — so
+   *   a summed rate grows with the dashboard's time range rather than
+   *   describing the network. Max answers "how bad did it get", Avg answers
+   *   "what is normal"; both are range-independent.
+   *
+   * - For the same reason the in/out bit-rate charts are NOT
+   *   transformAsRate'd the way the Ceph template's cumulative
+   *   ceph_pool_*_bytes counters are. They are already rates; rate-of-a-rate
+   *   plots noise around zero.
+   */
+  const components: Array<DashboardBaseComponent> = [
+    // Row 0: Title
+    createTextComponent({
+      text: "Network Dashboard",
+      top: 0,
+      left: 0,
+      width: 12,
+      height: 1,
+      isBold: true,
+    }),
+
+    /*
+     * Rows 1-5: where the network IS, next to how it is doing. The map is
+     * the subject and takes two thirds of the width; the column beside it
+     * is the numbers a reader checks without leaving the picture.
+     */
+    createNetworkMapComponent({
+      title: "Sites",
+      top: 1,
+      left: 0,
+      width: 8,
+      height: 5,
+      maxSites: 250,
+    }),
+    /*
+     * SnmpInterfaceOperStatus is emitted as 0/1 per interface, so Avg is the
+     * FRACTION of interfaces currently up — in [0, 1], not a percent.
+     * Labelled "(avg)" for the same reason the Monitor template labels its
+     * uptime tile that way rather than printing a misleading "%".
+     */
+    createValueComponent({
+      title: "Interfaces Up (avg)",
+      top: 1,
+      left: 8,
+      width: 4,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceOperStatus,
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsBetter,
+    }),
+    createValueComponent({
+      title: "Avg Interface Utilization",
+      top: 2,
+      left: 8,
+      width: 4,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceUtilizationPercent,
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+    /*
+     * Max, not Sum: this is "how bad did the worst port get", which is what
+     * an operator acts on. Summing a per-second error rate across every
+     * interface and every time bucket produces a number that doubles when
+     * you widen the time picker.
+     */
+    createValueComponent({
+      title: "Worst Interface Errors/sec",
+      top: 3,
+      left: 8,
+      width: 4,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceErrorsPerSecond,
+        aggregationType: MetricsAggregationType.Max,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+    createValueComponent({
+      title: "Peak Inbound",
+      top: 4,
+      left: 8,
+      width: 4,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceInBitsPerSecond,
+        aggregationType: MetricsAggregationType.Max,
+      },
+    }),
+    createValueComponent({
+      title: "Peak Outbound",
+      top: 5,
+      left: 8,
+      width: 4,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceOutBitsPerSecond,
+        aggregationType: MetricsAggregationType.Max,
+      },
+    }),
+
+    // Row 6: Section header
+    createTextComponent({
+      text: "Interface Throughput",
+      top: 6,
+      left: 0,
+      width: 12,
+      height: 1,
+      isBold: true,
+    }),
+
+    /*
+     * Rows 7-9: throughput, split per interface. Grouping by
+     * `interfaceName` is what turns one flat line into one line per uplink,
+     * which is the only form in which "is a link saturated" is answerable —
+     * an ungrouped chart averages a saturated uplink with nine idle access
+     * ports and reports that everything is fine.
+     */
+    createChartComponent({
+      title: "Inbound by Interface",
+      chartType: DashboardChartType.Area,
+      top: 7,
+      left: 0,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceInBitsPerSecond,
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Inbound",
+        legendUnit: "bps",
+        groupByAttributeKeys: ["interfaceName"],
+      },
+    }),
+    createChartComponent({
+      title: "Outbound by Interface",
+      chartType: DashboardChartType.Area,
+      top: 7,
+      left: 6,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceOutBitsPerSecond,
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Outbound",
+        legendUnit: "bps",
+        groupByAttributeKeys: ["interfaceName"],
+      },
+    }),
+
+    // Row 10: Section header
+    createTextComponent({
+      text: "Utilization & Errors",
+      top: 10,
+      left: 0,
+      width: 12,
+      height: 1,
+      isBold: true,
+    }),
+
+    /*
+     * Rows 11-13: the gauge an operator watches during an incident, the
+     * error-rate gauge that leads it, and the per-interface error breakdown
+     * that says WHICH port to look at.
+     */
+    createGaugeComponent({
+      title: "Peak Interface Utilization",
+      top: 11,
+      left: 0,
+      width: 3,
+      height: 3,
+      minValue: 0,
+      maxValue: 100,
+      warningThreshold: 70,
+      criticalThreshold: 90,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceUtilizationPercent,
+        aggregationType: MetricsAggregationType.Max,
+      },
+    }),
+    createGaugeComponent({
+      title: "Interface Error Rate",
+      top: 11,
+      left: 3,
+      width: 3,
+      height: 3,
+      /*
+       * A healthy Ethernet port errors essentially never, so the scale is
+       * deliberately tight: a sustained one error per second is already a
+       * cable, duplex or optic problem worth a ticket, and five is a link
+       * on its way out. A 0-100 scale like the utilization gauge next to it
+       * would render every real fault as a flat line on the floor.
+       */
+      minValue: 0,
+      maxValue: 10,
+      warningThreshold: 1,
+      criticalThreshold: 5,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceErrorsPerSecond,
+        aggregationType: MetricsAggregationType.Avg,
+      },
+    }),
+    createChartComponent({
+      title: "Interface Errors by Interface",
+      chartType: DashboardChartType.Bar,
+      top: 11,
+      left: 6,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceErrorsPerSecond,
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Errors/sec",
+        groupByAttributeKeys: ["interfaceName"],
+      },
+    }),
+
+    // Row 14: Section header
+    createTextComponent({
+      text: "Devices & Monitors",
+      top: 14,
+      left: 0,
+      width: 12,
+      height: 1,
+      isBold: true,
+    }),
+
+    /*
+     * Rows 15-18: utilization per interface, beside the monitors that page
+     * somebody when a device stops answering. The list is pinned to Network
+     * Device monitors — an unfiltered monitor list on a network dashboard is
+     * just the Monitors page with fewer columns — and it is also this
+     * dashboard's reachability view, correctly scoped in a way a shared
+     * uptime metric could never be.
+     */
+    createChartComponent({
+      title: "Utilization by Interface",
+      chartType: DashboardChartType.Line,
+      top: 15,
+      left: 0,
+      width: 6,
+      height: 4,
+      metricConfig: {
+        metricName: MonitorMetricType.SnmpInterfaceUtilizationPercent,
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Utilization",
+        legendUnit: "%",
+        groupByAttributeKeys: ["interfaceName"],
+      },
+    }),
+    createMonitorListComponent({
+      title: "Network Device Monitors",
+      top: 15,
+      left: 6,
+      width: 6,
+      height: 4,
+      maxRows: 25,
+      monitorTypes: [MonitorType.NetworkDevice],
+    }),
+  ];
+
+  /*
+   * Network device metrics are stored with BARE attribute keys
+   * (`deviceName`, `interfaceName`) rather than the OTel `resource.` prefix
+   * — see NetworkDeviceMetricUtil.buildDeviceMetricRow — so the variables
+   * bind to the bare keys. Both are multi-select: comparing two uplinks, or
+   * two branch routers, is the normal use rather than the exception.
+   */
+  const variables: Array<DashboardVariable> = [
+    createTelemetryAttributeVariable({
+      name: "device",
+      label: "Device",
+      attributeKey: "deviceName",
+      isMultiSelect: true,
+    }),
+    createTelemetryAttributeVariable({
+      name: "interface",
+      label: "Interface",
+      attributeKey: "interfaceName",
+      isMultiSelect: true,
+    }),
+  ];
+
+  return {
+    _type: ObjectType.DashboardViewConfig,
+    components,
+    variables,
+    heightInDashboardUnits: Math.max(DashboardSize.heightInDashboardUnits, 19),
+  };
+}
+
 export function getTemplateConfig(
   type: DashboardTemplateType,
 ): DashboardViewConfig | null {
@@ -3437,6 +3832,8 @@ export function getTemplateConfig(
       return createMetricsDashboardConfig();
     case DashboardTemplateType.Rum:
       return createRumDashboardConfig();
+    case DashboardTemplateType.Network:
+      return createNetworkDashboardConfig();
     case DashboardTemplateType.Blank:
       return null;
   }

package/Types/Database/BigIntColumnTransformer.ts

@@ -0,0 +1,74 @@
+import { ValueTransformer } from "typeorm/decorator/options/ValueTransformer";
+
+/*
+ * Round-trip for columns declared `ColumnType.BigPositiveNumber` (Postgres
+ * bigint) that the rest of the codebase wants to read as a plain number.
+ *
+ * `to` MUST pass `undefined` through untouched. TypeORM runs the column
+ * transformer *before* it decides whether the column was supplied at all:
+ *
+ *   InsertQueryBuilder.createColumnValueExpression
+ *     -> driver.preparePersistentValue    (applies transformer.to)
+ *     -> if (value === undefined) expression += "DEFAULT"
+ *
+ * so a transformer that folds `undefined` into `null` rewrites "the caller
+ * did not set this column" into "the caller explicitly set it to NULL". The
+ * column's DEFAULT is then never reached. On a `NOT NULL DEFAULT 0` counter
+ * that is a 500 on *every* insert:
+ *
+ *   null value in column "droppedCount" of relation "LogDropFilter"
+ *   violates not-null constraint
+ *
+ * which is exactly what shipped for the drop-filter drop counters. Nothing
+ * in the product sets those counters on create — they are ingest-owned — so
+ * every drop filter created through the dashboard failed.
+ *
+ * `from` exists because node-postgres hands bigint back as a string (it does
+ * not fit a JS number in the general case). Every value we store here is a
+ * record counter well inside Number.MAX_SAFE_INTEGER, and the UI renders it
+ * as a number, so normalize once here rather than making each reader
+ * remember.
+ */
+export function getBigIntDatabaseTransformer(): ValueTransformer {
+  return {
+    to: (value: number | null | undefined): string | null | undefined => {
+      /*
+       * Not a mistake and not the same as `null`: see the note above. This
+       * is the branch that lets the column DEFAULT apply.
+       */
+      if (value === undefined) {
+        return undefined;
+      }
+
+      if (value === null) {
+        return null;
+      }
+
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        /*
+         * `Math.trunc(NaN).toString()` is the string "NaN", which Postgres
+         * rejects with a syntax error that names neither the column nor the
+         * caller. Null at least fails as a constraint violation on the
+         * column it belongs to.
+         */
+        return null;
+      }
+
+      return Math.trunc(value).toString();
+    },
+
+    from: (value: string | number | null | undefined): number | null => {
+      if (value === null || value === undefined) {
+        return null;
+      }
+
+      if (typeof value === "number") {
+        return Number.isFinite(value) ? value : null;
+      }
+
+      const parsed: number = parseInt(value, 10);
+
+      return isNaN(parsed) ? null : parsed;
+    },
+  };
+}

package/Types/Database/DatabaseProperty.ts

@@ -45,6 +45,32 @@ export default class DatabaseProperty extends SerializableObject {
   public static getDatabaseTransformer(): ValueTransformer {
     return {
       to: (value: any) => {
+        /*
+         * `undefined` means "the caller did not set this column", and it has
+         * to stay distinguishable from `null` all the way into TypeORM.
+         *
+         * TypeORM runs the transformer BEFORE deciding whether the column
+         * was supplied:
+         *
+         *   InsertQueryBuilder.createColumnValueExpression
+         *     -> driver.preparePersistentValue   (runs this function)
+         *     -> if (value === undefined) expression += "DEFAULT"
+         *
+         * so answering `null` here (which every `toDatabase` does for a
+         * falsy value) rewrites an omitted column into an explicit NULL and
+         * makes the column's DEFAULT unreachable. On a NOT NULL column with
+         * a default — an on-call layer's `rotation`, a drop filter's
+         * `droppedCount` — that is a not-null constraint violation, i.e. an
+         * HTTP 500, on every create that leaves the column alone.
+         *
+         * UPDATE is unaffected either way: UpdateQueryBuilder strips
+         * undefined properties before the transformer ever sees them
+         * ("it doesn't make sense to update undefined properties").
+         */
+        if (value === undefined) {
+          return undefined;
+        }
+
         return this._toDatabase(value);
       },
       from: (value: any) => {

package/Types/Database/NumericColumnValue.ts

@@ -0,0 +1,128 @@
+import { JSONObject, JSONValue } from "../JSON";
+import { TableColumnMetadata } from "./TableColumn";
+import TableColumnType from "./TableColumnType";
+
+/*
+ * Column types whose in-memory representation is a plain JavaScript number.
+ *
+ * Deliberately excludes the types that merely *look* numeric — `Port`,
+ * `Version`, `Date` — because coercing those would destroy them.
+ *
+ * The declared type is not a perfect proxy for the in-memory one: an SMTP
+ * port is declared `Number` but typed `Port`, and a usage figure is declared
+ * `Number` but typed `Decimal`. Coercing a string to a number is safe for
+ * those only because each of their transformers accepts a raw number —
+ * which is a property their tests pin, not an accident.
+ */
+const NUMERIC_TABLE_COLUMN_TYPES: Set<TableColumnType> =
+  new Set<TableColumnType>([
+    TableColumnType.Number,
+    TableColumnType.SmallNumber,
+    TableColumnType.BigNumber,
+    TableColumnType.PositiveNumber,
+    TableColumnType.SmallPositiveNumber,
+    TableColumnType.BigPositiveNumber,
+  ]);
+
+export function isNumericTableColumnType(
+  type: TableColumnType | undefined | null,
+): boolean {
+  if (!type) {
+    return false;
+  }
+
+  return NUMERIC_TABLE_COLUMN_TYPES.has(type);
+}
+
+/*
+ * Normalize a JSON value destined for a number column.
+ *
+ * The dashboard's number form field is an `<input type="number">`, and a DOM
+ * input's value is a *string* — there is no numeric input event in HTML. So
+ * "10" typed into "Sample Percentage" reached the API as the JSON string
+ * "10", and any server-side check spelled `typeof value === "number"`
+ * rejected a perfectly valid form submission:
+ *
+ *   BadDataException: Sample percentage is required when the action is
+ *   "Sample" ... between 1 and 99.
+ *
+ * Postgres silently coerces '10' to 10 on the way in, which is why this had
+ * gone unnoticed on every other number field in the product: the string only
+ * becomes visible when something reads the value before it is stored.
+ *
+ * Normalizing here — where the column's declared type is known, on both the
+ * browser side (ModelForm -> BaseModel.fromJSON) and the server side
+ * (BaseAPI -> BaseModel.fromJSON) — means a number column holds a number by
+ * the time any hook, validator or query sees it.
+ *
+ * Only strings that parse cleanly to a finite number are converted. A blank
+ * string is left alone rather than turned into `0` (`Number("")` is 0, which
+ * would silently write a real value for a field the user cleared) or into
+ * `null` (which would defeat a column DEFAULT the same way the bigint
+ * transformer used to). Garbage like "abc" is left alone too, so validation
+ * rejects it with a message about the field instead of this function
+ * inventing a value.
+ */
+export function coerceNumericColumnValue(value: unknown): unknown {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  const trimmed: string = value.trim();
+
+  if (trimmed.length === 0) {
+    return value;
+  }
+
+  const parsed: number = Number(trimmed);
+
+  if (!Number.isFinite(parsed)) {
+    return value;
+  }
+
+  return parsed;
+}
+
+/*
+ * The minimum a model has to offer for its number columns to be found.
+ * Every DatabaseBaseModel satisfies it; asking for only this keeps the
+ * coercion usable from the API layer without dragging the model class in.
+ */
+export interface ColumnMetadataSource {
+  getTableColumnMetadata: (columnName: string) => TableColumnMetadata;
+}
+
+/*
+ * Coerce the number columns of a loose JSON patch, in place.
+ *
+ * `BaseModel.fromJSON` does this on its way to building a model, but an
+ * update never builds one — `BaseAPI.updateItem` goes from the request body
+ * straight to a partial entity — so without this a PATCH and a POST
+ * disagree about whether "10" is a number. That matters because the
+ * save-time hooks read these values before the database gets a chance to
+ * coerce them.
+ *
+ * Values that are not strings are left exactly as they are, including the
+ * `() => string` raw SQL expressions a PartialEntity may carry.
+ */
+export function coerceNumericColumnsInJSON(
+  json: JSONObject,
+  model: ColumnMetadataSource,
+): JSONObject {
+  for (const key of Object.keys(json)) {
+    const tableColumnMetadata: TableColumnMetadata =
+      model.getTableColumnMetadata(key);
+
+    if (!tableColumnMetadata) {
+      continue;
+    }
+
+    if (!isNumericTableColumnType(tableColumnMetadata.type)) {
+      continue;
+    }
+
+    json[key] = coerceNumericColumnValue(json[key]) as JSONValue;
+  }
+
+  return json;
+}