@oneuptime/common 11.5.9 → 11.5.11

package/Server/Services/MetricService.ts

@@ -18,10 +18,23 @@ import AggregationInterval from "../../Types/BaseDatabase/AggregationInterval";
 import AggregatedResult from "../../Types/BaseDatabase/AggregatedResult";
 import AnalyticsTableName from "../../Types/AnalyticsDatabase/AnalyticsTableName";
 import TableColumnType from "../../Types/AnalyticsDatabase/TableColumnType";
+import { LIMIT_PER_PROJECT } from "../../Types/Database/LimitMax";
 import BadDataException from "../../Types/Exception/BadDataException";
 import { JSONObject } from "../../Types/JSON";
-import { keyForHost } from "../../Utils/Telemetry/EntityKey";
+import {
+  canonicalizeEntityValue,
+  keyForHost,
+  keyForKubernetesCluster,
+  keyForService,
+} from "../../Utils/Telemetry/EntityKey";
+import { keyForContainer } from "../Utils/Telemetry/TelemetryEntity";
+import { getEntityBudget } from "../Utils/Telemetry/EntityRegistry";
+import { EntityScopeQueryValue } from "../Utils/AnalyticsDatabase/StatementGenerator";
+import TelemetryEntityService from "./TelemetryEntityService";
+import TelemetryEntity from "../../Models/DatabaseModels/TelemetryEntity";
+import EntityType from "../../Types/Telemetry/EntityType";
 import ObjectID from "../../Types/ObjectID";
+import PositiveNumber from "../../Types/PositiveNumber";
 import logger, { LogAttributes } from "../Utils/Logger";
 
 /*
@@ -46,6 +59,62 @@ const MAX_GROUP_BY_ATTRIBUTE_KEY_LENGTH: number = 256;
 const POINT_TYPE_CACHE_TTL_MS: number = 10 * 60 * 1000;
 const POINT_TYPE_CACHE_MAX_ENTRIES: number = 5000;
 
+/*
+ * Deliberately short: the registry gains a row for a NEW namespaced
+ * service variant asynchronously (throttled reconcile), and until this
+ * cache expires a routed service query would keep serving the stale
+ * (smaller) key set. 60s bounds that staleness to about one dashboard
+ * refresh while still collapsing the burst of per-metric aggregates a
+ * single refresh fires.
+ */
+const SERVICE_ENTITY_KEYS_CACHE_TTL_MS: number = 60 * 1000;
+const SERVICE_ENTITY_KEYS_CACHE_MAX_ENTRIES: number = 5000;
+
+type EntityMVRoute = {
+  /** The resource attribute the entity detail pages filter by. */
+  attributeKey: string;
+  /** The per-entity 1-minute rollup that serves the filter. */
+  tableName: AnalyticsTableName;
+  /** Scalar entity-key column — same name on the raw table and the MV. */
+  keyColumn: string;
+  /**
+   * Read-side key derivation, byte-identical to the ingest stamp. Only
+   * single-attribute identities are derivable this way; `null` means the
+   * key set must come from the registry instead (service — ingest folds
+   * service.namespace into the key when present, so one name can map to
+   * several keys and a computed bare key would silently drop the
+   * namespaced variants' data).
+   */
+  keyForValue: ((projectId: string, value: string) => string) | null;
+};
+
+const ENTITY_MV_ROUTES: ReadonlyArray<EntityMVRoute> = [
+  {
+    attributeKey: "resource.host.name",
+    tableName: AnalyticsTableName.MetricItemAggMV1mByHostV2,
+    keyColumn: "hostEntityKey",
+    keyForValue: keyForHost,
+  },
+  {
+    attributeKey: "resource.k8s.cluster.name",
+    tableName: AnalyticsTableName.MetricItemAggMV1mByK8sCluster,
+    keyColumn: "k8sClusterEntityKey",
+    keyForValue: keyForKubernetesCluster,
+  },
+  {
+    attributeKey: "resource.container.id",
+    tableName: AnalyticsTableName.MetricItemAggMV1mByContainer,
+    keyColumn: "containerEntityKey",
+    keyForValue: keyForContainer,
+  },
+  {
+    attributeKey: "resource.service.name",
+    tableName: AnalyticsTableName.MetricItemAggMV1mByService,
+    keyColumn: "serviceEntityKey",
+    keyForValue: null,
+  },
+];
+
 export class MetricService extends AnalyticsDatabaseService<Metric> {
   /*
    * (projectId|metricName) -> metricPointType, resolved lazily on the
@@ -72,6 +141,33 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
   private inFlightPointTypeLookups: Map<string, Promise<string | null>> =
     new Map();
 
+  /*
+   * Registry-resolved serviceEntityKey set per aggregateBy call, for
+   * queries filtering by `resource.service.name`. Same hand-over pattern
+   * as the point-type hint: toAggregateStatement is synchronous, so the
+   * async Postgres lookup happens in aggregateBy and is keyed on the
+   * (shared) aggregateBy object. An empty array means "registry has no
+   * rows for this name" — the builder then refuses to route (raw path).
+   */
+  private serviceEntityKeysHintByAggregate: WeakMap<
+    AggregateBy<Metric>,
+    Array<string>
+  > = new WeakMap();
+
+  /*
+   * (projectId|canonical service name) -> serviceEntityKey set. Bounded +
+   * short-TTL'd (see SERVICE_ENTITY_KEYS_CACHE_TTL_MS): a dashboard
+   * refresh fires one aggregate per metric name, all for the same
+   * service, and each would otherwise hit Postgres.
+   */
+  private serviceEntityKeysCache: Map<
+    string,
+    { keys: Array<string>; expiresAt: number }
+  > = new Map();
+
+  private inFlightServiceEntityKeyLookups: Map<string, Promise<Array<string>>> =
+    new Map();
+
   public constructor(clickhouseDatabase?: ClickhouseDatabase | undefined) {
     super({ modelType: Metric, database: clickhouseDatabase });
   }
@@ -96,11 +192,244 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       const pointType: string | null =
         await this.resolveMetricPointType(aggregateBy);
       this.pointTypeHintByAggregate.set(aggregateBy, pointType);
+
+      /*
+       * Service-scoped queries need the registry-resolved serviceEntityKey
+       * set before the synchronous statement builder runs. Skipped when
+       * the point type already rules out MV routing (distribution
+       * metrics never touch the rollups).
+       */
+      if (!pointType || !DISTRIBUTION_POINT_TYPES.includes(pointType)) {
+        const serviceKeys: Array<string> | null =
+          await this.resolveServiceEntityKeysHint(aggregateBy);
+        if (serviceKeys) {
+          this.serviceEntityKeysHintByAggregate.set(aggregateBy, serviceKeys);
+        }
+      }
     }
 
     return super.aggregateBy(aggregateBy);
   }
 
+  /**
+   * Resolves the serviceEntityKey set for a query whose only entity
+   * filter is a `resource.service.name` equality — the shape (and the
+   * only shape) the entity-MV builder routes to the per-service rollup.
+   * Returns null for every other query shape so no lookup is wasted.
+   */
+  private async resolveServiceEntityKeysHint(
+    aggregateBy: AggregateBy<Metric>,
+  ): Promise<Array<string> | null> {
+    const queryRecord: Record<string, unknown> =
+      (aggregateBy.query as unknown as Record<string, unknown>) || {};
+
+    // service + entityScope is never routed (see the entity-MV builder).
+    if (
+      queryRecord["entityScope"] !== undefined &&
+      queryRecord["entityScope"] !== null
+    ) {
+      return null;
+    }
+
+    const attrs: unknown = queryRecord["attributes"];
+    if (!attrs || typeof attrs !== "object") {
+      return null;
+    }
+    const attrEntries: Array<[string, unknown]> = Object.entries(
+      attrs as Record<string, unknown>,
+    );
+    if (attrEntries.length !== 1) {
+      return null;
+    }
+    const [attrKey, attrValue] = attrEntries[0]!;
+    if (
+      attrKey !== "resource.service.name" ||
+      typeof attrValue !== "string" ||
+      !attrValue
+    ) {
+      return null;
+    }
+
+    const projectIdValue: unknown = queryRecord["projectId"];
+    let projectId: string = "";
+    if (projectIdValue instanceof ObjectID) {
+      projectId = projectIdValue.toString();
+    } else if (typeof projectIdValue === "string") {
+      projectId = projectIdValue;
+    }
+    if (!projectId) {
+      return null;
+    }
+
+    const cacheKey: string = `${projectId}|${canonicalizeEntityValue(
+      attrValue,
+    )}`;
+    const cached: { keys: Array<string>; expiresAt: number } | undefined =
+      this.serviceEntityKeysCache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.keys;
+    }
+
+    const inFlight: Promise<Array<string>> | undefined =
+      this.inFlightServiceEntityKeyLookups.get(cacheKey);
+    if (inFlight) {
+      return inFlight;
+    }
+
+    const lookup: Promise<Array<string>> = this.lookupServiceEntityKeys(
+      projectId,
+      attrValue,
+    )
+      .then((keys: Array<string>) => {
+        this.evictExpiredServiceEntityKeyCacheEntries();
+        this.serviceEntityKeysCache.set(cacheKey, {
+          keys,
+          expiresAt: Date.now() + SERVICE_ENTITY_KEYS_CACHE_TTL_MS,
+        });
+        return keys;
+      })
+      .finally(() => {
+        this.inFlightServiceEntityKeyLookups.delete(cacheKey);
+      });
+
+    this.inFlightServiceEntityKeyLookups.set(cacheKey, lookup);
+    return lookup;
+  }
+
+  /**
+   * All serviceEntityKeys the ingest pipeline can have stamped for rows
+   * reporting this `service.name`, from the Postgres TelemetryEntity
+   * registry. Service identity folds `service.namespace` into the key
+   * when the resource carries one (see the service resolver in
+   * Common/Server/Utils/Telemetry/TelemetryEntity), so one name maps to
+   * one key per namespace variant — only the registry knows them all.
+   *
+   * `displayName` equals the canonicalized service.name for every
+   * Service row the registry mints (deriveDisplayName prefers the
+   * `service.name` identifying attribute), so the query is indexed and
+   * tiny; the identifyingAttributes re-check below guards against a
+   * displayName that came from some other identity shape. Returns []
+   * on a registry miss, on any lookup failure, or when the project's
+   * Service registry is at/over its entity budget (new variants stop
+   * minting rows there, so the key set can be permanently partial) —
+   * the caller then refuses to route (an MV query must never return
+   * less data than the raw predicate it replaces, and rows of a
+   * namespaced service the registry does not know about would be
+   * silently dropped).
+   */
+  private async lookupServiceEntityKeys(
+    projectId: string,
+    serviceName: string,
+  ): Promise<Array<string>> {
+    try {
+      const canonicalName: string = canonicalizeEntityValue(serviceName);
+
+      const rows: Array<TelemetryEntity> = await TelemetryEntityService.findBy({
+        query: {
+          projectId: new ObjectID(projectId),
+          entityType: EntityType.Service,
+          displayName: canonicalName,
+        },
+        select: {
+          entityKey: true,
+          identifyingAttributes: true,
+        },
+        limit: LIMIT_PER_PROJECT,
+        skip: 0,
+        props: { isRoot: true },
+      });
+
+      const keys: Set<string> = new Set<string>();
+      for (const row of rows) {
+        const identifying: Record<string, unknown> =
+          (row.identifyingAttributes as Record<string, unknown>) || {};
+        if (identifying["service.name"] !== canonicalName) {
+          continue;
+        }
+        if (typeof row.entityKey === "string" && row.entityKey) {
+          keys.add(row.entityKey);
+        }
+      }
+
+      if (keys.size === 0) {
+        return [];
+      }
+
+      /*
+       * Budget-capped projects must not route. At/over the per-type
+       * entity budget, ingest stops minting NEW Service registry rows
+       * forever (TelemetryEntityService.beforeCreate) while namespaced
+       * serviceEntityKeys keep flowing on signal rows — so a non-empty
+       * registry key set may be PERMANENTLY missing identity variants,
+       * and a routed `serviceEntityKey IN (...)` would silently return
+       * less data than the raw attributes predicate it replaces (the
+       * invariant documented above). Same signal as the ingest-side
+       * gate; the [] is cached for 60s alongside key hits, so the extra
+       * countBy amortizes to one per (project, service name) per minute.
+       */
+      const serviceEntityCount: PositiveNumber =
+        await TelemetryEntityService.countBy({
+          query: {
+            projectId: new ObjectID(projectId),
+            entityType: EntityType.Service,
+          },
+          props: { isRoot: true },
+        });
+      if (
+        serviceEntityCount.toNumber() >= getEntityBudget(EntityType.Service)
+      ) {
+        logger.debug(
+          "Service entity registry is budget-capped; refusing MV routing",
+        );
+        return [];
+      }
+
+      /*
+       * Union in the deterministic namespace-less key: a service that
+       * ALSO reports without a namespace may not have minted its bare
+       * registry row yet (reconcile is throttled and budget-gated), and
+       * adding a key can only widen the MV result, never narrow it.
+       */
+      keys.add(keyForService(projectId, serviceName));
+
+      return Array.from(keys).sort();
+    } catch (err) {
+      /*
+       * Lookup failures must not fail the aggregation — without the hint
+       * the builder falls back to the raw table, which is always correct.
+       */
+      logger.debug("Service entity key lookup failed");
+      logger.debug(err);
+      return [];
+    }
+  }
+
+  private evictExpiredServiceEntityKeyCacheEntries(): void {
+    if (
+      this.serviceEntityKeysCache.size < SERVICE_ENTITY_KEYS_CACHE_MAX_ENTRIES
+    ) {
+      return;
+    }
+    const now: number = Date.now();
+    for (const [key, entry] of this.serviceEntityKeysCache) {
+      if (entry.expiresAt <= now) {
+        this.serviceEntityKeysCache.delete(key);
+      }
+    }
+    // Mirrors evictExpiredPointTypeCacheEntries: never clear() wholesale.
+    while (
+      this.serviceEntityKeysCache.size >= SERVICE_ENTITY_KEYS_CACHE_MAX_ENTRIES
+    ) {
+      const oldestKey: string | undefined = this.serviceEntityKeysCache
+        .keys()
+        .next().value;
+      if (oldestKey === undefined) {
+        break;
+      }
+      this.serviceEntityKeysCache.delete(oldestKey);
+    }
+  }
+
   private async resolveMetricPointType(
     aggregateBy: AggregateBy<Metric>,
   ): Promise<string | null> {
@@ -336,6 +665,175 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     statement.append(`) AS attributes`);
   }
 
+  /**
+   * Validated Top-K spec, or null when the caller did not request one.
+   * `count` is parameter-bound where it reaches SQL and `rankBy` only
+   * ever selects between two hardcoded aggregate names, so this is
+   * shape validation (like getSanitizedGroupByAttributeKeys), not
+   * injection defense.
+   */
+  private getSanitizedTopK(
+    aggregateBy: AggregateBy<Metric>,
+  ): { count: number; rankBy: "max" | "avg" } | null {
+    const topK: AggregateBy<Metric>["topK"] = aggregateBy.topK;
+    if (!topK) {
+      return null;
+    }
+    const count: number = Math.floor(Number(topK.count));
+    if (!Number.isFinite(count) || count < 1 || count > LIMIT_PER_PROJECT) {
+      throw new BadDataException(
+        `topK.count must be a positive integer <= ${LIMIT_PER_PROJECT}.`,
+      );
+    }
+    if (topK.rankBy !== "max" && topK.rankBy !== "avg") {
+      throw new BadDataException(`topK.rankBy must be 'max' or 'avg'.`);
+    }
+    return { count, rankBy: topK.rankBy };
+  }
+
+  /**
+   * Appends the raw-table expressions that identify a group — model
+   * group-by columns as identifiers, attribute keys as parameter-bound
+   * `attributes[...]` lookups — in a FIXED order, so the Top-K
+   * IN-restriction tuple, the ranking subquery's SELECT/GROUP BY, and
+   * the totalGroups counter always line up element-for-element.
+   */
+  private appendRawGroupExpressionList(
+    statement: Statement,
+    groupByKeys: Array<string>,
+    attributeGroupKeys: Array<string>,
+  ): void {
+    let isFirst: boolean = true;
+    for (const key of groupByKeys) {
+      if (!isFirst) {
+        statement.append(`, `);
+      }
+      statement.append(key);
+      isFirst = false;
+    }
+    for (const key of attributeGroupKeys) {
+      if (!isFirst) {
+        statement.append(`, `);
+      }
+      statement.append(
+        SQL`attributes[${{ value: key, type: TableColumnType.Text }}]`,
+      );
+      isFirst = false;
+    }
+  }
+
+  /**
+   * Appends the Top-K group restriction predicate:
+   *
+   *   ` AND (<group exprs>) GLOBAL IN (SELECT <group exprs> FROM <table>
+   *      WHERE ... GROUP BY <group exprs>
+   *      ORDER BY max|avg(<column>) DESC LIMIT <k>)`
+   *
+   * The ranking subquery scores each group over the WHOLE query window
+   * (no time bucketing) so a series that spiked early ranks the same as
+   * one spiking late. Must be appended in raw-table WHERE scope — the
+   * innermost WHERE of the surrounding builder — where the group
+   * expressions are valid. Ranking uses plain max/avg of the raw
+   * column (not the distribution-aware expressions): for distribution
+   * metrics that scores by per-export-interval sums, which preserves
+   * relative group ordering well enough for series selection.
+   *
+   * GLOBAL IN is load-bearing: this predicate sits in a query on the
+   * Distributed Metric table whose subquery reads the SAME Distributed
+   * table, which multi-shard ClickHouse rejects outright as a
+   * double-distributed subquery (Code 288, distributed_product_mode =
+   * 'deny' by default) — every grouped Top-K chart would 500 on a
+   * 2+-shard cluster. A shard-local rewrite would be wrong anyway: the
+   * sharding key is cityHash64(projectId, name, primaryEntityId), so
+   * one project+metric's groups span shards and the ranking must be
+   * computed once globally, not per shard. On a single shard GLOBAL is
+   * a semantic no-op. (The mutable-metric twin below deliberately stays
+   * plain IN: its predicate lives in an initiator-evaluated outer query
+   * over a subquery-FROM, which is not subject to the denial.)
+   */
+  private appendTopKGroupRestriction(data: {
+    statement: Statement;
+    databaseName: string;
+    aggregateBy: AggregateBy<Metric>;
+    topK: { count: number; rankBy: "max" | "avg" };
+    groupByKeys: Array<string>;
+    attributeGroupKeys: Array<string>;
+  }): void {
+    const statement: Statement = data.statement;
+    const aggregationColumn: string =
+      data.aggregateBy.aggregateColumnName.toString();
+
+    statement.append(` AND (`);
+    this.appendRawGroupExpressionList(
+      statement,
+      data.groupByKeys,
+      data.attributeGroupKeys,
+    );
+    statement.append(`) GLOBAL IN (SELECT `);
+    this.appendRawGroupExpressionList(
+      statement,
+      data.groupByKeys,
+      data.attributeGroupKeys,
+    );
+    statement.append(
+      ` FROM ${data.databaseName}.${this.model.tableName} WHERE TRUE `,
+    );
+    statement.append(
+      this.statementGenerator.toWhereStatement(data.aggregateBy.query),
+    );
+    statement.append(this.getRetentionReadFilter());
+    statement.append(` GROUP BY `);
+    this.appendRawGroupExpressionList(
+      statement,
+      data.groupByKeys,
+      data.attributeGroupKeys,
+    );
+    statement.append(
+      ` ORDER BY ${data.topK.rankBy}(${aggregationColumn}) DESC`,
+    );
+    statement.append(
+      SQL` LIMIT ${{
+        value: data.topK.count,
+        type: TableColumnType.Number,
+      }}`,
+    );
+    statement.append(`)`);
+  }
+
+  /**
+   * Appends `, (SELECT uniqExact(<group exprs>) FROM <table>
+   * WHERE ...) AS __total_groups` — a scalar subquery counting every
+   * distinct group in the window BEFORE Top-K trims them. The value is
+   * constant across result rows; AnalyticsDatabaseService._aggregateBy
+   * reads it off the first row into AggregatedResult.totalGroups and it
+   * never reaches the per-row payload. Must be appended in SELECT-list
+   * position of the outer query.
+   */
+  private appendTotalGroupsColumn(data: {
+    statement: Statement;
+    databaseName: string;
+    aggregateBy: AggregateBy<Metric>;
+    groupByKeys: Array<string>;
+    attributeGroupKeys: Array<string>;
+  }): void {
+    const statement: Statement = data.statement;
+
+    statement.append(`, (SELECT uniqExact(`);
+    this.appendRawGroupExpressionList(
+      statement,
+      data.groupByKeys,
+      data.attributeGroupKeys,
+    );
+    statement.append(
+      `) FROM ${data.databaseName}.${this.model.tableName} WHERE TRUE `,
+    );
+    statement.append(
+      this.statementGenerator.toWhereStatement(data.aggregateBy.query),
+    );
+    statement.append(this.getRetentionReadFilter());
+    statement.append(`) AS __total_groups`);
+  }
+
   /*
    * Cascade deletes from `MetricItemV3` into the aggregating
    * materialized-view target tables.
@@ -352,10 +850,11 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
    * The cascade only runs when the caller scoped the delete by
    * `primaryEntityId`. Global time-based purges (TTL cleanup) are handled
    * by each MV table's own `retentionDate TTL DELETE`, so cascading those
-   * would pointlessly scan the whole MV. The per-host MV
-   * (`MetricItemAggMV1mByHostV2`) is keyed by `hostEntityKey` rather than
-   * `primaryEntityId`, so an entity-scoped delete has nothing to remove
-   * there — skip it.
+   * would pointlessly scan the whole MV. The per-entity MVs
+   * (`MetricItemAggMV1mByHostV2` / `...ByService` / `...ByK8sCluster` /
+   * `...ByContainer`) are keyed by their scalar entity-key column rather
+   * than `primaryEntityId`, so an entity-scoped delete has nothing to
+   * remove there — skip them.
    */
   public override async deleteBy(deleteBy: DeleteBy<Metric>): Promise<void> {
     await super.deleteBy(deleteBy);
@@ -498,11 +997,12 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
 
     if (!isPercentileAggregation(aggregateBy.aggregationType)) {
       /*
-       * Try the per-host MV first — host detail pages are the
-       * dominant attribute-filtered path and the per-host MV is
-       * the only one that can serve them. If it doesn't apply
-       * (no host filter, or extra attrs/groupBy), fall through
-       * to the project/primaryEntityId MV, then to the base table.
+       * Try the per-entity MVs first — entity detail pages (host, k8s
+       * cluster, container, service) are the dominant filtered path and
+       * the entity-keyed rollups are the only ones that can serve them.
+       * If none applies (no entity filter, or extra attrs/groupBy), fall
+       * through to the project/primaryEntityId MV, then to the base
+       * table.
        *
        * Distribution metrics (histograms/summaries) must skip the
        * MVs entirely: their states collapse `value`, which for
@@ -514,12 +1014,12 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
         attributeGroupKeys.length === 0 &&
         !this.isDistributionMetricAggregate(aggregateBy)
       ) {
-        const hostMvStatement: {
+        const entityMvStatement: {
           statement: Statement;
           columns: Array<string>;
-        } | null = this.tryBuildHostAggregateMVStatement(aggregateBy);
-        if (hostMvStatement) {
-          return hostMvStatement;
+        } | null = this.tryBuildEntityAggregateMVStatement(aggregateBy);
+        if (entityMvStatement) {
+          return entityMvStatement;
         }
         const mvStatement: {
           statement: Statement;
@@ -693,6 +1193,30 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
      */
     this.appendAttributeGroupMapColumn(statement, attributeGroupKeys);
 
+    /*
+     * Server-side Top-K: rank groups over the whole window, restrict
+     * the bucketed quantile to the winners, and surface the pre-trim
+     * group count. Only meaningful when the aggregation is grouped —
+     * p95-by-host must get the same series selection as the scalar
+     * paths.
+     */
+    const percentileTopK: { count: number; rankBy: "max" | "avg" } | null =
+      this.getSanitizedTopK(aggregateBy);
+    const percentileApplyTopK: boolean = Boolean(
+      percentileTopK &&
+        (groupByKeys.length > 0 || attributeGroupKeys.length > 0),
+    );
+
+    if (percentileApplyTopK) {
+      this.appendTotalGroupsColumn({
+        statement,
+        databaseName,
+        aggregateBy,
+        groupByKeys,
+        attributeGroupKeys,
+      });
+    }
+
     statement.append(SQL` FROM (`);
     statement.append(`SELECT ${innerSelectClause}`);
     this.appendAttributeGroupExtractionColumns(statement, attributeGroupKeys);
@@ -701,6 +1225,16 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     );
     statement.append(whereStatement);
     statement.append(this.getRetentionReadFilter());
+    if (percentileApplyTopK) {
+      this.appendTopKGroupRestriction({
+        statement,
+        databaseName,
+        aggregateBy,
+        topK: percentileTopK!,
+        groupByKeys,
+        attributeGroupKeys,
+      });
+    }
     statement.append(SQL`) `);
 
     /*
@@ -748,16 +1282,28 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
 
     /*
      * Match the read-path settings the base aggregator now appends (see
-     * AnalyticsDatabaseService.toAggregateStatement). The percentile
-     * path bypasses the base method, so we mirror them here to keep
-     * cluster behavior consistent across aggregation kinds.
+     * AnalyticsDatabaseService.toAggregateStatement), including the 45s
+     * execution cap and the caller-selected overflow mode. The
+     * percentile path bypasses the base method, so we mirror them here
+     * to keep cluster behavior consistent across aggregation kinds.
+     *
+     * transform_null_in=1 rides along only when the Top-K restriction
+     * is present: grouping by a Nullable model column (metricPointType,
+     * unit, ...) puts NULL group keys in play, and under the ClickHouse
+     * default (transform_null_in=0) NULL never matches an IN — a
+     * NULL-keyed group could win a ranking slot yet return zero rows.
+     * Query-wide it is safe here: user-filter IN lists are
+     * parameter-bound scalar arrays that never carry NULL.
      */
     statement.append(
       getQuerySettings({
+        maxExecutionTimeInSeconds: 45,
+        timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
         additionalSettings: {
           optimize_aggregation_in_order: 1,
           optimize_move_to_prewhere: 1,
           max_threads: 4,
+          ...(percentileApplyTopK ? { transform_null_in: 1 } : {}),
         },
       }),
     );
@@ -898,6 +1444,17 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
 
     const statement: Statement = SQL``;
 
+    /*
+     * Server-side Top-K: rank groups over the whole window, restrict
+     * the bucketed aggregation to the winners, and surface the pre-trim
+     * group count. Only meaningful when the aggregation is grouped.
+     */
+    const scalarTopK: { count: number; rankBy: "max" | "avg" } | null =
+      this.getSanitizedTopK(aggregateBy);
+    const scalarApplyTopK: boolean = Boolean(
+      scalarTopK && (groupByKeys.length > 0 || attributeGroupKeys.length > 0),
+    );
+
     statement.append(
       `SELECT ${aggregationExpression} as ${aggregationColumn}, ${AggregateUtil.buildBucketTimestampSelect(resolvedInterval, aggregationTimestampColumn)}`,
     );
@@ -905,6 +1462,15 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       statement.append(`, ${key}`);
     }
     this.appendAttributeGroupMapColumn(statement, attributeGroupKeys);
+    if (scalarApplyTopK) {
+      this.appendTotalGroupsColumn({
+        statement,
+        databaseName,
+        aggregateBy,
+        groupByKeys,
+        attributeGroupKeys,
+      });
+    }
 
     if (attributeGroupKeys.length > 0) {
       /*
@@ -935,6 +1501,16 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       );
       statement.append(whereStatement);
       statement.append(this.getRetentionReadFilter());
+      if (scalarApplyTopK) {
+        this.appendTopKGroupRestriction({
+          statement,
+          databaseName,
+          aggregateBy,
+          topK: scalarTopK!,
+          groupByKeys,
+          attributeGroupKeys,
+        });
+      }
       statement.append(SQL`) `);
     } else {
       statement.append(
@@ -942,6 +1518,16 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       );
       statement.append(whereStatement);
       statement.append(this.getRetentionReadFilter());
+      if (scalarApplyTopK) {
+        this.appendTopKGroupRestriction({
+          statement,
+          databaseName,
+          aggregateBy,
+          topK: scalarTopK!,
+          groupByKeys,
+          attributeGroupKeys,
+        });
+      }
     }
 
     /*
@@ -986,12 +1572,19 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       }} `,
     );
 
+    /*
+     * transform_null_in=1 only when the Top-K IN restriction is present
+     * — see the percentile path's settings comment for the rationale.
+     */
     statement.append(
       getQuerySettings({
+        maxExecutionTimeInSeconds: 45,
+        timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
         additionalSettings: {
           optimize_aggregation_in_order: 1,
           optimize_move_to_prewhere: 1,
           max_threads: 4,
+          ...(scalarApplyTopK ? { transform_null_in: 1 } : {}),
         },
       }),
     );
@@ -1049,11 +1642,37 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       aggregateBy.sort!,
     );
 
+    /*
+     * Server-side Top-K for the (model-column) grouped mutable path.
+     * The ranking subquery and totalGroups counter each re-run the
+     * dedup subquery (buildMutableMetricDedupSource) — acceptable
+     * because the mutable table is small by design (bounded-cardinality
+     * business metrics), unlike the raw Metric table.
+     */
+    const mutableTopK: { count: number; rankBy: "max" | "avg" } | null =
+      this.getSanitizedTopK(aggregateBy);
+    const mutableGroupByKeys: Array<string> = aggregateBy.groupBy
+      ? Object.keys(aggregateBy.groupBy)
+      : [];
+    const mutableApplyTopK: boolean = Boolean(
+      mutableTopK && mutableGroupByKeys.length > 0,
+    );
+
     const statement: Statement = SQL``;
 
+    statement.append(SQL`SELECT `).append(select.statement);
+
+    if (mutableApplyTopK) {
+      statement.append(`, (SELECT uniqExact(`);
+      this.appendRawGroupExpressionList(statement, mutableGroupByKeys, []);
+      statement.append(`)`);
+      statement.append(
+        this.buildMutableMetricDedupSource(databaseName, aggregateBy),
+      );
+      statement.append(`) AS __total_groups`);
+    }
+
     statement
-      .append(SQL`SELECT `)
-      .append(select.statement)
       .append(
         SQL`
           FROM (
@@ -1091,6 +1710,35 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       .append(outerWhereStatement)
       .append(SQL` AND retentionDate >= now()`);
 
+    if (mutableApplyTopK) {
+      /*
+       * Plain (non-GLOBAL) IN is deliberate here, unlike
+       * appendTopKGroupRestriction: this predicate sits in the OUTER
+       * query whose FROM is the argMax-dedup subquery — the initiator
+       * evaluates it, so it is not a double-distributed subquery and
+       * multi-shard ClickHouse accepts it as-is.
+       */
+      statement.append(` AND (`);
+      this.appendRawGroupExpressionList(statement, mutableGroupByKeys, []);
+      statement.append(`) IN (SELECT `);
+      this.appendRawGroupExpressionList(statement, mutableGroupByKeys, []);
+      statement.append(
+        this.buildMutableMetricDedupSource(databaseName, aggregateBy),
+      );
+      statement.append(` GROUP BY `);
+      this.appendRawGroupExpressionList(statement, mutableGroupByKeys, []);
+      statement.append(
+        ` ORDER BY ${mutableTopK!.rankBy}(${aggregateBy.aggregateColumnName.toString()}) DESC`,
+      );
+      statement.append(
+        SQL` LIMIT ${{
+          value: mutableTopK!.count,
+          type: TableColumnType.Number,
+        }}`,
+      );
+      statement.append(`)`);
+    }
+
     /*
      * Mirror the base builder's Total handling: the SELECT above (shared
      * toAggregateSelectStatement) already emits `min(time)` for a `Total`
@@ -1155,11 +1803,20 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       }}`,
     );
 
+    /*
+     * transform_null_in=1 only when the Top-K IN restriction is present
+     * — see the percentile path's settings comment for the rationale
+     * (mutable group-by keys are Nullable model columns too, e.g.
+     * primaryEntityType).
+     */
     statement.append(
       getQuerySettings({
+        maxExecutionTimeInSeconds: 45,
+        timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
         additionalSettings: {
           optimize_move_to_prewhere: 1,
           max_threads: 4,
+          ...(mutableApplyTopK ? { transform_null_in: 1 } : {}),
         },
       }),
     );
@@ -1177,6 +1834,63 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     };
   }
 
+  /**
+   * A fresh `FROM (...) WHERE ...` fragment over the argMax-deduped
+   * mutable-metric rows — the same source the main mutable aggregate
+   * reads from — for the Top-K ranking subquery and totalGroups
+   * counter, which need their own scan of the deduped rows (the
+   * versioned raw rows must never be ranked directly, or a metric
+   * updated N times would rank by its stalest value).
+   */
+  private buildMutableMetricDedupSource(
+    databaseName: string,
+    aggregateBy: AggregateBy<Metric>,
+  ): Statement {
+    const source: Statement = SQL``;
+    source
+      .append(
+        SQL`
+          FROM (
+            SELECT
+              projectId,
+              name,
+              primaryEntityId,
+              primaryEntityType,
+              metricPointId,
+              argMax(metricPointType, version) AS metricPointType,
+              argMax(time, version) AS time,
+              argMax(timeUnixNano, version) AS timeUnixNano,
+              argMax(attributes, version) AS attributes,
+              argMax(attributeKeys, version) AS attributeKeys,
+              argMax(value, version) AS value,
+              argMax(retentionDate, version) AS retentionDate,
+              argMax(isDeleted, version) AS isDeleted
+            FROM ${databaseName}.${AnalyticsTableName.MutableMetric}
+            WHERE TRUE
+        `,
+      )
+      .append(
+        this.statementGenerator.toWhereStatement(
+          this.getMutableMetricInnerQuery(aggregateBy.query),
+        ),
+      )
+      .append(
+        SQL`
+            GROUP BY
+              projectId,
+              name,
+              primaryEntityId,
+              primaryEntityType,
+              metricPointId
+          )
+          WHERE isDeleted = false
+        `,
+      )
+      .append(this.statementGenerator.toWhereStatement(aggregateBy.query))
+      .append(SQL` AND retentionDate >= now()`);
+    return source;
+  }
+
   private getMutableMetricInnerQuery(query: Query<Metric>): Query<Metric> {
     const queryRecord: Record<string, unknown> = query as unknown as Record<
       string,
@@ -1323,10 +2037,11 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     });
     /*
      * The MV is bucketed at 1 minute, so every time-bucketed interval
-     * (Minute / Hour / Day / Week / Month / Year) is >= MV resolution and
-     * acceptable — the honored interval flows into the date_trunc below.
-     * `Total` (whole-window, no bucketing) is the one exception: fall back
-     * to the raw-table builder, which knows how to collapse the window.
+     * (Minute / FiveMinutes / ... / Year) is >= MV resolution and
+     * acceptable — the honored interval flows into the shared bucket
+     * expression below. `Total` (whole-window, no bucketing) is the one
+     * exception: fall back to the raw-table builder, which knows how to
+     * collapse the window.
      */
     if (AggregateUtil.isTotalAggregation(interval)) {
       return null;
@@ -1382,8 +2097,6 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     }
     const databaseName: string = this.database.getDatasourceOptions().database!;
 
-    const intervalLower: string = interval.toLowerCase();
-
     let mergedExpr: string;
     if (aggType === AggregationType.Sum) {
       mergedExpr = `sumMerge(valueSumState)`;
@@ -1414,7 +2127,7 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     const statement: Statement = SQL``;
 
     statement.append(
-      `SELECT ${mergedExpr} as value, date_trunc('${intervalLower}', toStartOfInterval(bucketTime, INTERVAL 1 ${intervalLower})) as time`,
+      `SELECT ${mergedExpr} as value, ${AggregateUtil.buildBucketTimestampExpression(interval, "bucketTime")} as time`,
     );
     statement.append(SQL` FROM ${databaseName}.MetricItemAggMV1m`);
     statement.append(
@@ -1438,6 +2151,8 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     );
     statement.append(
       getQuerySettings({
+        maxExecutionTimeInSeconds: 45,
+        timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
         additionalSettings: {
           optimize_aggregation_in_order: 1,
           optimize_move_to_prewhere: 1,
@@ -1463,30 +2178,55 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
   }
 
   /*
-   * Per-host materialized-view fast path.
+   * Entity-scoped materialized-view fast path (per-entity 1-minute
+   * rollups, keyed by the ingest-stamped scalar entity-key columns).
+   * Entity keys canonicalize their value (trim + lowercase), so spelling
+   * drift in the reported identity still lands on one rollup stream.
    *
-   * Returns a statement that reads from MetricItemAggMV1mByHostV2
-   * (created by RekeyMetricHostRollupToEntityKey), which is keyed by
-   * the stable `hostEntityKey` — the incoming `resource.host.name`
-   * filter value is folded into that key server-side via
-   * EntityKey.keyForHost, so spelling drift (case/whitespace) in the
-   * reported hostname still lands on one rollup stream. Applies when:
+   * Routing decision table — ALL of these outer gates must hold:
+   *   Sum/Avg/Min/Max/Count over `value` bucketed by `time`; no group-by
+   *   of any kind (an entity-key-keyed MV cannot label legend series);
+   *   not a distribution metric and not a percentile (enforced by the
+   *   caller); a bucketed (non-Total) interval; a projectId (the entity
+   *   key is tenant-scoped by construction); and no query columns beyond
+   *   projectId/name/time/attributes/entityScope.
+   * Then exactly ONE of these entity-filter shapes routes:
    *
-   *   - The aggregation is Sum/Avg/Min/Max/Count over `value`.
-   *   - The only attribute filter is `resource.host.name` as a
-   *     bare-string equality (the dashboard's host detail page
-   *     pattern), and the query carries a `projectId` (the entity
-   *     key is tenant-scoped by construction).
-   *   - The query carries no group-by other than the time
-   *     bucket — the MV is keyed by hostEntityKey and does not
-   *     preserve other attribute breakdowns.
+   *   attributes == {resource.host.name: v}
+   *     -> MetricItemAggMV1mByHostV2, hostEntityKey = keyForHost(projectId, v)
+   *   attributes == {resource.k8s.cluster.name: v}
+   *     -> MetricItemAggMV1mByK8sCluster, k8sClusterEntityKey = keyForKubernetesCluster(projectId, v)
+   *   attributes == {resource.container.id: v}
+   *     -> MetricItemAggMV1mByContainer, containerEntityKey = keyForContainer(projectId, v)
+   *   attributes == {resource.service.name: v}
+   *     -> MetricItemAggMV1mByService, serviceEntityKey IN (<registry key set>)
+   *        The key set is resolved asynchronously in aggregateBy() from
+   *        the Postgres TelemetryEntity registry — service identity folds
+   *        service.namespace into the key at ingest, so one name can map
+   *        to several keys. No registry rows -> NO routing (raw path).
+   *   entityScope only, attributeKey in {host/k8s-cluster/container} and
+   *   entityKeys verified byte-equal to [keyFor<type>(projectId, attributeValue)]
+   *     -> same MV as the matching attribute shape. The scope's attribute
+   *        OR-fallback only adds rows ingested before the entity-key
+   *        columns existed — the same retention-bounded gap the original
+   *        per-host path accepted.
+   *   attributes(single recognized key) + entityScope agreeing on
+   *   attributeKey/attributeValue (the host/k8s Metrics-tab sparkline
+   *   shape; the scope is then redundant — A AND (B OR A) === A)
+   *     -> same MV as the attribute shape (service excluded).
+   *
+   * Everything else falls through (minute MV, then raw): service +
+   * entityScope (a bare-key translation would drop namespaced variants),
+   * unverifiable or multi-key scopes, extra attribute filters, non-string
+   * values, k8s pod/node identities (composite cluster(+namespace)+uid —
+   * not derivable from a single attribute), and any other query column.
+   * When in doubt this method returns null; the raw path is always
+   * correct.
    *
-   * Returns `null` if any condition fails so the caller falls
-   * through to the next fast path / base table. The result row
-   * shape (columns: aggregateColumn, timestampColumn) matches
-   * the base statement so downstream code needs no changes.
+   * The result row shape (columns: aggregateColumn, timestampColumn)
+   * matches the base statement so downstream code needs no changes.
    */
-  private tryBuildHostAggregateMVStatement(
+  private tryBuildEntityAggregateMVStatement(
     aggregateBy: AggregateBy<Metric>,
   ): { statement: Statement; columns: Array<string> } | null {
     const aggType: AggregationType = aggregateBy.aggregationType;
@@ -1519,80 +2259,51 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       return null;
     }
 
-    /*
-     * Inspect the attribute filter. This MV is only safe when
-     * the user is filtering by exactly one attribute,
-     * `resource.host.name`, with a bare-string value (the
-     * canonical Overview/Metrics-page pattern). Anything else —
-     * extra attribute filters, NotEqual, Search, etc. — has to
-     * fall back so the result stays correct.
-     */
     const queryRecord: Record<string, unknown> =
       (aggregateBy.query as unknown as Record<string, unknown>) || {};
-    const attrs: unknown = queryRecord["attributes"];
-    if (!attrs || typeof attrs !== "object") {
-      return null;
-    }
-    const attrEntries: Array<[string, unknown]> = Object.entries(
-      attrs as Record<string, unknown>,
-    );
-    if (attrEntries.length !== 1) {
-      return null;
+
+    /*
+     * The entity keys fold the tenant in (sha256(projectId|type|...)), so
+     * MV rows can only be located when the query is project-scoped.
+     * Dashboard reads always are; anything else falls back safely.
+     */
+    const projectIdValue: unknown = queryRecord["projectId"];
+    let projectId: string = "";
+    if (projectIdValue instanceof ObjectID) {
+      projectId = projectIdValue.toString();
+    } else if (typeof projectIdValue === "string") {
+      projectId = projectIdValue;
     }
-    const [attrKey, attrValue] = attrEntries[0]!;
-    if (attrKey !== "resource.host.name") {
+    if (!projectId) {
       return null;
     }
-    if (attrValue === undefined || attrValue === null) {
+
+    const resolved: { route: EntityMVRoute; keys: Array<string> } | null =
+      this.resolveEntityMVRouteAndKeys(aggregateBy, queryRecord, projectId);
+    if (!resolved) {
       return null;
     }
 
     /*
-     * The MV only carries projectId/name/hostEntityKey/bucketTime. Any
-     * other query key (primaryEntityId, entityScope, entityKeys, ...)
-     * would compile to a WHERE over a column the MV does not have, so
-     * fall back to the raw table for those. Mirrors
-     * tryBuildMinuteAggregateMVStatement.
+     * Each MV only carries projectId/name/<entity key>/bucketTime. Any
+     * other query key (primaryEntityId, entityKeys, ...) would compile to
+     * a WHERE over a column the MV does not have, so fall back to the raw
+     * table for those. Mirrors tryBuildMinuteAggregateMVStatement.
+     * `attributes` and `entityScope` are validated and rewritten into the
+     * entity-key predicate by resolveEntityMVRouteAndKeys above.
      */
     const mvQueryableColumns: ReadonlyArray<string> = [
       "projectId",
       "name",
       "time", // stripped below; bucketTime range is added explicitly
-      "attributes", // rewritten below into the hostEntityKey predicate
+      "attributes",
+      "entityScope",
     ];
     for (const queryKey of Object.keys(queryRecord)) {
       if (!mvQueryableColumns.includes(queryKey)) {
         return null;
       }
     }
-    const hostIdentifier: string =
-      typeof attrValue === "string" ? attrValue : "";
-    if (!hostIdentifier) {
-      return null;
-    }
-
-    /*
-     * The entity key folds the tenant in (sha256(projectId|host|...)), so
-     * the MV row can only be located when the query is project-scoped.
-     * Dashboard reads always are; anything else falls back safely.
-     */
-    const projectIdValue: unknown = queryRecord["projectId"];
-    let projectId: string = "";
-    if (projectIdValue instanceof ObjectID) {
-      projectId = projectIdValue.toString();
-    } else if (typeof projectIdValue === "string") {
-      projectId = projectIdValue;
-    }
-    if (!projectId) {
-      return null;
-    }
-
-    /*
-     * Same canonicalized key the ingest pipeline stamps into
-     * MetricItemV3.hostEntityKey (and the V2 MV groups by) — byte-equality
-     * is what makes this lookup correct, see Common/Utils/Telemetry/EntityKey.
-     */
-    const hostEntityKey: string = keyForHost(projectId, hostIdentifier);
 
     const interval: AggregationInterval = AggregateUtil.getAggregationInterval({
       startDate: aggregateBy.startTimestamp!,
@@ -1600,10 +2311,10 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       aggregationInterval: aggregateBy.aggregationInterval,
     });
     /*
-     * `Total` (whole-window, no bucketing) is not served by this
-     * time-bucketed per-host MV — fall back to the raw-table builder.
-     * Every other interval is >= the MV's 1-minute resolution and flows
-     * into the date_trunc below.
+     * `Total` (whole-window, no bucketing) is not served by these
+     * time-bucketed per-entity MVs — fall back to the raw-table builder.
+     * Every other interval is >= the MVs' 1-minute resolution and flows
+     * into the shared bucket expression below.
      */
     if (AggregateUtil.isTotalAggregation(interval)) {
       return null;
@@ -1614,8 +2325,6 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     }
     const databaseName: string = this.database.getDatasourceOptions().database!;
 
-    const intervalLower: string = interval.toLowerCase();
-
     let mergedExpr: string;
     if (aggType === AggregationType.Sum) {
       mergedExpr = `sumMerge(valueSumState)`;
@@ -1630,13 +2339,13 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     }
 
     /*
-     * Strip both `time` (column doesn't exist on the MV; we
-     * inject an explicit bucketTime range below) and
-     * `attributes` (the attribute filter is now an explicit
-     * `hostEntityKey =` predicate against an MV column).
+     * Strip `time` (column doesn't exist on the MV; we inject an
+     * explicit bucketTime range below) plus `attributes`/`entityScope`
+     * (the entity filter is now an explicit predicate against the MV's
+     * entity-key column).
      */
     const filteredQuery: typeof aggregateBy.query =
-      this.stripAttributesAndTimeFromQuery(
+      this.stripEntityFilterAndTimeFromQuery(
         aggregateBy.query,
       ) as typeof aggregateBy.query;
     const nonTimeWhere: Statement =
@@ -1648,18 +2357,29 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     const statement: Statement = SQL``;
 
     statement.append(
-      `SELECT ${mergedExpr} as value, date_trunc('${intervalLower}', toStartOfInterval(bucketTime, INTERVAL 1 ${intervalLower})) as time`,
+      `SELECT ${mergedExpr} as value, ${AggregateUtil.buildBucketTimestampExpression(interval, "bucketTime")} as time`,
     );
-    statement.append(SQL` FROM ${databaseName}.MetricItemAggMV1mByHostV2`);
+    statement.append(SQL` FROM ${databaseName}.`);
+    statement.append(resolved.route.tableName);
     statement.append(
       ` WHERE bucketTime >= toDateTime('${this.formatDateTime(aggregateBy.startTimestamp!)}') AND bucketTime <= toDateTime('${this.formatDateTime(aggregateBy.endTimestamp!)}')${this.getRetentionReadFilter()}`,
     );
-    statement.append(
-      SQL` AND hostEntityKey = ${{
-        value: hostEntityKey,
-        type: TableColumnType.Text,
-      }}`,
-    );
+    statement.append(` AND ${resolved.route.keyColumn}`);
+    if (resolved.keys.length === 1) {
+      statement.append(
+        SQL` = ${{
+          value: resolved.keys[0]!,
+          type: TableColumnType.Text,
+        }}`,
+      );
+    } else {
+      statement.append(
+        SQL` IN ${{
+          value: resolved.keys,
+          type: TableColumnType.ArrayText,
+        }}`,
+      );
+    }
     statement.append(SQL` `).append(nonTimeWhere);
 
     statement.append(SQL` GROUP BY `).append(`time`);
@@ -1678,6 +2398,8 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     );
     statement.append(
       getQuerySettings({
+        maxExecutionTimeInSeconds: 45,
+        timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
         additionalSettings: {
           optimize_aggregation_in_order: 1,
           optimize_move_to_prewhere: 1,
@@ -1686,7 +2408,7 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
       }),
     );
 
-    logger.debug(`${this.model.tableName} Host MV Aggregate Statement`, {
+    logger.debug(`${this.model.tableName} Entity MV Aggregate Statement`, {
       tableName: this.model.tableName,
     } as LogAttributes);
     logger.debug(statement, {
@@ -1702,13 +2424,139 @@ export class MetricService extends AnalyticsDatabaseService<Metric> {
     };
   }
 
-  private stripAttributesAndTimeFromQuery(query: unknown): typeof query {
+  /**
+   * The single entity filter of a query, resolved to the MV route that
+   * serves it and the exact entity-key set to filter by — or null when
+   * no branch of the routing decision table (see
+   * tryBuildEntityAggregateMVStatement) matches. Never guesses: every
+   * shape it accepts is one whose MV predicate provably covers the raw
+   * predicate it replaces (modulo the accepted pre-entity-key-column
+   * rows).
+   */
+  private resolveEntityMVRouteAndKeys(
+    aggregateBy: AggregateBy<Metric>,
+    queryRecord: Record<string, unknown>,
+    projectId: string,
+  ): { route: EntityMVRoute; keys: Array<string> } | null {
+    const attrs: unknown = queryRecord["attributes"];
+    if (attrs !== undefined && attrs !== null && typeof attrs !== "object") {
+      return null;
+    }
+    const attrEntries: Array<[string, unknown]> =
+      attrs && typeof attrs === "object"
+        ? Object.entries(attrs as Record<string, unknown>)
+        : [];
+    if (attrEntries.length > 1) {
+      return null;
+    }
+
+    const scopeValue: unknown = queryRecord["entityScope"];
+    const scope: EntityScopeQueryValue | null =
+      scopeValue !== undefined &&
+      scopeValue !== null &&
+      typeof scopeValue === "object"
+        ? (scopeValue as EntityScopeQueryValue)
+        : null;
+    // A present-but-malformed entityScope is a filter we cannot honor.
+    if (scopeValue !== undefined && scopeValue !== null && !scope) {
+      return null;
+    }
+
+    if (attrEntries.length === 1) {
+      const [attrKey, attrValue] = attrEntries[0]!;
+      const route: EntityMVRoute | undefined = ENTITY_MV_ROUTES.find(
+        (candidate: EntityMVRoute) => {
+          return candidate.attributeKey === attrKey;
+        },
+      );
+      if (!route || typeof attrValue !== "string" || !attrValue) {
+        return null;
+      }
+
+      if (scope) {
+        /*
+         * The host/k8s Metrics tabs send the attribute filter AND a
+         * matching entityScope in the same query. When the scope is
+         * provably the SAME entity filter (same attributeKey/value), the
+         * conjunction reduces to the attribute equality — the scope's
+         * OR-fallback is subsumed — so route on the attribute alone. Any
+         * disagreement means a genuine second filter: fall back. Service
+         * is excluded outright: its scope keys cannot be verified against
+         * a computed key (namespace variants).
+         */
+        if (route.keyForValue === null) {
+          return null;
+        }
+        if (
+          scope.attributeKey !== attrKey ||
+          String(scope.attributeValue ?? "") !== attrValue
+        ) {
+          return null;
+        }
+      }
+
+      if (route.keyForValue === null) {
+        /*
+         * Service: the registry-resolved key set was handed over by
+         * aggregateBy(). Absent or empty (sync caller, registry miss,
+         * lookup failure) -> raw path.
+         */
+        const hintKeys: Array<string> | undefined =
+          this.serviceEntityKeysHintByAggregate.get(aggregateBy);
+        if (!hintKeys || hintKeys.length === 0) {
+          return null;
+        }
+        return { route, keys: hintKeys };
+      }
+
+      return { route, keys: [route.keyForValue(projectId, attrValue)] };
+    }
+
+    // No attribute filter: entityScope-only shape.
+    if (!scope) {
+      return null;
+    }
+    const route: EntityMVRoute | undefined = ENTITY_MV_ROUTES.find(
+      (candidate: EntityMVRoute) => {
+        return candidate.attributeKey === scope.attributeKey;
+      },
+    );
+    if (!route || route.keyForValue === null) {
+      return null;
+    }
+    const scopeAttributeValue: unknown = scope.attributeValue;
+    if (typeof scopeAttributeValue !== "string" || !scopeAttributeValue) {
+      return null;
+    }
+
+    /*
+     * `hasAny(entityKeys, [...])` is only translatable to the scalar
+     * entity-key column when every listed key IS the key this scope's
+     * attribute value derives to — recompute it server-side and require
+     * byte equality (a foreign or extra key would make the raw predicate
+     * match rows the MV predicate cannot).
+     */
+    const expectedKey: string = route.keyForValue(
+      projectId,
+      scopeAttributeValue,
+    );
+    const scopeKeys: Array<string> = Array.isArray(scope.entityKeys)
+      ? scope.entityKeys
+      : [];
+    if (scopeKeys.length !== 1 || scopeKeys[0] !== expectedKey) {
+      return null;
+    }
+
+    return { route, keys: [expectedKey] };
+  }
+
+  private stripEntityFilterAndTimeFromQuery(query: unknown): typeof query {
     if (!query || typeof query !== "object") {
       return query;
     }
     const out: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(query as Record<string, unknown>)) {
-      if (k === "time" || k === "attributes") {
+      if (k === "time" || k === "attributes" || k === "entityScope") {
         continue;
       }
       out[k] = v;