@oneuptime/common 10.8.2 → 11.0.0

package/Server/Services/ServiceService.ts

@@ -127,6 +127,7 @@ export class Service extends DatabaseService<Model> {
       serviceNamespace?: string | undefined;
       runtimeName?: string | undefined;
       runtimeVersion?: string | undefined;
+      telemetrySdkLanguage?: string | undefined;
       cloudProvider?: string | undefined;
       cloudPlatform?: string | undefined;
       cloudRegion?: string | undefined;
@@ -181,6 +182,9 @@ export class Service extends DatabaseService<Model> {
     if (extra?.runtimeVersion) {
       data.runtimeVersion = extra.runtimeVersion;
     }
+    if (extra?.telemetrySdkLanguage) {
+      data.telemetrySdkLanguage = extra.telemetrySdkLanguage;
+    }
     if (extra?.cloudProvider) {
       data.cloudProvider = extra.cloudProvider;
     }
@@ -209,6 +213,7 @@ export class Service extends DatabaseService<Model> {
     serviceNamespace?: string | undefined;
     runtimeName?: string | undefined;
     runtimeVersion?: string | undefined;
+    telemetrySdkLanguage?: string | undefined;
     cloudProvider?: string | undefined;
     cloudPlatform?: string | undefined;
     cloudRegion?: string | undefined;
@@ -220,6 +225,7 @@ export class Service extends DatabaseService<Model> {
       serviceNamespace: extra?.serviceNamespace ?? null,
       runtimeName: extra?.runtimeName ?? null,
       runtimeVersion: extra?.runtimeVersion ?? null,
+      telemetrySdkLanguage: extra?.telemetrySdkLanguage ?? null,
       cloudProvider: extra?.cloudProvider ?? null,
       cloudPlatform: extra?.cloudPlatform ?? null,
       cloudRegion: extra?.cloudRegion ?? null,

package/Server/Services/SpanService.ts

@@ -2,8 +2,14 @@ import ClickhouseDatabase from "../Infrastructure/ClickhouseDatabase";
 import AnalyticsDatabaseService from "./AnalyticsDatabaseService";
 import Span from "../../Models/AnalyticsModels/Span";
 import CountBy from "../Types/AnalyticsDatabase/CountBy";
+import AggregateBy, {
+  AggregateUtil,
+} from "../Types/AnalyticsDatabase/AggregateBy";
 import { SQL, Statement } from "../Utils/AnalyticsDatabase/Statement";
+import { getQuerySettings } from "../Utils/AnalyticsDatabase/QuerySettingsHelper";
 import TableColumnType from "../../Types/AnalyticsDatabase/TableColumnType";
+import AggregationType from "../../Types/BaseDatabase/AggregationType";
+import SortOrder from "../../Types/BaseDatabase/SortOrder";
 import InBetween from "../../Types/BaseDatabase/InBetween";
 import Includes from "../../Types/BaseDatabase/Includes";
 import ObjectID from "../../Types/ObjectID";
@@ -19,7 +25,7 @@ const PROJECTION_ELIGIBLE_KEYS: Set<string> = new Set([
   "projectId",
   "startTime",
   "isRootSpan",
-  "serviceId",
+  "primaryEntityId",
   "statusCode",
 ]);
 
@@ -48,9 +54,9 @@ export class SpanService extends AnalyticsDatabaseService<Span> {
   /**
    * Override the count statement to route eligible queries through the
    * proj_hist_by_minute projection. The projection is keyed on
-   * (projectId, toStartOfMinute(startTime), serviceId, statusCode, isRootSpan)
-   * so its WHERE clause must reference the projection's exact expressions —
-   * filtering on raw `startTime` won't trigger projection use.
+   * (projectId, toStartOfMinute(startTime), primaryEntityId, statusCode,
+   * isRootSpan) so its WHERE clause must reference the projection's exact
+   * expressions — filtering on raw `startTime` won't trigger projection use.
    *
    * Trade-off: time bounds get rounded to the minute, so the count can be
    * inflated by spans that started in the same minute as the boundary. For
@@ -132,23 +138,23 @@ export class SpanService extends AnalyticsDatabaseService<Span> {
       );
     }
 
-    const serviceIdValue: unknown = query["serviceId"];
-    if (serviceIdValue instanceof ObjectID) {
+    const primaryEntityIdValue: unknown = query["primaryEntityId"];
+    if (primaryEntityIdValue instanceof ObjectID) {
       statement.append(
-        SQL` AND serviceId = ${{
+        SQL` AND primaryEntityId = ${{
           type: TableColumnType.ObjectID,
-          value: serviceIdValue,
+          value: primaryEntityIdValue,
         }}`,
       );
-    } else if (serviceIdValue instanceof Includes) {
+    } else if (primaryEntityIdValue instanceof Includes) {
       statement.append(
-        SQL` AND serviceId IN (${{
+        SQL` AND primaryEntityId IN (${{
           type: TableColumnType.ObjectID,
-          value: serviceIdValue,
+          value: primaryEntityIdValue,
         }})`,
       );
-    } else if (serviceIdValue !== undefined) {
-      // Unrecognized serviceId form — let the generic path handle it.
+    } else if (primaryEntityIdValue !== undefined) {
+      // Unrecognized primaryEntityId form — let the generic path handle it.
       return null;
     }
 
@@ -177,11 +183,265 @@ export class SpanService extends AnalyticsDatabaseService<Span> {
      * in depth — projection scans should complete in <1s.
      */
     statement.append(
-      " SETTINGS optimize_use_projections = 1, max_execution_time = 45, timeout_overflow_mode = 'break'",
+      getQuerySettings({
+        maxExecutionTimeInSeconds: 45,
+        timeoutOverflowMode: "break",
+        additionalSettings: { optimize_use_projections: 1 },
+      }),
     );
 
     return statement;
   }
+
+  /**
+   * Route eligible duration aggregations through the proj_agg_by_service
+   * projection (projectId, primaryEntityId, toStartOfMinute(startTime) ->
+   * count() / avg(durationUnixNano) / quantile(0.99)(durationUnixNano)).
+   * The projection stores aggregate-function STATES, so re-grouping its
+   * minute rows into coarser buckets merges those states — results are
+   * identical to scanning the raw table, at a fraction of the read
+   * (verified on dev with EXPLAIN indexes=1: ReadFromMergeTree
+   * (proj_agg_by_service), 9/2136 granules for a full-day window).
+   *
+   * Count queries may additionally filter on statusCode / isRootSpan: the
+   * optimizer then serves them from proj_hist_by_minute, whose key is
+   * (projectId, minute, primaryEntityId, statusCode, isRootSpan). This is
+   * the error-rate series on the Service / RUM / Serverless overview
+   * pages. Those filters stay rejected for Avg/P99 — proj_agg_by_service
+   * cannot evaluate them, and quantile states for different levels do not
+   * merge.
+   *
+   * Two things are load-bearing for the optimizer to pick the projection:
+   *   1. The time predicates AND the bucket expression must be written
+   *      over toStartOfMinute(startTime) — the projection's key
+   *      expression — never raw startTime.
+   *   2. The aggregate must byte-match a stored expression: count() (NOT
+   *      count(durationUnixNano) — equivalent here since the column is
+   *      non-nullable), avg(durationUnixNano) or
+   *      quantile(0.99)(durationUnixNano).
+   *
+   * Trade-off (same as the count override): window edges round to the
+   * minute, so the boundary buckets may include spans from the partial
+   * boundary minute.
+   */
+  public override toAggregateStatement(aggregateBy: AggregateBy<Span>): {
+    statement: Statement;
+    columns: Array<string>;
+  } {
+    const projectionStatement: {
+      statement: Statement;
+      columns: Array<string>;
+    } | null = this.tryBuildProjectionAggregateStatement(aggregateBy);
+    if (projectionStatement) {
+      return projectionStatement;
+    }
+    return super.toAggregateStatement(aggregateBy);
+  }
+
+  private tryBuildProjectionAggregateStatement(
+    aggregateBy: AggregateBy<Span>,
+  ): { statement: Statement; columns: Array<string> } | null {
+    if (aggregateBy.aggregateColumnName?.toString() !== "durationUnixNano") {
+      return null;
+    }
+
+    /*
+     * Only the aggregates whose states the projection stores. P95 etc.
+     * must fall back: the projection has no quantile(0.95) state and
+     * quantile states for different levels do not merge into each other.
+     */
+    const aggregateExpressionByType: Partial<Record<AggregationType, string>> =
+      {
+        [AggregationType.Count]: "count()",
+        [AggregationType.Avg]: "avg(durationUnixNano)",
+        [AggregationType.P99]: "quantile(0.99)(durationUnixNano)",
+      };
+    const aggregateExpression: string | undefined =
+      aggregateExpressionByType[aggregateBy.aggregationType];
+    if (!aggregateExpression) {
+      return null;
+    }
+
+    if (
+      aggregateBy.aggregationTimestampColumnName?.toString() !== "startTime"
+    ) {
+      return null;
+    }
+
+    if (aggregateBy.groupBy && Object.keys(aggregateBy.groupBy).length > 0) {
+      // Extra GROUP BY dimensions aren't all projection columns; fall back.
+      return null;
+    }
+
+    if (!aggregateBy.startTimestamp || !aggregateBy.endTimestamp) {
+      // Needed to derive the bucket interval (mirrors the generic path).
+      return null;
+    }
+
+    const query: Record<string, unknown> = (aggregateBy.query ||
+      {}) as unknown as Record<string, unknown>;
+
+    /*
+     * Filters the projections can evaluate. Avg/P99 are served by
+     * proj_agg_by_service, which is keyed only on (projectId,
+     * primaryEntityId, minute) — a statusCode/isRootSpan filter must bail.
+     * Count is also served by proj_hist_by_minute, whose key includes
+     * statusCode and isRootSpan, so those filters stay projection-servable
+     * for Count (this is the error-rate series on the overview pages).
+     */
+    const eligibleKeys: Array<string> = [
+      "projectId",
+      "startTime",
+      "primaryEntityId",
+    ];
+    if (aggregateBy.aggregationType === AggregationType.Count) {
+      eligibleKeys.push("statusCode", "isRootSpan");
+    }
+
+    // Bail out on any filter the projections cannot evaluate.
+    for (const key of Object.keys(query)) {
+      if (!eligibleKeys.includes(key)) {
+        return null;
+      }
+    }
+
+    const projectId: ObjectID | undefined = query["projectId"] as
+      | ObjectID
+      | undefined;
+    const startTimeFilter: unknown = query["startTime"];
+
+    if (!projectId || !(startTimeFilter instanceof InBetween)) {
+      return null;
+    }
+
+    const startValue: Date | null = SpanService.coerceToDate(
+      startTimeFilter.startValue,
+    );
+    const endValue: Date | null = SpanService.coerceToDate(
+      startTimeFilter.endValue,
+    );
+    if (!startValue || !endValue) {
+      return null;
+    }
+
+    if (!this.database) {
+      this.useDefaultDatabase();
+    }
+    const databaseName: string = this.database.getDatasourceOptions().database!;
+
+    const aggregationInterval: string = AggregateUtil.getAggregationInterval({
+      startDate: aggregateBy.startTimestamp,
+      endDate: aggregateBy.endTimestamp,
+    }).toLowerCase();
+
+    /*
+     * Bucket expression derived from the projection key: for the minute
+     * interval date_trunc is a no-op, for coarser intervals truncating
+     * the minute equals truncating the raw timestamp. Aliased to the
+     * timestamp column name so the generic result parsing applies.
+     */
+    const statement: Statement = new Statement();
+    statement.append(
+      `SELECT ${aggregateExpression} as durationUnixNano, date_trunc('${aggregationInterval}', toStartOfMinute(startTime)) as startTime`,
+    );
+    statement.append(
+      SQL` FROM ${databaseName}.${this.model.tableName} WHERE projectId = ${{
+        type: TableColumnType.ObjectID,
+        value: projectId,
+      }} AND toStartOfMinute(startTime) >= toStartOfMinute(${{
+        type: TableColumnType.Date,
+        value: startValue,
+      }}) AND toStartOfMinute(startTime) <= toStartOfMinute(${{
+        type: TableColumnType.Date,
+        value: endValue,
+      }})`,
+    );
+
+    const primaryEntityIdValue: unknown = query["primaryEntityId"];
+    if (primaryEntityIdValue instanceof ObjectID) {
+      statement.append(
+        SQL` AND primaryEntityId = ${{
+          type: TableColumnType.ObjectID,
+          value: primaryEntityIdValue,
+        }}`,
+      );
+    } else if (primaryEntityIdValue instanceof Includes) {
+      statement.append(
+        SQL` AND primaryEntityId IN (${{
+          type: TableColumnType.ObjectID,
+          value: primaryEntityIdValue,
+        }})`,
+      );
+    } else if (primaryEntityIdValue !== undefined) {
+      return null;
+    }
+
+    /*
+     * Only reachable for Count (the whitelist above rejects these keys for
+     * Avg/P99). Predicate translation mirrors
+     * tryBuildProjectionCountStatement: scalar = equality, Includes = IN,
+     * anything else = bail to the generic path.
+     */
+    if (query["isRootSpan"] !== undefined) {
+      statement.append(
+        SQL` AND isRootSpan = ${{
+          type: TableColumnType.Boolean,
+          value: Boolean(query["isRootSpan"]),
+        }}`,
+      );
+    }
+
+    const statusCodeValue: unknown = query["statusCode"];
+    if (typeof statusCodeValue === "number") {
+      statement.append(
+        SQL` AND statusCode = ${{
+          type: TableColumnType.Number,
+          value: statusCodeValue,
+        }}`,
+      );
+    } else if (statusCodeValue instanceof Includes) {
+      statement.append(
+        SQL` AND statusCode IN (${{
+          type: TableColumnType.Number,
+          value: statusCodeValue,
+        }})`,
+      );
+    } else if (statusCodeValue !== undefined) {
+      return null;
+    }
+
+    statement.append(" GROUP BY startTime");
+
+    const sortOrder: SortOrder | undefined = aggregateBy.sort
+      ? (Object.values(aggregateBy.sort)[0] as SortOrder | undefined)
+      : undefined;
+    statement.append(
+      ` ORDER BY startTime ${sortOrder === SortOrder.Ascending ? "ASC" : "DESC"}`,
+    );
+
+    statement.append(
+      SQL` LIMIT ${{
+        type: TableColumnType.Number,
+        value: Number(aggregateBy.limit) || 10,
+      }} OFFSET ${{
+        type: TableColumnType.Number,
+        value: Number(aggregateBy.skip) || 0,
+      }}`,
+    );
+
+    statement.append(
+      getQuerySettings({
+        maxExecutionTimeInSeconds: 45,
+        timeoutOverflowMode: "break",
+        additionalSettings: { optimize_use_projections: 1 },
+      }),
+    );
+
+    return {
+      statement,
+      columns: ["durationUnixNano", "startTime"],
+    };
+  }
 }
 
 export default new SpanService();

package/Server/Services/TelemetryEntityRelationshipService.ts

@@ -0,0 +1,71 @@
+import DatabaseService from "./DatabaseService";
+import Model from "../../Models/DatabaseModels/TelemetryEntityRelationship";
+import ObjectID from "../../Types/ObjectID";
+import OneUptimeDate from "../../Types/Date";
+import logger from "../Utils/Logger";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import { EntityRelationshipEdge } from "../../Utils/Telemetry/EntityRelationship";
+import { reconcileByNaturalKey } from "../Utils/Telemetry/EntityRegistry";
+
+export class TelemetryEntityRelationshipService extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  /**
+   * Forward-only topology reconciliation: upsert a row per directed edge and
+   * bump `lastSeenAt`. Resilient — a topology-graph failure must never break
+   * signal ingest, so every error is swallowed (logged). Callers throttle
+   * this (see `reconcileEntityRegistryThrottled` in
+   * `Common/Server/Utils/Telemetry/EntityRegistry`), and only pass edges
+   * among registry-promoted entities so every edge endpoint has a row.
+   */
+  @CaptureSpan()
+  public async reconcileRelationships(data: {
+    projectId: ObjectID;
+    edges: Array<EntityRelationshipEdge>;
+  }): Promise<void> {
+    for (const edge of data.edges) {
+      try {
+        await this.upsertRelationship({ projectId: data.projectId, edge });
+      } catch (err) {
+        logger.error(
+          `TelemetryEntityRelationshipService: failed to upsert edge ${edge.fromEntityKey}-[${edge.relationshipType}]->${edge.toEntityKey}:`,
+        );
+        logger.error(err as Error);
+      }
+    }
+  }
+
+  private async upsertRelationship(data: {
+    projectId: ObjectID;
+    edge: EntityRelationshipEdge;
+  }): Promise<void> {
+    const { projectId, edge } = data;
+    const now: Date = OneUptimeDate.getCurrentDate();
+
+    await reconcileByNaturalKey({
+      service: this,
+      query: {
+        projectId,
+        fromEntityKey: edge.fromEntityKey,
+        toEntityKey: edge.toEntityKey,
+        relationshipType: edge.relationshipType,
+      },
+      lastSeenAt: now,
+      describe: `edge ${edge.fromEntityKey}-[${edge.relationshipType}]->${edge.toEntityKey}`,
+      buildModel: () => {
+        const model: Model = new Model();
+        model.projectId = projectId;
+        model.fromEntityKey = edge.fromEntityKey;
+        model.toEntityKey = edge.toEntityKey;
+        model.relationshipType = edge.relationshipType;
+        model.firstSeenAt = now;
+        model.lastSeenAt = now;
+        return model;
+      },
+    });
+  }
+}
+
+export default new TelemetryEntityRelationshipService();

package/Server/Services/TelemetryEntityService.ts

@@ -0,0 +1,246 @@
+import DatabaseService from "./DatabaseService";
+import Model from "../../Models/DatabaseModels/TelemetryEntity";
+import ObjectID from "../../Types/ObjectID";
+import OneUptimeDate from "../../Types/Date";
+import ColumnLength from "../../Types/Database/ColumnLength";
+import QueryDeepPartialEntity from "../../Types/Database/PartialEntity";
+import { JSONObject } from "../../Types/JSON";
+import EntityType from "../../Types/Telemetry/EntityType";
+import logger from "../Utils/Logger";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import { ExtractedEntity } from "../Utils/Telemetry/TelemetryEntity";
+import {
+  getEntityBudget,
+  reconcileByNaturalKey,
+  REGISTRY_PROMOTED_TYPES,
+  shouldWarnEntityBudgetOnce,
+} from "../Utils/Telemetry/EntityRegistry";
+
+export class TelemetryEntityService extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  /**
+   * Forward-only registry reconciliation: upsert a catalog row per
+   * discovered entity, bump `lastSeenAt`, merge descriptive attributes
+   * (last-writer-wins) and union labels. High-churn membership-only
+   * types (container / process / service.instance / telemetry.sdk — see
+   * `REGISTRY_PROMOTED_TYPES`) are skipped: their keys still flow into
+   * the `entityKeys` column on signals, they just never mint registry
+   * rows. New rows are additionally gated by a per-(project, type)
+   * entity budget. Resilient by design — a registry failure must never break
+   * signal ingest, so every error is swallowed (logged). Callers are
+   * expected to throttle this (it should not run on every batch); see
+   * `reconcileEntityRegistryThrottled` in
+   * `Common/Server/Utils/Telemetry/EntityRegistry`.
+   */
+  @CaptureSpan()
+  public async reconcileEntities(data: {
+    projectId: ObjectID;
+    entities: Array<ExtractedEntity>;
+  }): Promise<void> {
+    /*
+     * Per-reconcile budget count cache: at most one countBy per entity
+     * type per reconcile (the fence already throttles reconciles to one
+     * per entity-set per window, so this stays cheap). Creates within
+     * this reconcile increment the cached count so a single batch cannot
+     * blow past the budget.
+     */
+    const countByType: Map<EntityType, number> = new Map<EntityType, number>();
+
+    for (const entity of data.entities) {
+      if (!REGISTRY_PROMOTED_TYPES.has(entity.entityType)) {
+        continue;
+      }
+      try {
+        await this.upsertEntity({
+          projectId: data.projectId,
+          entity,
+          countByType,
+        });
+      } catch (err) {
+        logger.error(
+          `TelemetryEntityService: failed to upsert entity ${entity.entityType}/${entity.entityKey}:`,
+        );
+        logger.error(err as Error);
+      }
+    }
+  }
+
+  private async upsertEntity(data: {
+    projectId: ObjectID;
+    entity: ExtractedEntity;
+    countByType: Map<EntityType, number>;
+  }): Promise<void> {
+    const { projectId, entity, countByType } = data;
+    const now: Date = OneUptimeDate.getCurrentDate();
+
+    await reconcileByNaturalKey({
+      service: this,
+      query: {
+        projectId,
+        entityType: entity.entityType,
+        entityKey: entity.entityKey,
+      },
+      lastSeenAt: now,
+      describe: `entity ${entity.entityType}/${entity.entityKey}`,
+      select: { descriptiveAttributes: true, labels: true },
+      buildUpdate: (existing: Model): QueryDeepPartialEntity<Model> => {
+        return TelemetryEntityService.buildDescriptiveUpdate(entity, existing);
+      },
+      /*
+       * Entity budget (doc §Edge Cases): existing rows always get their
+       * bump above; only NEW rows are gated. Counted via the
+       * (projectId, entityType) index; over budget the row is skipped —
+       * its key still flows in `entityKeys` on signals.
+       */
+      beforeCreate: async (): Promise<boolean> => {
+        const budget: number = getEntityBudget(entity.entityType);
+
+        let count: number | undefined = countByType.get(entity.entityType);
+        if (count === undefined) {
+          count = (
+            await this.countBy({
+              query: { projectId, entityType: entity.entityType },
+              props: { isRoot: true },
+            })
+          ).toNumber();
+          countByType.set(entity.entityType, count);
+        }
+
+        if (count < budget) {
+          countByType.set(entity.entityType, count + 1);
+          return true;
+        }
+
+        if (
+          await shouldWarnEntityBudgetOnce({
+            projectId,
+            entityType: entity.entityType,
+          })
+        ) {
+          logger.warn(
+            `TelemetryEntityService: entity budget reached for project ${projectId.toString()} type ${entity.entityType} (${count} >= ${budget}); skipping new registry rows. Membership keys still flow on signals.`,
+          );
+        }
+        return false;
+      },
+      buildModel: () => {
+        const model: Model = new Model();
+        model.projectId = projectId;
+        model.entityType = entity.entityType;
+        model.entityKey = entity.entityKey;
+        model.identifyingAttributes = entity.identifyingAttributes;
+        if (
+          entity.descriptiveAttributes &&
+          Object.keys(entity.descriptiveAttributes).length > 0
+        ) {
+          model.descriptiveAttributes = entity.descriptiveAttributes;
+        }
+        if (entity.labels && entity.labels.length > 0) {
+          model.labels = TelemetryEntityService.normalizeLabels(entity.labels);
+        }
+        // varchar(ShortText) column; k8s names can run to 253 chars.
+        model.displayName = TelemetryEntityService.deriveDisplayName(
+          entity,
+        ).substring(0, ColumnLength.ShortText);
+        model.firstSeenAt = now;
+        model.lastSeenAt = now;
+        return model;
+      },
+    });
+  }
+
+  /**
+   * Extra fields for the `lastSeenAt` bump on an existing row:
+   * descriptive attributes merge last-writer-wins per key, labels merge
+   * as a set union. Both are written ONLY when the merge actually changes
+   * the stored value, so a stable resource keeps its bump a one-column
+   * update (no jsonb churn).
+   */
+  private static buildDescriptiveUpdate(
+    entity: ExtractedEntity,
+    existing: Model,
+  ): QueryDeepPartialEntity<Model> {
+    /*
+     * Built as a plain shape and cast once on return: assigning into
+     * QueryDeepPartialEntity<Model> directly forces TS to instantiate the
+     * recursive JSONObject mapping (TS2589).
+     */
+    const update: {
+      descriptiveAttributes?: JSONObject;
+      labels?: Array<string>;
+    } = {};
+
+    const incoming: Record<string, string> = entity.descriptiveAttributes || {};
+    if (Object.keys(incoming).length > 0) {
+      const current: Record<string, unknown> =
+        (existing.descriptiveAttributes as Record<string, unknown>) || {};
+
+      const differs: boolean = Object.keys(incoming).some((key: string) => {
+        return current[key] !== incoming[key];
+      });
+
+      if (differs) {
+        update.descriptiveAttributes = {
+          ...current,
+          ...incoming,
+        } as JSONObject;
+      }
+    }
+
+    const incomingLabels: Array<string> = entity.labels || [];
+    if (incomingLabels.length > 0) {
+      const currentLabels: Array<string> = existing.labels || [];
+      const currentSet: Set<string> = new Set<string>(currentLabels);
+
+      const hasNew: boolean = incomingLabels.some((label: string) => {
+        return !currentSet.has(label);
+      });
+
+      if (hasNew) {
+        update.labels = TelemetryEntityService.normalizeLabels([
+          ...currentLabels,
+          ...incomingLabels,
+        ]);
+      }
+    }
+
+    return update as unknown as QueryDeepPartialEntity<Model>;
+  }
+
+  /** Sorted + deduped for a stable stored value. */
+  private static normalizeLabels(labels: Array<string>): Array<string> {
+    return Array.from(new Set<string>(labels)).sort();
+  }
+
+  /**
+   * Best-effort human-readable name for the entity explorer: prefer the
+   * most specific `*.name` identifying attribute (e.g. k8s.pod.name over
+   * k8s.cluster.name), else the last identifying value, else the key.
+   */
+  public static deriveDisplayName(entity: ExtractedEntity): string {
+    const id: Record<string, string> = entity.identifyingAttributes || {};
+    const nameKeys: Array<string> = Object.keys(id)
+      .filter((k: string) => {
+        return k.endsWith(".name");
+      })
+      .sort((a: string, b: string) => {
+        return b.length - a.length;
+      });
+
+    if (nameKeys.length > 0 && id[nameKeys[0]!]) {
+      return id[nameKeys[0]!]!;
+    }
+
+    const keys: Array<string> = Object.keys(id);
+    if (keys.length > 0 && id[keys[keys.length - 1]!]) {
+      return id[keys[keys.length - 1]!]!;
+    }
+
+    return entity.entityKey;
+  }
+}
+
+export default new TelemetryEntityService();