@oneuptime/common 10.8.1 → 11.0.0

package/UI/Utils/TelemetryService.ts

@@ -7,11 +7,11 @@ import ServiceType from "../../Types/Telemetry/ServiceType";
  * Telemetry that arrives without an OTel service.name (and with no
  * host / docker / k8s resource signal) is not backed by a Service row.
  * The ingest path tags those analytics rows with the projectId in the
- * `serviceId` column under ServiceType.Unknown (see
+ * `primaryEntityId` column under ServiceType.Unknown (see
  * OtelIngestBaseService.resolveTelemetryResource). The read side has no
  * Service to resolve, so we represent that telemetry with a synthetic,
  * non-persisted Service whose id is the projectId — that way the
- * existing serviceId -> Service lookups in the telemetry views resolve
+ * existing primaryEntityId -> Service lookups in the telemetry views resolve
  * it to a labelled "Unknown Service" entry without any per-view special
  * casing. A real Service._id is never equal to a projectId, so this
  * never collides with a genuine service.
@@ -19,8 +19,8 @@ import ServiceType from "../../Types/Telemetry/ServiceType";
 export const UNKNOWN_SERVICE_NAME: string = "Unknown Service";
 
 /*
- * Result of resolving a telemetry row's polymorphic (serviceId,
- * serviceType) to something renderable. Either a Service (a real
+ * Result of resolving a telemetry row's polymorphic (primaryEntityId,
+ * primaryEntityType) to something renderable. Either a Service (a real
  * OpenTelemetry service, or the synthetic "Unknown Service" for the
  * unattributed bucket) — or a plain `label` for infrastructure resource
  * types (Host / DockerHost / KubernetesCluster) that have no Service row.
@@ -32,25 +32,25 @@ export interface ResolvedTelemetryResource {
 
 export default class TelemetryServiceUtil {
   /*
-   * True when a telemetry row's serviceId is the synthetic "Unknown
+   * True when a telemetry row's primaryEntityId is the synthetic "Unknown
    * Service" — i.e. it equals the projectId (ServiceType.Unknown). Used
    * to suppress navigation to a per-service detail page that does not
    * exist for unattributed telemetry.
    */
   public static isUnknownServiceId(
-    serviceId: ObjectID | string | null | undefined,
+    primaryEntityId: ObjectID | string | null | undefined,
     projectId: ObjectID | null | undefined,
   ): boolean {
-    if (!serviceId || !projectId) {
+    if (!primaryEntityId || !projectId) {
       return false;
     }
-    return serviceId.toString() === projectId.toString();
+    return primaryEntityId.toString() === projectId.toString();
   }
 
   /*
    * Build the synthetic Service used to render unattributed telemetry.
-   * Not persisted — id is the projectId so that serviceId -> Service
-   * lookups (which key on the analytics row's serviceId) resolve to it.
+   * Not persisted — id is the projectId so that primaryEntityId -> Service
+   * lookups (which key on the analytics row's primaryEntityId) resolve to it.
    */
   public static getUnknownService(projectId: ObjectID): Service {
     const service: Service = new Service();
@@ -61,7 +61,7 @@ export default class TelemetryServiceUtil {
   }
 
   /*
-   * Resolve a telemetry row's polymorphic (serviceId, serviceType) to a
+   * Resolve a telemetry row's polymorphic (primaryEntityId, primaryEntityType) to a
    * renderable resource, given the project's loaded Services. Replaces the
    * old server-side `service` ORM relation on TelemetryException: a real
    * Service resolves from the loaded list, the unattributed bucket resolves
@@ -70,12 +70,12 @@ export default class TelemetryServiceUtil {
    * them). Mirrors how the ClickHouse analytics rows are resolved.
    */
   public static resolveTelemetryResource(data: {
-    serviceId: ObjectID | string | null | undefined;
-    serviceType: ServiceType | string | null | undefined;
+    primaryEntityId: ObjectID | string | null | undefined;
+    primaryEntityType: ServiceType | string | null | undefined;
     services: Array<Service>;
     projectId: ObjectID | null | undefined;
   }): ResolvedTelemetryResource {
-    const serviceIdStr: string | undefined = data.serviceId?.toString();
+    const serviceIdStr: string | undefined = data.primaryEntityId?.toString();
 
     // Real Service (OpenTelemetry) — resolve from the loaded list.
     if (serviceIdStr) {
@@ -87,11 +87,11 @@ export default class TelemetryServiceUtil {
       }
     }
 
-    // Unattributed (Unknown) bucket — serviceId is the projectId.
+    // Unattributed (Unknown) bucket — primaryEntityId is the projectId.
     if (
       data.projectId &&
-      (data.serviceType === ServiceType.Unknown ||
-        this.isUnknownServiceId(data.serviceId, data.projectId))
+      (data.primaryEntityType === ServiceType.Unknown ||
+        this.isUnknownServiceId(data.primaryEntityId, data.projectId))
     ) {
       return { service: this.getUnknownService(data.projectId) };
     }
@@ -102,8 +102,8 @@ export default class TelemetryServiceUtil {
       [ServiceType.DockerHost]: "Docker host telemetry",
       [ServiceType.KubernetesCluster]: "Kubernetes telemetry",
     };
-    const label: string | undefined = data.serviceType
-      ? typeLabels[data.serviceType.toString()]
+    const label: string | undefined = data.primaryEntityType
+      ? typeLabels[data.primaryEntityType.toString()]
       : undefined;
     if (label) {
       return { label: label };
@@ -115,7 +115,7 @@ export default class TelemetryServiceUtil {
   /*
    * Append the synthetic "Unknown Service" to a loaded service list, but
    * only when the telemetry in view actually references it (some
-   * serviceId equals the projectId). Avoids showing an empty "Unknown
+   * primaryEntityId equals the projectId). Avoids showing an empty "Unknown
    * Service" entry for projects that always set service.name. Idempotent.
    */
   public static withUnknownServiceIfReferenced(data: {

package/Utils/Dashboard/Components/DashboardTraceChartComponent.ts

@@ -0,0 +1,134 @@
+import DashboardTraceChartComponent from "../../../Types/Dashboard/DashboardComponents/DashboardTraceChartComponent";
+import { ObjectType } from "../../../Types/JSON";
+import ObjectID from "../../../Types/ObjectID";
+import DashboardBaseComponentUtil from "./DashboardBaseComponent";
+import {
+  ComponentArgument,
+  ComponentArgumentSection,
+  ComponentInputType,
+} from "../../../Types/Dashboard/DashboardComponents/ComponentArgument";
+import DashboardComponentType from "../../../Types/Dashboard/DashboardComponentType";
+
+const DisplaySection: ComponentArgumentSection = {
+  name: "Display Options",
+  description: "Configure the widget title and metric",
+  order: 1,
+};
+
+const QuerySection: ComponentArgumentSection = {
+  name: "Query",
+  description: "Which spans to aggregate and how to split them",
+  order: 2,
+};
+
+export default class DashboardTraceChartComponentUtil extends DashboardBaseComponentUtil {
+  public static override getDefaultComponent(): DashboardTraceChartComponent {
+    return {
+      _type: ObjectType.DashboardComponent,
+      componentType: DashboardComponentType.TraceChart,
+      widthInDashboardUnits: 8,
+      heightInDashboardUnits: 5,
+      topInDashboardUnits: 0,
+      leftInDashboardUnits: 0,
+      componentId: ObjectID.generate(),
+      minHeightInDashboardUnits: 3,
+      minWidthInDashboardUnits: 6,
+      arguments: {
+        metric: "count",
+        topLimit: 10,
+      },
+    };
+  }
+
+  public static override getComponentConfigArguments(): Array<
+    ComponentArgument<DashboardTraceChartComponent>
+  > {
+    const componentArguments: Array<
+      ComponentArgument<DashboardTraceChartComponent>
+    > = [];
+
+    componentArguments.push({
+      name: "Title",
+      description: "Header shown above the chart",
+      required: false,
+      type: ComponentInputType.Text,
+      id: "title",
+      section: DisplaySection,
+    });
+
+    componentArguments.push({
+      name: "Metric",
+      description: "Span aggregation to chart over time",
+      required: false,
+      type: ComponentInputType.Dropdown,
+      id: "metric",
+      section: DisplaySection,
+      dropdownOptions: [
+        { label: "Request Count", value: "count" },
+        { label: "Error Count", value: "errorCount" },
+        { label: "Avg Response Time", value: "avgDuration" },
+        { label: "Median Response Time (P50)", value: "p50Duration" },
+        { label: "P90 Response Time", value: "p90Duration" },
+        { label: "P95 Response Time", value: "p95Duration" },
+        { label: "P99 Response Time", value: "p99Duration" },
+        { label: "Min Response Time", value: "minDuration" },
+        { label: "Max Response Time", value: "maxDuration" },
+      ],
+    });
+
+    componentArguments.push({
+      name: "Span Name Contains",
+      description:
+        "Only include spans whose name contains this text (e.g. /Shipment/ShipShipment)",
+      required: false,
+      type: ComponentInputType.Text,
+      id: "spanNameContains",
+      placeholder: "/Shipment/ShipShipment",
+      section: QuerySection,
+    });
+
+    componentArguments.push({
+      name: "Attribute Filters",
+      description:
+        "Attribute equality filters, ANDed — key=value pairs separated by semicolons (e.g. url.host=torginol.starship.online; http.method=POST)",
+      required: false,
+      type: ComponentInputType.Text,
+      id: "attributeFilters",
+      placeholder: "url.host=torginol.starship.online",
+      section: QuerySection,
+    });
+
+    componentArguments.push({
+      name: "Split By",
+      description:
+        "Optional dimension — a span attribute key (e.g. url.host, resource.service.instance.id) or one of: name, primaryEntityId, statusCode, kind. One series per value.",
+      required: false,
+      type: ComponentInputType.Text,
+      id: "groupByAttribute",
+      placeholder: "url.host",
+      section: QuerySection,
+    });
+
+    componentArguments.push({
+      name: "Top Series",
+      description: "Cap on the number of series when split (default 10)",
+      required: false,
+      type: ComponentInputType.Number,
+      id: "topLimit",
+      placeholder: "10",
+      section: QuerySection,
+    });
+
+    componentArguments.push({
+      name: "Include Child Spans",
+      description:
+        "Count every span instead of root spans only (the traces explorer defaults to root spans)",
+      required: false,
+      type: ComponentInputType.Boolean,
+      id: "includeChildSpans",
+      section: QuerySection,
+    });
+
+    return componentArguments;
+  }
+}

package/Utils/Dashboard/Components/Index.ts

@@ -24,6 +24,7 @@ import DashboardLogStreamComponentUtil from "./DashboardLogStreamComponent";
 import DashboardMonitorListComponentUtil from "./DashboardMonitorListComponent";
 import DashboardTableComponentUtil from "./DashboardTableComponent";
 import DashboardTextComponentUtil from "./DashboardTextComponent";
+import DashboardTraceChartComponentUtil from "./DashboardTraceChartComponent";
 import DashboardTraceListComponentUtil from "./DashboardTraceListComponent";
 import DashboardValueComponentUtil from "./DashboardValueComponent";
 
@@ -73,6 +74,12 @@ export default class DashboardComponentsUtil {
       >;
     }
 
+    if (dashboardComponentType === DashboardComponentType.TraceChart) {
+      return DashboardTraceChartComponentUtil.getComponentConfigArguments() as Array<
+        ComponentArgument<DashboardBaseComponent>
+      >;
+    }
+
     if (dashboardComponentType === DashboardComponentType.IncidentList) {
       return DashboardIncidentListComponentUtil.getComponentConfigArguments() as Array<
         ComponentArgument<DashboardBaseComponent>

package/Utils/Telemetry/EntityKey.ts

@@ -0,0 +1,151 @@
+import Crypto from "../Crypto";
+import Dictionary from "../../Types/Dictionary";
+import EntityType from "../../Types/Telemetry/EntityType";
+
+/*
+ * Isomorphic OpenTelemetry entity-key computation — the single source of
+ * truth shared by ingest (server, stamping `entityKeys`) and reads
+ * (server or browser, building `has(entityKeys, :key)` predicates).
+ * Hashing goes through an injectable SHA-256 provider: the default is
+ * `Common/Utils/Crypto` (crypto-js, pure JS) so this module works in the
+ * browser, and the server swaps in node:crypto for the ingest hot path
+ * (see TelemetryEntity.ts). Any provider MUST produce the same
+ * lowercase-hex SHA-256 — a hard requirement: a read-side key that
+ * doesn't byte-match the ingest-side stamp finds nothing.
+ *
+ * See Internal/Docs/OpenTelemetryEntities.md.
+ */
+
+/** Canonical identity-value form: trimmed + lowercased. */
+export function canonicalizeEntityValue(value: string | undefined): string {
+  return String(value === undefined || value === null ? "" : value)
+    .trim()
+    .toLowerCase();
+}
+
+export type Sha256HexProvider = (input: string) => string;
+
+let sha256HexProvider: Sha256HexProvider = (input: string): string => {
+  return Crypto.getSha256Hash(input);
+};
+
+/**
+ * Swap the SHA-256 implementation (e.g. node:crypto on the server). The
+ * provider must return the full lowercase-hex digest, byte-identical to
+ * the crypto-js default, or ingest-stamped and read-side keys fork.
+ */
+export function setSha256Provider(provider: Sha256HexProvider): void {
+  sha256HexProvider = provider;
+}
+
+/*
+ * '|' separates preimage segments and '=' separates key from value, so
+ * both — and the escape character itself — are backslash-escaped inside
+ * keys and values. This keeps the preimage injective (a value like
+ * `a|service.namespace=b` cannot collide with a two-attribute identity)
+ * while leaving values WITHOUT these characters byte-identical to the
+ * historical preimage, so already-stamped keys for normal data are
+ * unchanged.
+ */
+function escapeIdentityToken(token: string): string {
+  return token.replace(/([\\|=])/g, "\\$1");
+}
+
+/**
+ * Stable 16-hex-char identity key for an entity. Pure: same inputs → same
+ * key. Keys are sorted so attribute order is irrelevant; values are
+ * canonicalized so casing/whitespace drift does not fork identity;
+ * projectId is folded in so keys are tenant-unique (and a
+ * `has(entityKeys, key)` predicate is implicitly project-scoped).
+ */
+export function computeEntityKey(data: {
+  projectId: string;
+  entityType: EntityType;
+  identifyingAttributes: Dictionary<string>;
+}): string {
+  const keys: Array<string> = Object.keys(
+    data.identifyingAttributes || {},
+  ).sort();
+
+  const parts: Array<string> = [];
+  for (const key of keys) {
+    parts.push(
+      `${escapeIdentityToken(key)}=${escapeIdentityToken(
+        canonicalizeEntityValue(data.identifyingAttributes[key]),
+      )}`,
+    );
+  }
+
+  const preimage: string = `${data.projectId}|${data.entityType}|${parts.join(
+    "|",
+  )}`;
+
+  return sha256HexProvider(preimage).slice(0, 16);
+}
+
+/*
+ * ---- Read-side helpers ---------------------------------------------------
+ *
+ * Given a OneUptime resource's identifying value, compute the entity key
+ * to query `has(entityKeys, :key)`. Each MUST mirror the corresponding
+ * ingest-side resolver in `TelemetryEntity.extractEntities` exactly.
+ */
+
+/**
+ * `host.name` is the host identity (matches the Host row's `hostIdentifier`,
+ * which is the canonicalized host.name). Pass `Host.hostIdentifier`.
+ */
+export function keyForHost(projectId: string, hostIdentifier: string): string {
+  return computeEntityKey({
+    projectId,
+    entityType: EntityType.Host,
+    identifyingAttributes: { "host.name": hostIdentifier },
+  });
+}
+
+/**
+ * `service.name` (+ `service.namespace` when the resource carries one) is
+ * the service identity — the ingest resolver folds the namespace into the
+ * key, so a namespaced service is only matchable when the same namespace
+ * is passed here. Pass `Service.name` (+ the namespace if known).
+ */
+export function keyForService(
+  projectId: string,
+  serviceName: string,
+  serviceNamespace?: string | undefined,
+): string {
+  const identifyingAttributes: Dictionary<string> = {
+    "service.name": serviceName,
+  };
+
+  /*
+   * Mirrors the resolver's addIfPresent: blank/whitespace-only namespaces
+   * are not identity-bearing.
+   */
+  if (serviceNamespace && serviceNamespace.trim().length > 0) {
+    identifyingAttributes["service.namespace"] = serviceNamespace;
+  }
+
+  return computeEntityKey({
+    projectId,
+    entityType: EntityType.Service,
+    identifyingAttributes,
+  });
+}
+
+/**
+ * `k8s.cluster.name` is the cluster identity (matches the KubernetesCluster
+ * row's `clusterIdentifier`; the ingest resolver is name-only — see
+ * `TelemetryEntity.k8sClusterIdentity`). Pass
+ * `KubernetesCluster.clusterIdentifier`.
+ */
+export function keyForKubernetesCluster(
+  projectId: string,
+  clusterIdentifier: string,
+): string {
+  return computeEntityKey({
+    projectId,
+    entityType: EntityType.KubernetesCluster,
+    identifyingAttributes: { "k8s.cluster.name": clusterIdentifier },
+  });
+}

package/Utils/Telemetry/EntityRelationship.ts

@@ -0,0 +1,113 @@
+import EntityRelationshipType from "../../Types/Telemetry/EntityRelationshipType";
+import EntityType from "../../Types/Telemetry/EntityType";
+
+/*
+ * Co-occurrence relationship inference (phase 5 of the entity model —
+ * Internal/Docs/OpenTelemetryEntities.md §4). Every ingest batch yields an
+ * entity set; the directed pairs that co-occur in one resource are, by
+ * construction, related. `relType` is inferred from the *type* pair, not
+ * any standardized wire signal (the OTel relationship taxonomy is
+ * undefined), giving an infrastructure topology graph for free. Pure +
+ * synchronous: operates on already-computed entity keys, no DB round trip.
+ */
+
+/** A single directed relationship edge between two entities. */
+export interface EntityRelationshipEdge {
+  fromEntityKey: string;
+  toEntityKey: string;
+  relationshipType: EntityRelationshipType;
+}
+
+/*
+ * Directed rules: a `from`-type that co-occurs with a `to`-type implies the
+ * given relationship. Only the meaningful direction has a rule (e.g. pod →
+ * cluster is `member-of`; cluster → pod yields nothing), so iterating all
+ * ordered pairs and keeping the non-null results produces a correctly
+ * directed edge set without double-counting. Extend as new entity types
+ * graduate from membership-only to first-class.
+ *
+ * `depends-on` is deliberately absent: a caller service and its callee
+ * never share one resource, so it cannot be co-occurrence-inferred. Those
+ * edges are derived from cross-service parent/child span pairs by the
+ * TelemetryEntity:ComputeServiceDependencies worker cron.
+ */
+const RULES: Record<string, EntityRelationshipType> = {
+  [`${EntityType.ServiceInstance}|${EntityType.Service}`]:
+    EntityRelationshipType.InstanceOf,
+  [`${EntityType.Service}|${EntityType.Host}`]: EntityRelationshipType.HostedOn,
+  [`${EntityType.Service}|${EntityType.KubernetesPod}`]:
+    EntityRelationshipType.RunsOn,
+  [`${EntityType.Container}|${EntityType.KubernetesPod}`]:
+    EntityRelationshipType.PartOf,
+  [`${EntityType.Container}|${EntityType.Host}`]: EntityRelationshipType.PartOf,
+  [`${EntityType.Process}|${EntityType.Container}`]:
+    EntityRelationshipType.PartOf,
+  [`${EntityType.Process}|${EntityType.Host}`]: EntityRelationshipType.RunsOn,
+  [`${EntityType.KubernetesPod}|${EntityType.KubernetesNode}`]:
+    EntityRelationshipType.RunsOn,
+  [`${EntityType.KubernetesPod}|${EntityType.KubernetesNamespace}`]:
+    EntityRelationshipType.MemberOf,
+  [`${EntityType.KubernetesPod}|${EntityType.KubernetesCluster}`]:
+    EntityRelationshipType.MemberOf,
+  [`${EntityType.KubernetesNode}|${EntityType.KubernetesCluster}`]:
+    EntityRelationshipType.MemberOf,
+  [`${EntityType.KubernetesNamespace}|${EntityType.KubernetesCluster}`]:
+    EntityRelationshipType.MemberOf,
+  [`${EntityType.KubernetesDeployment}|${EntityType.KubernetesNamespace}`]:
+    EntityRelationshipType.MemberOf,
+  [`${EntityType.KubernetesDeployment}|${EntityType.KubernetesCluster}`]:
+    EntityRelationshipType.MemberOf,
+};
+
+/** The relationship `fromType` → `toType` implies, or null if none. */
+export function inferRelationshipType(
+  fromType: EntityType,
+  toType: EntityType,
+): EntityRelationshipType | null {
+  return RULES[`${fromType}|${toType}`] || null;
+}
+
+/**
+ * Derive every directed relationship edge implied by an entity set (one
+ * resource batch). Deduped; self-pairs and same-key pairs skipped.
+ */
+export function deriveRelationships(
+  entities: Array<{ entityType: EntityType; entityKey: string }>,
+): Array<EntityRelationshipEdge> {
+  const edges: Array<EntityRelationshipEdge> = [];
+  const seen: Set<string> = new Set<string>();
+
+  for (let i: number = 0; i < entities.length; i++) {
+    for (let j: number = 0; j < entities.length; j++) {
+      if (i === j) {
+        continue;
+      }
+      const from: { entityType: EntityType; entityKey: string } = entities[i]!;
+      const to: { entityType: EntityType; entityKey: string } = entities[j]!;
+
+      if (from.entityKey === to.entityKey) {
+        continue;
+      }
+
+      const relationshipType: EntityRelationshipType | null =
+        inferRelationshipType(from.entityType, to.entityType);
+      if (!relationshipType) {
+        continue;
+      }
+
+      const dedupeKey: string = `${from.entityKey}|${to.entityKey}|${relationshipType}`;
+      if (seen.has(dedupeKey)) {
+        continue;
+      }
+      seen.add(dedupeKey);
+
+      edges.push({
+        fromEntityKey: from.entityKey,
+        toEntityKey: to.entityKey,
+        relationshipType,
+      });
+    }
+  }
+
+  return edges;
+}

package/Utils/Traces/CriticalPath.ts

@@ -9,7 +9,7 @@ export interface SpanData {
   startTimeUnixNano: number;
   endTimeUnixNano: number;
   durationUnixNano: number;
-  serviceId: string | undefined;
+  primaryEntityId: string | undefined;
   name: string | undefined;
 }
 
@@ -28,7 +28,7 @@ export interface CriticalPathResult {
 }
 
 export interface ServiceBreakdown {
-  serviceId: string;
+  primaryEntityId: string;
   totalDurationUnixNano: number;
   selfTimeUnixNano: number;
   spanCount: number;
@@ -308,12 +308,12 @@ export default class CriticalPathUtil {
     > = new Map();
 
     for (const span of spans) {
-      const serviceId: string = span.serviceId || "unknown";
+      const primaryEntityId: string = span.primaryEntityId || "unknown";
       const entry: {
         totalDuration: number;
         selfTime: number;
         spanCount: number;
-      } = serviceMap.get(serviceId) || {
+      } = serviceMap.get(primaryEntityId) || {
         totalDuration: 0,
         selfTime: 0,
         spanCount: 0,
@@ -323,13 +323,13 @@ export default class CriticalPathUtil {
       const selfTime: SpanSelfTime | undefined = selfTimes.get(span.spanId);
       entry.selfTime += selfTime ? selfTime.selfTimeUnixNano : 0;
       entry.spanCount += 1;
-      serviceMap.set(serviceId, entry);
+      serviceMap.set(primaryEntityId, entry);
     }
 
     const result: ServiceBreakdown[] = [];
-    for (const [serviceId, data] of serviceMap.entries()) {
+    for (const [primaryEntityId, data] of serviceMap.entries()) {
       result.push({
-        serviceId,
+        primaryEntityId,
         totalDurationUnixNano: data.totalDuration,
         selfTimeUnixNano: data.selfTime,
         spanCount: data.spanCount,

package/Utils/UUID.ts

@@ -1,4 +1,61 @@
 export default class UUID {
+  /**
+   * RFC 9562 UUIDv7: 48-bit big-endian unix-millisecond timestamp prefix,
+   * then version/variant bits, then 74 random bits. Ids generated later
+   * sort lexicographically after ids generated earlier (same-millisecond
+   * ids tie on the prefix and order randomly). Used for analytics-row
+   * `_id`s: time-ordered ids cluster inserts and compress far better in
+   * ClickHouse than fully-random v4 UUIDs. Postgres ids keep using
+   * `generate()` (random v4) — do not switch those.
+   */
+  public static generateTimeOrdered(): string {
+    const bytes: Uint8Array = new Uint8Array(16);
+
+    const cryptoObj: Crypto | undefined = globalThis.crypto;
+    if (cryptoObj && typeof cryptoObj.getRandomValues === "function") {
+      cryptoObj.getRandomValues(bytes);
+    } else {
+      // Non-cryptographic fallback — uniqueness, not secrecy, is the goal.
+      for (let i: number = 0; i < bytes.length; i++) {
+        bytes[i] = (Math.random() * 256) | 0;
+      }
+    }
+
+    /*
+     * 48-bit timestamp written big-endian into bytes 0..5. JS bitwise
+     * operators truncate to 32 bits, so the bytes are peeled off with
+     * division instead of shifts.
+     */
+    let timestamp: number = Date.now();
+    for (let i: number = 5; i >= 0; i--) {
+      bytes[i] = timestamp % 256;
+      timestamp = Math.floor(timestamp / 256);
+    }
+
+    // Version 7 in the high nibble of byte 6; RFC 4122 variant on byte 8.
+    bytes[6] = ((bytes[6] as number) & 0x0f) | 0x70;
+    bytes[8] = ((bytes[8] as number) & 0x3f) | 0x80;
+
+    return UUID.formatBytes(bytes);
+  }
+
+  private static formatBytes(bytes: Uint8Array): string {
+    const hex: string = Array.from(bytes, (b: number) => {
+      return b.toString(16).padStart(2, "0");
+    }).join("");
+    return (
+      hex.slice(0, 8) +
+      "-" +
+      hex.slice(8, 12) +
+      "-" +
+      hex.slice(12, 16) +
+      "-" +
+      hex.slice(16, 20) +
+      "-" +
+      hex.slice(20, 32)
+    );
+  }
+
   public static generate(): string {
     const cryptoObj: Crypto | undefined = globalThis.crypto;