@oneuptime/common 11.5.9 → 11.5.11

package/Server/Utils/ProductAnalytics.ts

@@ -0,0 +1,133 @@
+import { AnalyticsHost, AnalyticsKey } from "../EnvironmentConfig";
+import UserService from "../Services/UserService";
+import HTTPErrorResponse from "../../Types/API/HTTPErrorResponse";
+import HTTPResponse from "../../Types/API/HTTPResponse";
+import URL from "../../Types/API/URL";
+import { JSONObject } from "../../Types/JSON";
+import ObjectID from "../../Types/ObjectID";
+import User from "../../Models/DatabaseModels/User";
+import API from "../../Utils/API";
+import logger from "./Logger";
+
+/*
+ * Server-side product analytics (PostHog).
+ *
+ * Client-side events are lost to ad blockers — common with OneUptime's
+ * developer audience — so revenue and activation events are also captured
+ * here, where they cannot be blocked.
+ *
+ * Events are identified by the user's email (the same distinct id the
+ * frontends use via posthog.identify) so server and client events join into
+ * one person profile.
+ *
+ * No-ops when ANALYTICS_KEY / ANALYTICS_HOST are not configured (the default
+ * for self-hosted installs). Never throws — analytics must not break the
+ * product.
+ */
+export default class ProductAnalytics {
+  public static isConfigured(): boolean {
+    return Boolean(AnalyticsKey && AnalyticsHost);
+  }
+
+  public static capture(data: {
+    event: string;
+    distinctId: string;
+    properties?: JSONObject | undefined;
+  }): void {
+    try {
+      if (!this.isConfigured()) {
+        return;
+      }
+
+      if (!data.distinctId) {
+        return;
+      }
+
+      API.post<JSONObject>({
+        url: URL.fromString(AnalyticsHost.toString()).addRoute("/capture/"),
+        data: {
+          api_key: AnalyticsKey,
+          event: data.event,
+          distinct_id: data.distinctId,
+          properties: {
+            source: "oneuptime-server",
+            ...(data.properties || {}),
+          },
+        },
+      })
+        .then((result: HTTPResponse<JSONObject> | HTTPErrorResponse) => {
+          /*
+           * API.post resolves (does not reject) on HTTP error statuses, so a
+           * misconfigured ANALYTICS_KEY (401) or malformed body (400) must be
+           * surfaced here or events vanish with no log signal.
+           */
+          if (result instanceof HTTPErrorResponse) {
+            logger.error(
+              `ProductAnalytics capture failed for event ${data.event}: HTTP ${result.statusCode} ${result.message}`,
+            );
+          }
+        })
+        .catch((err: Error) => {
+          logger.error("ProductAnalytics capture failed:");
+          logger.error(err);
+        });
+    } catch (err) {
+      /*
+       * e.g. URL.fromString throws on a malformed ANALYTICS_HOST. Analytics
+       * runs inside request-path hooks (signup, project create, plan change)
+       * and must never fail those requests.
+       */
+      logger.error("ProductAnalytics capture failed:");
+      logger.error(err as Error);
+    }
+  }
+
+  /*
+   * Capture an event attributed to a user by id, resolving the user's email
+   * to use as the distinct id. Skips silently when the user cannot be
+   * resolved (e.g. records created by probes, workflows or API keys).
+   */
+  public static captureForUser(data: {
+    userId: ObjectID | undefined | null;
+    event: string;
+    properties?: JSONObject | undefined;
+  }): void {
+    try {
+      if (!this.isConfigured()) {
+        return;
+      }
+
+      if (!data.userId) {
+        return;
+      }
+
+      UserService.findOneById({
+        id: data.userId,
+        select: {
+          email: true,
+        },
+        props: {
+          isRoot: true,
+        },
+      })
+        .then((user: User | null) => {
+          if (!user || !user.email) {
+            return;
+          }
+
+          this.capture({
+            event: data.event,
+            distinctId: user.email.toString(),
+            properties: data.properties,
+          });
+        })
+        .catch((err: Error) => {
+          logger.error("ProductAnalytics captureForUser failed:");
+          logger.error(err);
+        });
+    } catch (err) {
+      logger.error("ProductAnalytics captureForUser failed:");
+      logger.error(err as Error);
+    }
+  }
+}

package/Server/Utils/Telemetry/Telemetry.ts

@@ -26,6 +26,8 @@ export default class TelemetryUtil {
           name: true,
           description: true,
           unit: true,
+          isMonotonic: true,
+          aggregationTemporality: true,
         },
         props: {
           isRoot: true,
@@ -66,6 +68,30 @@ export default class TelemetryUtil {
           metricType.unit = metricTypeInMap.unit || "";
         }
 
+        /*
+         * Counter semantics (isMonotonic / aggregationTemporality) are only
+         * known on OTel metric ingest paths — other callers (monitor
+         * metrics, heartbeat metrics) never set them, so an undefined
+         * incoming value means "unknown", not "clear the stored value".
+         */
+        if (
+          metricTypeInMap.isMonotonic !== undefined &&
+          metricType.isMonotonic !== metricTypeInMap.isMonotonic
+        ) {
+          isSame = false;
+          metricType.isMonotonic = metricTypeInMap.isMonotonic;
+        }
+
+        if (
+          metricTypeInMap.aggregationTemporality !== undefined &&
+          metricType.aggregationTemporality !==
+            metricTypeInMap.aggregationTemporality
+        ) {
+          isSame = false;
+          metricType.aggregationTemporality =
+            metricTypeInMap.aggregationTemporality;
+        }
+
         // check if services are same
 
         for (const serviceId of servicesInMap) {
@@ -92,6 +118,12 @@ export default class TelemetryUtil {
               services: metricType.services || [],
               description: metricTypeInMap.description || "",
               unit: metricTypeInMap.unit || "",
+              ...(metricType.isMonotonic !== undefined
+                ? { isMonotonic: metricType.isMonotonic }
+                : {}),
+              ...(metricType.aggregationTemporality !== undefined
+                ? { aggregationTemporality: metricType.aggregationTemporality }
+                : {}),
             },
             props: {
               isRoot: true,
@@ -104,6 +136,13 @@ export default class TelemetryUtil {
         metricType.name = metricName;
         metricType.description = metricTypeInMap.description || "";
         metricType.unit = metricTypeInMap.unit || "";
+        if (metricTypeInMap.isMonotonic !== undefined) {
+          metricType.isMonotonic = metricTypeInMap.isMonotonic;
+        }
+        if (metricTypeInMap.aggregationTemporality !== undefined) {
+          metricType.aggregationTemporality =
+            metricTypeInMap.aggregationTemporality;
+        }
         metricType.projectId = data.projectId;
         metricType.services = [];
 

package/Server/Utils/Telemetry/TelemetryEntity.ts

@@ -888,3 +888,24 @@ export default class TelemetryEntity {
     return out;
   }
 }
+
+/**
+ * `container.id` is the container identity (mirrors the container
+ * resolver above — id-only). Read-side helper in the mold of
+ * `EntityKey.keyForHost` & co.; it lives here rather than in the
+ * isomorphic EntityKey module because its only consumer today is the
+ * server-side container metric-rollup read path
+ * (`MetricService.tryBuildEntityAggregateMVStatement` against
+ * `MetricItemAggMV1mByContainer`), so there is no reason to widen the
+ * browser bundle. Pass the raw `container.id` attribute value.
+ */
+export function keyForContainer(
+  projectId: string,
+  containerId: string,
+): string {
+  return computeEntityKeyShared({
+    projectId,
+    entityType: EntityType.Container,
+    identifyingAttributes: { "container.id": containerId },
+  });
+}

package/Tests/Server/API/BaseAnalyticsAPI.test.ts

@@ -0,0 +1,72 @@
+import "../TestingUtils/Init";
+import BaseAnalyticsAPI from "../../../Server/API/BaseAnalyticsAPI";
+import AnalyticsDataModel from "../../../Models/AnalyticsModels/AnalyticsBaseModel/AnalyticsBaseModel";
+import AggregateBy from "../../../Types/BaseDatabase/AggregateBy";
+import { LIMIT_PER_PROJECT } from "../../../Types/Database/LimitMax";
+import { describe, expect, it } from "@jest/globals";
+
+describe("BaseAnalyticsAPI.clampAggregateLimit", () => {
+  type MakeAggregateByFunction = (
+    limit: unknown,
+  ) => AggregateBy<AnalyticsDataModel>;
+
+  const makeAggregateBy: MakeAggregateByFunction = (
+    limit: unknown,
+  ): AggregateBy<AnalyticsDataModel> => {
+    return { limit } as unknown as AggregateBy<AnalyticsDataModel>;
+  };
+
+  it("clamps a client-sent limit above LIMIT_PER_PROJECT down to LIMIT_PER_PROJECT", () => {
+    const aggregateBy: AggregateBy<AnalyticsDataModel> =
+      makeAggregateBy(999999999);
+
+    BaseAnalyticsAPI.clampAggregateLimit(aggregateBy);
+
+    expect(aggregateBy.limit).toBe(LIMIT_PER_PROJECT);
+  });
+
+  it("clamps limit = LIMIT_PER_PROJECT + 1", () => {
+    const aggregateBy: AggregateBy<AnalyticsDataModel> = makeAggregateBy(
+      LIMIT_PER_PROJECT + 1,
+    );
+
+    BaseAnalyticsAPI.clampAggregateLimit(aggregateBy);
+
+    expect(aggregateBy.limit).toBe(LIMIT_PER_PROJECT);
+  });
+
+  it("does NOT clamp down to 1000 — grouped charts legitimately use the full 10k", () => {
+    const aggregateBy: AggregateBy<AnalyticsDataModel> =
+      makeAggregateBy(LIMIT_PER_PROJECT);
+
+    BaseAnalyticsAPI.clampAggregateLimit(aggregateBy);
+
+    expect(aggregateBy.limit).toBe(LIMIT_PER_PROJECT);
+  });
+
+  it("leaves an in-range limit untouched", () => {
+    const aggregateBy: AggregateBy<AnalyticsDataModel> = makeAggregateBy(500);
+
+    BaseAnalyticsAPI.clampAggregateLimit(aggregateBy);
+
+    expect(aggregateBy.limit).toBe(500);
+  });
+
+  it("leaves an absent limit for the service layer's own defaulting", () => {
+    const aggregateBy: AggregateBy<AnalyticsDataModel> =
+      makeAggregateBy(undefined);
+
+    BaseAnalyticsAPI.clampAggregateLimit(aggregateBy);
+
+    expect(aggregateBy.limit).toBeUndefined();
+  });
+
+  it("leaves a non-numeric limit untouched (existing validation handles it)", () => {
+    const aggregateBy: AggregateBy<AnalyticsDataModel> =
+      makeAggregateBy("not-a-number");
+
+    BaseAnalyticsAPI.clampAggregateLimit(aggregateBy);
+
+    expect(aggregateBy.limit).toBe("not-a-number" as unknown as number);
+  });
+});

package/Tests/Server/Infrastructure/SemaphorePermit.test.ts

@@ -36,7 +36,15 @@ function mockRedisClient(): ClientType {
 }
 
 function lastMockPermit(): MockPermit {
-  const result: unknown = redisSemaphoreConstructor.mock.results.at(-1)?.value;
+  /*
+   * Indexed rather than .at(-1): this project targets es2017, so
+   * Array.prototype.at is outside its lib. Older @types/node pulled in newer
+   * lib references that happened to declare it, which is why this compiled
+   * before the types were aligned with the Node 26 runtime.
+   */
+  const results: Array<{ value: unknown }> =
+    redisSemaphoreConstructor.mock.results;
+  const result: unknown = results[results.length - 1]?.value;
   return result as MockPermit;
 }
 

package/Tests/Server/Services/AnalyticsDatabaseService.test.ts

@@ -364,14 +364,33 @@ describe("AnalyticsDatabaseService", () => {
       const query: string = service.toAggregateStatement(makeBaseAggregateBy())
         .statement.query;
 
-      // 1-day window derives an Hour bucket, grouped by the time column.
+      /*
+       * 1-day window derives a FifteenMinutes bucket (see
+       * AggregationIntervalUtil), which compiles through the shared
+       * expression map — NOT via lowercasing the enum into date_trunc.
+       */
       expect(query).toContain(
-        "date_trunc('hour', toStartOfInterval(column_ObjectID, INTERVAL 1 hour))",
+        "toStartOfInterval(column_ObjectID, INTERVAL 15 MINUTE) as column_ObjectID",
       );
+      expect(query).not.toContain("date_trunc('fifteenminutes'");
       expect(query).toContain("GROUP BY column_ObjectID");
       expect(query).not.toContain("min(column_ObjectID)");
     });
 
+    test("derives an Hour bucket for a 5-day window", () => {
+      const query: string = service.toAggregateStatement(
+        makeBaseAggregateBy({
+          startTimestamp: new Date("2024-01-01"),
+          endTimestamp: new Date("2024-01-06"),
+        }),
+      ).statement.query;
+
+      expect(query).toContain(
+        "date_trunc('hour', toStartOfInterval(column_ObjectID, INTERVAL 1 hour))",
+      );
+      expect(query).toContain("GROUP BY column_ObjectID");
+    });
+
     test("Total with no group-by drops the time bucket and guards empty windows", () => {
       const query: string = service.toAggregateStatement(
         makeBaseAggregateBy({ aggregationInterval: "Total" }),

package/Tests/Server/Services/MetricEntityMVKeyParity.test.ts

@@ -0,0 +1,173 @@
+import TelemetryEntity, {
+  ExtractedEntity,
+  keyForContainer,
+} from "../../../Server/Utils/Telemetry/TelemetryEntity";
+import {
+  keyForHost,
+  keyForKubernetesCluster,
+  keyForService,
+} from "../../../Utils/Telemetry/EntityKey";
+import EntityType from "../../../Types/Telemetry/EntityType";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * Pins the read-side key derivations MetricService's entity-MV routing
+ * uses (keyForHost / keyForKubernetesCluster / keyForContainer /
+ * keyForService) against the ingest side that stamps the scalar
+ * entity-key columns the per-entity rollup MVs group by
+ * (TelemetryEntity.extractEntities -> serviceEntityKey / hostEntityKey /
+ * k8sClusterEntityKey / containerEntityKey on MetricItemV3; the MVs copy
+ * the stamped column verbatim — `WHERE <key> != '' GROUP BY ... <key>`).
+ *
+ * Byte-equality between the two sides is what makes an MV lookup
+ * correct: a routed predicate whose key doesn't match the stamp finds
+ * nothing. This is the sibling of EntityKeySqlParity.test.ts (which pins
+ * keyForHost against ClickHouse's SQL SHA-256); the host vector below
+ * reuses that test's live-ClickHouse-verified literal so the ingest
+ * stamping stays anchored to the same externally computed value.
+ */
+describe("entity-MV routing keys — parity with ingest-stamped scalar entity keys", () => {
+  const projectId: string = "proj-123";
+
+  /*
+   * A resource carrying all four routable identities at once, with
+   * casing/whitespace drift to exercise canonicalization.
+   */
+  const attributes: Record<string, string> = {
+    "host.name": "Web-Server-01 ",
+    "k8s.cluster.name": "Prod-EU-1",
+    "container.id": "ABC123def456",
+    "service.name": "Checkout",
+  };
+
+  type FirstOfTypeFunction = (
+    entities: Array<ExtractedEntity>,
+    entityType: EntityType,
+  ) => string;
+
+  /*
+   * Mirrors OtelIngestBaseService.scalarEntityKeysFromEntities: the
+   * FIRST extracted entity of a type is what lands in the scalar column
+   * ('' when the type is absent).
+   */
+  const firstOfType: FirstOfTypeFunction = (
+    entities: Array<ExtractedEntity>,
+    entityType: EntityType,
+  ): string => {
+    return (
+      entities.find((entity: ExtractedEntity) => {
+        return entity.entityType === entityType;
+      })?.entityKey || ""
+    );
+  };
+
+  test("each routable read-side key byte-matches the stamped scalar column", () => {
+    const entities: Array<ExtractedEntity> = TelemetryEntity.extractEntities({
+      projectId,
+      attributes,
+    });
+
+    expect(firstOfType(entities, EntityType.Host)).toBe(
+      keyForHost(projectId, "Web-Server-01 "),
+    );
+    expect(firstOfType(entities, EntityType.KubernetesCluster)).toBe(
+      keyForKubernetesCluster(projectId, "Prod-EU-1"),
+    );
+    expect(firstOfType(entities, EntityType.Container)).toBe(
+      keyForContainer(projectId, "ABC123def456"),
+    );
+    expect(firstOfType(entities, EntityType.Service)).toBe(
+      keyForService(projectId, "Checkout"),
+    );
+  });
+
+  test("read-side keys canonicalize exactly like ingest (spelling drift lands on one rollup stream)", () => {
+    const drifted: Array<ExtractedEntity> = TelemetryEntity.extractEntities({
+      projectId,
+      attributes: {
+        "host.name": "web-server-01",
+        "k8s.cluster.name": " prod-eu-1 ",
+        "container.id": "abc123DEF456",
+        "service.name": "  checkout",
+      },
+    });
+
+    expect(firstOfType(drifted, EntityType.Host)).toBe(
+      keyForHost(projectId, "Web-Server-01 "),
+    );
+    expect(firstOfType(drifted, EntityType.KubernetesCluster)).toBe(
+      keyForKubernetesCluster(projectId, "Prod-EU-1"),
+    );
+    expect(firstOfType(drifted, EntityType.Container)).toBe(
+      keyForContainer(projectId, "ABC123def456"),
+    );
+    expect(firstOfType(drifted, EntityType.Service)).toBe(
+      keyForService(projectId, "Checkout"),
+    );
+  });
+
+  test("host stamping matches the live-ClickHouse-verified vector from EntityKeySqlParity", () => {
+    const entities: Array<ExtractedEntity> = TelemetryEntity.extractEntities({
+      projectId: "proj-123",
+      attributes: { "host.name": "Web-Server-01 " },
+    });
+
+    // Literal output of ClickHouse 25.7's SHA-256 SQL for this identity.
+    expect(firstOfType(entities, EntityType.Host)).toBe("dba90fb9cca1242e");
+  });
+
+  test("service.namespace forks the stamped key — the bare-name key MUST NOT be assumed (registry required)", () => {
+    const namespaced: Array<ExtractedEntity> = TelemetryEntity.extractEntities({
+      projectId,
+      attributes: {
+        "service.name": "checkout",
+        "service.namespace": "prod",
+      },
+    });
+
+    const stampedKey: string = firstOfType(namespaced, EntityType.Service);
+
+    // Ingest folds the namespace in ...
+    expect(stampedKey).toBe(keyForService(projectId, "checkout", "prod"));
+    /*
+     * ... so the bare-name derivation finds NOTHING for these rows. This
+     * is why MetricService resolves service key SETS from the registry
+     * and falls back to raw on a miss, instead of computing one key.
+     */
+    expect(stampedKey).not.toBe(keyForService(projectId, "checkout"));
+  });
+
+  test("a blank namespace is not identity-bearing on either side", () => {
+    const blankNamespace: Array<ExtractedEntity> =
+      TelemetryEntity.extractEntities({
+        projectId,
+        attributes: {
+          "service.name": "checkout",
+          "service.namespace": "   ",
+        },
+      });
+
+    expect(firstOfType(blankNamespace, EntityType.Service)).toBe(
+      keyForService(projectId, "checkout"),
+    );
+    expect(keyForService(projectId, "checkout", "   ")).toBe(
+      keyForService(projectId, "checkout"),
+    );
+  });
+
+  test("entityKeys membership (the entityScope raw predicate) contains every routable key", () => {
+    const membershipKeys: Array<string> = TelemetryEntity.extractEntityKeys({
+      projectId,
+      attributes,
+    });
+
+    for (const key of [
+      keyForHost(projectId, "Web-Server-01 "),
+      keyForKubernetesCluster(projectId, "Prod-EU-1"),
+      keyForContainer(projectId, "ABC123def456"),
+      keyForService(projectId, "Checkout"),
+    ]) {
+      expect(membershipKeys).toContain(key);
+    }
+  });
+});