@oneuptime/common 12.0.4 → 12.0.6

package/Types/AI/AIInsightEvidence.ts

@@ -30,6 +30,12 @@ export interface ExceptionInsightEvidence {
   spikeMultiplier?: number | undefined;
   // Lifetime occurrence count of the exception.
   totalOccurrenceCount?: number | undefined;
+  /*
+   * How many distinct TelemetryException groups (i.e. stack-trace variants of
+   * the same type + normalized message) this finding rolls up. 1 for the
+   * ordinary case; higher when one throw site surfaces on several call paths.
+   */
+  distinctExceptionGroupCount?: number | undefined;
   // ISO-8601 — when the exception was first ever seen.
   firstSeenAt?: string | undefined;
 }

package/Types/AI/AIRunCodeFixRecommendation.ts

@@ -0,0 +1,17 @@
+/*
+ * The durable code-fix recommendation for an incident/alert investigation.
+ * Stored on AIRun so the dashboard and the manual fix-task endpoint consume
+ * the same server-authored decision instead of interpreting analysis prose.
+ *
+ * Every run starts NotRecommended. The investigation engine atomically moves
+ * a winning incident/alert run to Pending with its Completed transition, then
+ * settles the posted analysis to a terminal recommendation. This keeps all
+ * error, legacy and non-investigation paths fail closed.
+ */
+enum AIRunCodeFixRecommendation {
+  Pending = "Pending",
+  Recommended = "Recommended",
+  NotRecommended = "NotRecommended",
+}
+
+export default AIRunCodeFixRecommendation;

package/Types/AI/CodeFixTaskContext.ts

@@ -1,7 +1,8 @@
 /*
- * The JSON persisted on AIRun.taskContext for CodeFix recipes whose entire
- * working context is captured at trigger time rather than referenced by a
- * subject id (incident/alert) or a telemetry exception.
+ * The JSON persisted on AIRun.taskContext for tasks whose exact working
+ * context must survive until a worker claims them. Some recipes have no
+ * durable subject record; others, such as FixFromIncident, deliberately pin
+ * a snapshot instead of re-reading mutable subject state at execution time.
  *
  * First user: the FixPerformance recipe. Its evidence is computed
  * DETERMINISTICALLY from a trace's span tree when the user clicks "Fix
@@ -74,7 +75,29 @@ export interface PerformanceCodeLocation {
   lineNumber?: number | undefined;
 }
 
+/*
+ * The immutable investigation snapshot consumed by FixFromIncident. Both
+ * fields travel together: the run id proves which Recommended decision was
+ * gated, and the markdown is the exact posted analysis that decision covered.
+ */
+export interface InvestigationCodeFixTaskSnapshot {
+  investigationRunId: string;
+  investigationAnalysisMarkdown: string;
+}
+
 export interface CodeFixTaskContext {
+  /*
+   * FixFromIncident: the exact investigation whose published RootCause is
+   * the task's context. This prevents a later re-investigation from changing
+   * the report between the user's click and the worker claiming the task.
+   */
+  sourceInvestigationRunId?: string | undefined;
+  /*
+   * Snapshot of that run's published analysis. Fix tasks can wait in the
+   * queue, so reading the feed again when the worker claims the task would
+   * let a later re-investigation silently change the requested fix.
+   */
+  sourceInvestigationAnalysisMarkdown?: string | undefined;
   // FixPerformance: the analyzed trace.
   traceId?: string | undefined;
   // Best-effort service attribution resolved from the trace's spans.
@@ -91,4 +114,41 @@ export interface CodeFixTaskContext {
   telemetryServiceId?: string | undefined;
 }
 
+/*
+ * Canonical JSON shape persisted for a Recommended investigation. Unlike the
+ * normalized snapshot returned below, these names are the established
+ * AIRun.taskContext wire contract.
+ */
+export type InvestigationCodeFixTaskContext = CodeFixTaskContext & {
+  sourceInvestigationRunId: string;
+  sourceInvestigationAnalysisMarkdown: string;
+};
+
+/*
+ * Treat partial, empty and malformed JSON as no snapshot. The same validator
+ * is shared by the trigger, claim guard and task-details reader so none of
+ * those boundaries can silently fall back to a different investigation.
+ */
+export function getInvestigationCodeFixTaskSnapshot(
+  taskContext: CodeFixTaskContext | null | undefined,
+): InvestigationCodeFixTaskSnapshot | null {
+  const investigationRunId: unknown = taskContext?.sourceInvestigationRunId;
+  const investigationAnalysisMarkdown: unknown =
+    taskContext?.sourceInvestigationAnalysisMarkdown;
+
+  if (
+    typeof investigationRunId !== "string" ||
+    investigationRunId.trim().length === 0 ||
+    typeof investigationAnalysisMarkdown !== "string" ||
+    investigationAnalysisMarkdown.trim().length === 0
+  ) {
+    return null;
+  }
+
+  return {
+    investigationRunId,
+    investigationAnalysisMarkdown,
+  };
+}
+
 export default CodeFixTaskContext;

package/Types/AI/CodeFixTaskType.ts

@@ -26,9 +26,9 @@ enum CodeFixTaskType {
    * Add the observability an INCONCLUSIVE AI investigation was missing
    * (structured logs, spans, metric counters on the implicated code paths).
    * NOT user-triggerable from the exception page — it has its own automatic
-   * trigger: an inconclusive investigation on a project that opted in via
-   * Project.enableInstrumentationFixTasks (see Common/Server/Utils/AI/
-   * AI/InstrumentationTaskTrigger.ts). Its subject is the triggering
+   * trigger: an inconclusive investigation on a project that opted in through
+   * the incident/alert instrumentation fix setting (see Common/Server/Utils/
+   * AI/SRE/InstrumentationTaskTrigger.ts). Its subject is the triggering
    * incident/alert, NOT a telemetry exception.
    */
   ImproveInstrumentation = "ImproveInstrumentation",

package/Types/Analytics/RevenueEvent.ts

@@ -0,0 +1,31 @@
+import { JSONObject } from "../JSON";
+
+/**
+ * Stable, versioned events used to measure the self-serve revenue funnel.
+ *
+ * Event names are intentionally GA4-compatible snake_case. Additive property
+ * changes are safe; breaking semantic changes require a new schema version.
+ */
+export enum RevenueEventName {
+  SignupStarted = "signup_started",
+  SignupCompleted = "sign_up",
+  WorkspaceCreated = "workspace_created",
+  MonitorCreated = "monitor_created",
+  TeammateInvited = "teammate_invited",
+  SubscriptionUpgraded = "subscription_upgraded",
+  SubscriptionDowngraded = "subscription_downgraded",
+}
+
+export enum RevenueFunnelStage {
+  Acquisition = "acquisition",
+  Signup = "signup",
+  Activation = "activation",
+  Collaboration = "collaboration",
+  Revenue = "revenue",
+}
+
+export interface RevenueEventProperties extends JSONObject {
+  funnel_stage: RevenueFunnelStage;
+}
+
+export const REVENUE_EVENT_SCHEMA_VERSION: number = 1;

package/Types/Dashboard/DashboardComponentType.ts

@@ -5,6 +5,17 @@ enum DashboardComponentType {
   Clock = `Clock`,
   Table = `Table`,
   Gauge = `Gauge`,
+  /*
+   * Widgets that read an EXTERNAL Data Source (Prometheus, SQL, ClickHouse,
+   * Loki, Elasticsearch, REST) rather than OneUptime's own telemetry. They
+   * are separate component types — not a mode of the metric widgets above —
+   * so each one can carry the query editor, defaults, and rendering its own
+   * source of data actually needs. Not available on public dashboards.
+   */
+  DataSourceChart = `DataSourceChart`,
+  DataSourceValue = `DataSourceValue`,
+  DataSourceGauge = `DataSourceGauge`,
+  DataSourceTable = `DataSourceTable`,
   LogStream = `LogStream`,
   LogChart = `LogChart`,
   TraceList = `TraceList`,
@@ -44,3 +55,23 @@ enum DashboardComponentType {
 }
 
 export default DashboardComponentType;
+
+/*
+ * Every widget type that reads an EXTERNAL Data Source. Kept next to the
+ * enum so adding a fifth one is a single edit, and consumed by the widget
+ * settings form (which query editor to render) and by anything that has to
+ * treat external-data widgets as a class — notably the public dashboard,
+ * where they are unavailable.
+ */
+export const DataSourceComponentTypes: ReadonlyArray<DashboardComponentType> = [
+  DashboardComponentType.DataSourceChart,
+  DashboardComponentType.DataSourceValue,
+  DashboardComponentType.DataSourceGauge,
+  DashboardComponentType.DataSourceTable,
+];
+
+export function isDataSourceComponentType(
+  componentType: DashboardComponentType,
+): boolean {
+  return DataSourceComponentTypes.includes(componentType);
+}

package/Types/Dashboard/DashboardComponents/DashboardDataSourceChartComponent.ts

@@ -0,0 +1,27 @@
+import DataSourceQueryConfig from "../../DataSource/DataSourceQueryConfig";
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import DashboardChartType from "../Chart/ChartType";
+import BaseComponent from "./DashboardBaseComponent";
+
+/*
+ * Time-series chart over one or more EXTERNAL Data Source queries (PromQL /
+ * SQL / LogQL / ES DSL / REST). The OneUptime-metrics chart is a separate
+ * widget (DashboardChartComponent) — this one never touches metric queries,
+ * formulas, or the metric explorer.
+ *
+ * Not available on public dashboards: the anonymous API has no data-source
+ * surface, by design.
+ */
+export default interface DashboardDataSourceChartComponent
+  extends BaseComponent {
+  componentType: DashboardComponentType.DataSourceChart;
+  componentId: ObjectID;
+  arguments: {
+    // Each query becomes one overlaid set of series on the chart.
+    queries?: Array<DataSourceQueryConfig> | undefined;
+    chartTitle?: string | undefined;
+    chartDescription?: string | undefined;
+    chartType?: DashboardChartType | undefined;
+  };
+}

package/Types/Dashboard/DashboardComponents/DashboardDataSourceGaugeComponent.ts

@@ -0,0 +1,32 @@
+import DataSourceQueryConfig from "../../DataSource/DataSourceQueryConfig";
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+import { DataSourceValueReduce } from "./DashboardDataSourceValueComponent";
+
+/*
+ * Radial gauge driven by an EXTERNAL Data Source query. The
+ * OneUptime-metrics equivalent is DashboardGaugeComponent.
+ *
+ * Not available on public dashboards.
+ */
+export default interface DashboardDataSourceGaugeComponent
+  extends BaseComponent {
+  componentType: DashboardComponentType.DataSourceGauge;
+  componentId: ObjectID;
+  arguments: {
+    query?: DataSourceQueryConfig | undefined;
+    gaugeTitle?: string | undefined;
+    // See DashboardDataSourceValueComponent — same reduction, same default.
+    reduce?: DataSourceValueReduce | undefined;
+    /*
+     * Unit suffix for the centre value and the min/max footer. External
+     * queries carry no MetricType to derive one from.
+     */
+    unit?: string | undefined;
+    minValue?: number | undefined;
+    maxValue?: number | undefined;
+    warningThreshold?: number | undefined;
+    criticalThreshold?: number | undefined;
+  };
+}

package/Types/Dashboard/DashboardComponents/DashboardDataSourceTableComponent.ts

@@ -0,0 +1,30 @@
+import DataSourceQueryConfig from "../../DataSource/DataSourceQueryConfig";
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+
+/*
+ * Tabular rows straight from an EXTERNAL Data Source query. Columns come
+ * from the query result, not from widget config — the connector normalizes
+ * every source into DataSourceTableResult. The OneUptime-metrics
+ * equivalent (columns, formulas, group-by) is DashboardTableComponent.
+ *
+ * Not available on public dashboards.
+ */
+export default interface DashboardDataSourceTableComponent
+  extends BaseComponent {
+  componentType: DashboardComponentType.DataSourceTable;
+  componentId: ObjectID;
+  arguments: {
+    query?: DataSourceQueryConfig | undefined;
+    tableTitle?: string | undefined;
+    tableDescription?: string | undefined;
+    /*
+     * Client-side cap on rendered rows, applied after sorting so "top 10 by
+     * this column" works. The connector's own row cap still applies first —
+     * this only trims what the widget draws. Absent ⇒ render every row the
+     * query returned.
+     */
+    maxRows?: number | undefined;
+  };
+}

package/Types/Dashboard/DashboardComponents/DashboardDataSourceValueComponent.ts

@@ -0,0 +1,55 @@
+import DataSourceQueryConfig from "../../DataSource/DataSourceQueryConfig";
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+import { DashboardValueTrendDirection } from "./DashboardValueComponent";
+
+/*
+ * How the points a Data Source query returns over the dashboard's time
+ * window collapse into the single number the widget shows. The metric
+ * Value widget takes this from the metric query's "Aggregate by" picker;
+ * an external query has no such picker, so it is a widget argument here.
+ */
+export enum DataSourceValueReduce {
+  Last = "Last",
+  First = "First",
+  Avg = "Avg",
+  Sum = "Sum",
+  Min = "Min",
+  Max = "Max",
+}
+
+/*
+ * Single big-number stat driven by an EXTERNAL Data Source query. The
+ * OneUptime-metrics equivalent is DashboardValueComponent; the two share a
+ * renderer but not a configuration surface.
+ *
+ * Not available on public dashboards.
+ */
+export default interface DashboardDataSourceValueComponent
+  extends BaseComponent {
+  componentType: DashboardComponentType.DataSourceValue;
+  componentId: ObjectID;
+  arguments: {
+    query?: DataSourceQueryConfig | undefined;
+    title: string;
+    /*
+     * How the returned points reduce to one number. Absent ⇒ Last, which
+     * is what "the current value of this query" means for the overwhelming
+     * majority of external queries (a Prometheus instant-style rate, a SQL
+     * count per bucket).
+     */
+    reduce?: DataSourceValueReduce | undefined;
+    /*
+     * Unit suffix rendered after the number. External queries carry no
+     * OneUptime MetricType, so there is nothing to derive a unit from —
+     * the user names it. Known units also scale the value the same way
+     * metric units do ("Bytes" ⇒ 1.5 MB, "ms" ⇒ 2.4 sec, "%" ⇒ 99.9%).
+     * Empty/undefined ⇒ the raw number with no suffix.
+     */
+    unit?: string | undefined;
+    warningThreshold?: number | undefined;
+    criticalThreshold?: number | undefined;
+    trendDirection?: DashboardValueTrendDirection | undefined;
+  };
+}

package/Types/DataSource/DataSourceLimits.ts

@@ -0,0 +1,62 @@
+/*
+ * Hard resource bounds applied to every external Data Source query,
+ * regardless of connector. These protect the OneUptime API server (memory,
+ * event loop) and the customer's target system from runaway dashboard
+ * queries — a dashboard with 20 widgets refreshing every minute multiplies
+ * whatever a single query costs.
+ */
+
+// Upper bound on wall-clock time for one connection attempt.
+export const DATA_SOURCE_CONNECT_TIMEOUT_IN_MS: number = 10 * 1000;
+
+// Upper bound on wall-clock time for one query execution.
+export const DATA_SOURCE_QUERY_TIMEOUT_IN_MS: number = 30 * 1000;
+
+/*
+ * Row cap for time-series results. 11k points ≈ 7.5 days at 1-minute
+ * resolution for a single series — beyond that the chart cannot render the
+ * detail anyway. Connectors fetch cap+1 to detect truncation.
+ */
+export const DATA_SOURCE_MAX_TIME_SERIES_ROWS: number = 11000;
+
+// Row cap for tabular results — dashboards render tables, not exports.
+export const DATA_SOURCE_MAX_TABLE_ROWS: number = 1000;
+
+// Cap on distinct series one query may return before truncation.
+export const DATA_SOURCE_MAX_SERIES: number = 100;
+
+/*
+ * Cap on the raw HTTP response body accepted from HTTP-based sources
+ * (Prometheus/Loki/Elasticsearch/REST), before parsing. Prevents a
+ * misconfigured endpoint from ballooning API-server memory.
+ */
+export const DATA_SOURCE_MAX_RESPONSE_SIZE_IN_BYTES: number = 20 * 1024 * 1024;
+
+/*
+ * Default step for range queries when the client does not send one:
+ * aim for ~250 buckets across the selected window, clamped to sane bounds.
+ */
+export const DATA_SOURCE_TARGET_BUCKETS: number = 250;
+export const DATA_SOURCE_MIN_STEP_IN_SECONDS: number = 10;
+export const DATA_SOURCE_MAX_STEP_IN_SECONDS: number = 24 * 60 * 60;
+
+export class DataSourceLimitsUtil {
+  /*
+   * Derive a range-query step (seconds) from a time window: ~TARGET_BUCKETS
+   * buckets, clamped. Used server-side when the widget doesn't specify one
+   * so Prometheus/Loki range queries stay bounded no matter the window.
+   */
+  public static getStepInSeconds(startDate: Date, endDate: Date): number {
+    const rangeSeconds: number = Math.max(
+      Math.floor((endDate.getTime() - startDate.getTime()) / 1000),
+      1,
+    );
+    const rawStep: number = Math.ceil(
+      rangeSeconds / DATA_SOURCE_TARGET_BUCKETS,
+    );
+    return Math.min(
+      Math.max(rawStep, DATA_SOURCE_MIN_STEP_IN_SECONDS),
+      DATA_SOURCE_MAX_STEP_IN_SECONDS,
+    );
+  }
+}

package/Types/DataSource/DataSourceQueryConfig.ts

@@ -0,0 +1,41 @@
+/*
+ * A widget-stored binding to an external Data Source. Persisted inside
+ * `Dashboard.dashboardViewConfig` on chart/value/gauge/table components, so
+ * every field must survive JSON round-trips (plain strings/numbers only —
+ * dataSourceId is a string, not an ObjectID instance).
+ */
+export default interface DataSourceQueryConfig {
+  /*
+   * Stable identity for this query within the widget (mirrors
+   * MetricQueryConfigData.id) so editor UI state survives reorders.
+   */
+  id?: string | undefined;
+
+  // _id of the project's DataSource record this query runs against.
+  dataSourceId: string;
+
+  /*
+   * Query text in the source's native language: PromQL, SQL, LogQL,
+   * Elasticsearch Query DSL JSON, or the REST request descriptor JSON.
+   * SQL queries may use the $__startTime / $__endTime / $__startTimeMs /
+   * $__endTimeMs / $__rangeSeconds macros, replaced server-side with the
+   * dashboard's current time window.
+   */
+  query: string;
+
+  /*
+   * Optional legend template for chart series. Supports {{label}}
+   * placeholders resolved against each series' group keys (e.g. Prometheus
+   * label values). Absent ⇒ series are named from their group keys.
+   */
+  legend?: string | undefined;
+}
+
+/*
+ * What shape of result the widget wants back from the query endpoint.
+ * Charts/values/gauges consume time series; the table widget consumes rows.
+ */
+export enum DataSourceResultKind {
+  TimeSeries = "TimeSeries",
+  Table = "Table",
+}

package/Types/DataSource/DataSourceTableResult.ts

@@ -0,0 +1,38 @@
+import { JSONValue } from "../JSON";
+
+/*
+ * Column type hints let table widgets right-align numbers and format dates
+ * without sniffing every row. Connectors set these from driver metadata when
+ * available and fall back to inspecting the first row.
+ */
+export enum DataSourceTableColumnType {
+  Text = "Text",
+  Number = "Number",
+  Date = "Date",
+  Boolean = "Boolean",
+  Json = "Json",
+}
+
+export interface DataSourceTableColumn {
+  // Row-object key this column reads from.
+  key: string;
+  // Human-facing header; defaults to the key.
+  title: string;
+  type: DataSourceTableColumnType;
+}
+
+/*
+ * Normalized tabular result every connector's queryTable returns. Rows are
+ * plain JSON objects keyed by column key so the payload serializes straight
+ * through the API to the table widget.
+ */
+export default interface DataSourceTableResult {
+  columns: Array<DataSourceTableColumn>;
+  rows: Array<{ [key: string]: JSONValue }>;
+  /*
+   * True when the connector clamped the result at the row cap — the widget
+   * shows a truncation banner so users don't mistake a clamp for the full
+   * result set.
+   */
+  truncated?: boolean | undefined;
+}