@oneuptime/common 10.0.65 → 10.0.66

package/Types/Metrics/MetricDownsamplingRetentionDays.ts

@@ -0,0 +1,49 @@
+/*
+ * Per-tier retention (in days) for downsampled metric storage.
+ *
+ * On Project, this is the default that applies to all services.
+ * On Service, this is an optional override — null fields inherit from the project default.
+ *
+ * Keys are tier identifiers: "raw" (untouched OTel data points), "1m", "5m", "1h", "1d".
+ */
+
+export default interface MetricDownsamplingRetentionDays {
+  raw?: number | null;
+  "1m"?: number | null;
+  "5m"?: number | null;
+  "1h"?: number | null;
+  "1d"?: number | null;
+}
+
+export const DEFAULT_METRIC_DOWNSAMPLING_RETENTION_DAYS: Record<
+  keyof MetricDownsamplingRetentionDays,
+  number
+> = {
+  raw: 7,
+  "1m": 14,
+  "5m": 30,
+  "1h": 90,
+  "1d": 365,
+};
+
+export const DEFAULT_METRIC_CARDINALITY_BUDGET: number = 10000;
+
+/*
+ * Resolves the effective retention days for a given tier, falling back through
+ * service override → project default → hardcoded default.
+ */
+export function resolveTierRetentionDays(
+  tier: keyof MetricDownsamplingRetentionDays,
+  serviceOverride: MetricDownsamplingRetentionDays | null | undefined,
+  projectDefault: MetricDownsamplingRetentionDays | null | undefined,
+): number {
+  const serviceValue: number | null | undefined = serviceOverride?.[tier];
+  if (typeof serviceValue === "number" && serviceValue > 0) {
+    return serviceValue;
+  }
+  const projectValue: number | null | undefined = projectDefault?.[tier];
+  if (typeof projectValue === "number" && projectValue > 0) {
+    return projectValue;
+  }
+  return DEFAULT_METRIC_DOWNSAMPLING_RETENTION_DAYS[tier];
+}

package/Types/Metrics/MetricFormulaConfigData.ts

@@ -1,7 +1,11 @@
 import MetricAliasData from "./MetricAliasData";
 import MetricFormulaData from "./MetricFormulaData";
+import { MetricChartType } from "./MetricQueryConfigData";
 
 export default interface MetricFormulaConfigData {
   metricAliasData: MetricAliasData;
   metricFormulaData: MetricFormulaData;
+  chartType?: MetricChartType | undefined;
+  warningThreshold?: number | undefined;
+  criticalThreshold?: number | undefined;
 }

package/Types/Metrics/MetricPipelineRuleFilterCondition.ts

@@ -0,0 +1,136 @@
+export enum MetricPipelineRuleFilterCheckOn {
+  MetricName = "Metric Name",
+  Attribute = "Attribute",
+}
+
+export enum MetricPipelineRuleFilterConditionType {
+  EqualTo = "Equal To",
+  NotEqualTo = "Not Equal To",
+  Contains = "Contains",
+  NotContains = "Not Contains",
+  StartsWith = "Starts With",
+  EndsWith = "Ends With",
+  MatchesRegex = "Matches Regex",
+  DoesNotMatchRegex = "Does Not Match Regex",
+  IsPresent = "Is Present",
+  IsNotPresent = "Is Not Present",
+  IsEmpty = "Is Empty",
+  IsNotEmpty = "Is Not Empty",
+}
+
+export default interface MetricPipelineRuleFilterCondition {
+  checkOn: MetricPipelineRuleFilterCheckOn;
+  // Required when checkOn is Attribute. The attribute key to evaluate on.
+  attributeKey?: string | undefined;
+  conditionType: MetricPipelineRuleFilterConditionType | undefined;
+  // Required for conditions that compare against a value.
+  value?: string | undefined;
+}
+
+export class MetricPipelineRuleFilterConditionUtil {
+  public static getCheckOnOptions(): Array<MetricPipelineRuleFilterCheckOn> {
+    return [
+      MetricPipelineRuleFilterCheckOn.MetricName,
+      MetricPipelineRuleFilterCheckOn.Attribute,
+    ];
+  }
+
+  public static getConditionTypesByCheckOn(
+    checkOn: MetricPipelineRuleFilterCheckOn,
+  ): Array<MetricPipelineRuleFilterConditionType> {
+    switch (checkOn) {
+      case MetricPipelineRuleFilterCheckOn.MetricName:
+        return [
+          MetricPipelineRuleFilterConditionType.EqualTo,
+          MetricPipelineRuleFilterConditionType.NotEqualTo,
+          MetricPipelineRuleFilterConditionType.Contains,
+          MetricPipelineRuleFilterConditionType.NotContains,
+          MetricPipelineRuleFilterConditionType.StartsWith,
+          MetricPipelineRuleFilterConditionType.EndsWith,
+          MetricPipelineRuleFilterConditionType.MatchesRegex,
+          MetricPipelineRuleFilterConditionType.DoesNotMatchRegex,
+        ];
+      case MetricPipelineRuleFilterCheckOn.Attribute:
+        return [
+          MetricPipelineRuleFilterConditionType.IsPresent,
+          MetricPipelineRuleFilterConditionType.IsNotPresent,
+          MetricPipelineRuleFilterConditionType.IsEmpty,
+          MetricPipelineRuleFilterConditionType.IsNotEmpty,
+          MetricPipelineRuleFilterConditionType.EqualTo,
+          MetricPipelineRuleFilterConditionType.NotEqualTo,
+          MetricPipelineRuleFilterConditionType.Contains,
+          MetricPipelineRuleFilterConditionType.NotContains,
+          MetricPipelineRuleFilterConditionType.StartsWith,
+          MetricPipelineRuleFilterConditionType.EndsWith,
+          MetricPipelineRuleFilterConditionType.MatchesRegex,
+          MetricPipelineRuleFilterConditionType.DoesNotMatchRegex,
+        ];
+      default:
+        return [];
+    }
+  }
+
+  public static hasAttributeKeyField(
+    checkOn: MetricPipelineRuleFilterCheckOn,
+  ): boolean {
+    return checkOn === MetricPipelineRuleFilterCheckOn.Attribute;
+  }
+
+  public static hasValueField(
+    conditionType: MetricPipelineRuleFilterConditionType | undefined,
+  ): boolean {
+    if (!conditionType) {
+      return false;
+    }
+    switch (conditionType) {
+      case MetricPipelineRuleFilterConditionType.IsPresent:
+      case MetricPipelineRuleFilterConditionType.IsNotPresent:
+      case MetricPipelineRuleFilterConditionType.IsEmpty:
+      case MetricPipelineRuleFilterConditionType.IsNotEmpty:
+        return false;
+      default:
+        return true;
+    }
+  }
+
+  public static getValidationError(
+    filters: Array<MetricPipelineRuleFilterCondition> | undefined,
+  ): string | null {
+    if (!filters || filters.length === 0) {
+      return null;
+    }
+
+    for (let i: number = 0; i < filters.length; i++) {
+      const filter: MetricPipelineRuleFilterCondition = filters[i]!;
+      const prefix: string = `Filter #${i + 1}: `;
+
+      if (!filter.checkOn) {
+        return `${prefix}Filter type is required.`;
+      }
+
+      if (!filter.conditionType) {
+        return `${prefix}Condition is required.`;
+      }
+
+      if (
+        MetricPipelineRuleFilterConditionUtil.hasAttributeKeyField(
+          filter.checkOn,
+        ) &&
+        !filter.attributeKey?.trim()
+      ) {
+        return `${prefix}Attribute key is required.`;
+      }
+
+      if (
+        MetricPipelineRuleFilterConditionUtil.hasValueField(
+          filter.conditionType,
+        ) &&
+        !filter.value?.toString().trim()
+      ) {
+        return `${prefix}Value is required.`;
+      }
+    }
+
+    return null;
+  }
+}

package/Types/Metrics/MetricPipelineRuleType.ts

@@ -0,0 +1,27 @@
+/*
+ * Rule types for the metric ingest pipeline. Evaluated per data-point in
+ * OtelMetricsIngestService after buildMetricRow() and before the ClickHouse
+ * insert buffer.
+ *
+ * - Filter:           keep only rows matching the match expression; drop others.
+ * - Drop:             drop rows matching the match expression; keep others.
+ * - RenameMetric:     rename the metric (row.name) from one string to another.
+ * - RenameAttribute:  rename an attribute key (renameFromKey -> renameToKey).
+ * - AddAttribute:     add an attribute (addAttributeKey = addAttributeValue).
+ * - RemoveAttribute:  remove an attribute by key.
+ * - RedactAttribute:  replace an attribute's value with redactReplacement.
+ * - Sample:           keep `samplePercentage`% of matching rows; drop the rest.
+ */
+
+enum MetricPipelineRuleType {
+  Filter = "Filter",
+  Drop = "Drop",
+  RenameMetric = "RenameMetric",
+  RenameAttribute = "RenameAttribute",
+  AddAttribute = "AddAttribute",
+  RemoveAttribute = "RemoveAttribute",
+  RedactAttribute = "RedactAttribute",
+  Sample = "Sample",
+}
+
+export default MetricPipelineRuleType;

package/Types/Metrics/RecordingRuleDefinition.ts

@@ -0,0 +1,180 @@
+import AggregationType from "../BaseDatabase/AggregationType";
+
+/*
+ * A single source metric inside a Recording Rule. Each source is given an
+ * alphabetic alias (A, B, C, ...) that can be referenced from the rule's
+ * expression string. Aliases are case-sensitive and match /^[A-Z]$/ in v1.
+ */
+export interface RecordingRuleSource {
+  alias: string;
+  metricName: string;
+  aggregationType: AggregationType;
+  // Optional pre-filter so you can say e.g. "A = sum(http.requests WHERE http.status_code_class = '5xx')".
+  filterAttributeKey?: string;
+  filterAttributeValue?: string;
+}
+
+/*
+ * Full stored definition of a Recording Rule. Persisted as a JSONB column on
+ * MetricRecordingRule so we don't have to migrate the Postgres schema every
+ * time we add a new field.
+ */
+export default interface RecordingRuleDefinition {
+  sources: Array<RecordingRuleSource>;
+  /*
+   * Arithmetic expression in our simple DSL: operators + - * /, parentheses,
+   * numeric literals, and alias references. Example: "A / B * 100".
+   */
+  expression: string;
+  /*
+   * Optional attribute key to group source queries by and preserve on output
+   * rows. One derived data point per group per evaluation bucket.
+   */
+  groupByAttribute?: string;
+}
+
+/*
+ * Maximum number of source metrics per rule for v1. Kept small to bound the
+ * per-cron workload.
+ */
+export const RECORDING_RULE_MAX_SOURCES: number = 4;
+
+// Maximum expression length for v1. Prevents pathological parser input.
+export const RECORDING_RULE_MAX_EXPRESSION_LENGTH: number = 500;
+
+/*
+ * Alphabet used to generate source aliases. v1 caps at RECORDING_RULE_MAX_SOURCES
+ * so we never exceed the first few letters in practice.
+ */
+const ALIAS_ALPHABET: string = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+const ALIAS_REGEX: RegExp = /^[A-Z]$/;
+
+const EXPRESSION_REGEX: RegExp = /^[A-Z0-9+\-*/().\s]+$/;
+
+export class RecordingRuleDefinitionUtil {
+  public static getAggregationOptions(): Array<{
+    value: AggregationType;
+    label: string;
+  }> {
+    return [
+      { value: AggregationType.Sum, label: "Sum" },
+      { value: AggregationType.Avg, label: "Average" },
+      { value: AggregationType.Count, label: "Count" },
+      { value: AggregationType.Min, label: "Minimum" },
+      { value: AggregationType.Max, label: "Maximum" },
+    ];
+  }
+
+  public static getNextAlias(
+    sources: Array<RecordingRuleSource> | undefined,
+  ): string {
+    const used: Set<string> = new Set<string>(
+      (sources || []).map((s: RecordingRuleSource) => {
+        return s.alias;
+      }),
+    );
+    for (const letter of ALIAS_ALPHABET) {
+      if (!used.has(letter)) {
+        return letter;
+      }
+    }
+    return "A";
+  }
+
+  public static getEmptyDefinition(): RecordingRuleDefinition {
+    return {
+      sources: [
+        {
+          alias: "A",
+          metricName: "",
+          aggregationType: AggregationType.Sum,
+        },
+      ],
+      expression: "A",
+      groupByAttribute: "",
+    };
+  }
+
+  public static getValidationError(
+    definition: RecordingRuleDefinition | undefined,
+  ): string | null {
+    if (!definition) {
+      return "Definition is required.";
+    }
+
+    const sources: Array<RecordingRuleSource> = definition.sources || [];
+
+    if (sources.length === 0) {
+      return "Add at least one source metric.";
+    }
+
+    if (sources.length > RECORDING_RULE_MAX_SOURCES) {
+      return `A rule can reference at most ${RECORDING_RULE_MAX_SOURCES} source metrics.`;
+    }
+
+    const aliases: Set<string> = new Set<string>();
+    for (let i: number = 0; i < sources.length; i++) {
+      const source: RecordingRuleSource = sources[i]!;
+      const prefix: string = `Source ${source.alias || `#${i + 1}`}: `;
+
+      if (!source.alias || !ALIAS_REGEX.test(source.alias)) {
+        return `${prefix}Alias must be a single uppercase letter A-Z.`;
+      }
+
+      if (aliases.has(source.alias)) {
+        return `${prefix}Duplicate alias. Each source must have a unique letter.`;
+      }
+      aliases.add(source.alias);
+
+      if (!source.metricName?.trim()) {
+        return `${prefix}Metric name is required.`;
+      }
+
+      if (!source.aggregationType) {
+        return `${prefix}Aggregation type is required.`;
+      }
+
+      const hasFilterKey: boolean = Boolean(source.filterAttributeKey?.trim());
+      const hasFilterValue: boolean = Boolean(
+        source.filterAttributeValue?.trim(),
+      );
+
+      if (hasFilterKey !== hasFilterValue) {
+        return `${prefix}Attribute filter needs both a key and a value (or leave both empty).`;
+      }
+    }
+
+    const expression: string = (definition.expression || "").trim();
+
+    if (!expression) {
+      return "Expression is required.";
+    }
+
+    if (expression.length > RECORDING_RULE_MAX_EXPRESSION_LENGTH) {
+      return `Expression must be ${RECORDING_RULE_MAX_EXPRESSION_LENGTH} characters or fewer.`;
+    }
+
+    // Expression may only use aliases defined in sources.
+    const referencedAliases: Set<string> = new Set<string>(
+      expression.match(/[A-Z]/g) || [],
+    );
+    for (const alias of referencedAliases) {
+      if (!aliases.has(alias)) {
+        return `Expression references alias '${alias}' which is not defined in sources.`;
+      }
+    }
+
+    // Must reference at least one alias — otherwise the expression is a constant.
+    if (referencedAliases.size === 0) {
+      return "Expression must reference at least one source alias (e.g. A, B).";
+    }
+
+    // Reject any character outside the allowed DSL grammar.
+    if (!EXPRESSION_REGEX.test(expression)) {
+      return "Expression may only contain aliases (A-Z), numbers, operators (+ - * /), parentheses, and spaces.";
+    }
+
+    return null;
+  }
+}

package/Types/Monitor/CriteriaFilter.ts

@@ -1,4 +1,5 @@
 import Zod, { ZodSchema } from "../../Utils/Schema/Zod";
+import MetricCriteriaContext from "./MetricMonitor/MetricCriteriaContext";
 
 export enum CheckOn {
   ResponseTime = "Response Time (in ms)",
@@ -103,9 +104,42 @@ export enum EvaluateOverTimeType {
   AnyValue = "Any Value",
 }
 
+export enum NoDataPolicy {
+  /*
+   * Do not treat missing data as a breach. The criterion simply does
+   * not fire. This is the safest default and matches most SaaS tooling.
+   */
+  Ignore = "Ignore",
+  /*
+   * Treat missing data points as zero. Preserves the original behavior
+   * prior to this policy being configurable — useful for counters where
+   * "no events" genuinely means zero.
+   */
+  TreatAsZero = "Treat As Zero",
+  /*
+   * Trigger the criterion as a breach regardless of threshold. Use for
+   * heartbeat-style metrics where the absence of data is itself the
+   * problem.
+   */
+  Trigger = "Trigger",
+}
+
 export interface MetricMonitorOptions {
   metricAlias?: string | undefined;
   metricAggregationType?: EvaluateOverTimeType | undefined;
+  /*
+   * Governs how the evaluator handles the case where the metric query
+   * returned zero samples in the evaluation window. Defaults to Ignore
+   * when unset.
+   */
+  onNoDataPolicy?: NoDataPolicy | undefined;
+  /*
+   * Unit the user entered the threshold value in (e.g. "MB", "sec").
+   * The evaluator converts the threshold into the metric's native unit
+   * before comparison. When unset, the threshold is assumed to already
+   * be in the metric's native unit (backward compatible).
+   */
+  thresholdUnit?: string | undefined;
 }
 
 export enum EvaluateOverTimeMinutes {
@@ -134,6 +168,13 @@ export interface CriteriaFilter {
   value: string | number | undefined;
   evaluateOverTime?: boolean | undefined;
   evaluateOverTimeOptions?: EvaluateOverTimeOptions | undefined;
+  /*
+   * Populated at evaluation time for metric monitors so downstream code
+   * (e.g. the root cause builder) can include metric-specific context
+   * like metric name, unit, filter/group-by attributes, and the series
+   * that actually breached. Not persisted.
+   */
+  metricCriteriaContext?: MetricCriteriaContext | undefined;
 }
 
 export enum FilterType {
@@ -274,6 +315,8 @@ export const CriteriaFilterSchema: ZodSchema = Zod.object({
   metricMonitorOptions: Zod.object({
     metricAlias: Zod.string().optional(),
     metricAggregationType: Zod.string().optional(),
+    onNoDataPolicy: Zod.string().optional(),
+    thresholdUnit: Zod.string().optional(),
   }).optional(),
   snmpMonitorOptions: Zod.object({
     oid: Zod.string().optional(),

package/Types/Monitor/MetricMonitor/MetricCriteriaContext.ts

@@ -0,0 +1,70 @@
+import { JSONObject } from "../../JSON";
+import MetricsAggregationType from "../../Metrics/MetricsAggregationType";
+
+/**
+ * A per-timestamp snapshot of a variable referenced by a formula —
+ * used to show "what did $a and $b evaluate to when c breached?" on the
+ * incident root-cause page.
+ */
+export interface MetricComponentValue {
+  alias: string;
+  value: number | null;
+}
+
+export interface MetricBreachingSample {
+  value: number;
+  timestamp: Date;
+  attributes: JSONObject;
+  /**
+   * For formula evaluations: the values of each referenced variable at
+   * this timestamp. Keyed by variable alias. Absent for plain metric
+   * criteria.
+   */
+  componentValues?: Array<MetricComponentValue> | undefined;
+}
+
+/**
+ * Descriptor for one variable referenced by a formula, used to label
+ * table columns and render the Metric Details section. Name is the
+ * metric display name (usually the metric name, sometimes the formula
+ * expression for nested formulas) and unit is the variable's native
+ * unit as configured.
+ */
+export interface MetricComponent {
+  alias: string;
+  name: string;
+  unit: string | null;
+  isFormula: boolean;
+}
+
+export default interface MetricCriteriaContext {
+  metricName: string;
+  alias: string;
+  unit: string | null;
+  aggregationType: MetricsAggregationType | null;
+  isFormula: boolean;
+  formulaExpression?: string | undefined;
+  filterAttributes: JSONObject;
+  groupBy: Array<string>;
+  timeWindowMinutes?: number | undefined;
+  breachingSample?: MetricBreachingSample | undefined;
+  /**
+   * All samples in the evaluation window that breached the threshold,
+   * in chronological order. Used to render a table of timestamps and
+   * values on the incident root-cause page.
+   */
+  breachingSamples?: Array<MetricBreachingSample> | undefined;
+  /**
+   * Total number of samples considered during evaluation (including
+   * non-breaching ones), so the root cause can show "N of M samples
+   * breached" without re-querying.
+   */
+  totalSamplesInWindow?: number | undefined;
+  /**
+   * For formulas: metadata for each variable the formula references,
+   * in the order they appear in the expression. Consumers use this to
+   * label breakdown columns and to surface underlying units/metric
+   * names in the Metric Details section.
+   */
+  components?: Array<MetricComponent> | undefined;
+}