@oneuptime/common 11.5.9 → 11.5.10

package/build/dist/Server/Services/MetricService.js

@@ -7,8 +7,13 @@ import { getQuerySettings } from "../Utils/AnalyticsDatabase/QuerySettingsHelper
 import AggregationType, { getPercentileLevel, isPercentileAggregation, } from "../../Types/BaseDatabase/AggregationType";
 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 { 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 TelemetryEntityService from "./TelemetryEntityService";
+import EntityType from "../../Types/Telemetry/EntityType";
 import ObjectID from "../../Types/ObjectID";
 import logger from "../Utils/Logger";
 /*
@@ -30,6 +35,42 @@ const MAX_GROUP_BY_ATTRIBUTE_KEYS = 10;
 const MAX_GROUP_BY_ATTRIBUTE_KEY_LENGTH = 256;
 const POINT_TYPE_CACHE_TTL_MS = 10 * 60 * 1000;
 const POINT_TYPE_CACHE_MAX_ENTRIES = 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 = 60 * 1000;
+const SERVICE_ENTITY_KEYS_CACHE_MAX_ENTRIES = 5000;
+const ENTITY_MV_ROUTES = [
+    {
+        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 {
     constructor(clickhouseDatabase) {
         super({ modelType: Metric, database: clickhouseDatabase });
@@ -48,6 +89,23 @@ export class MetricService extends AnalyticsDatabaseService {
          */
         this.pointTypeHintByAggregate = new WeakMap();
         this.inFlightPointTypeLookups = 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).
+         */
+        this.serviceEntityKeysHintByAggregate = 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.
+         */
+        this.serviceEntityKeysCache = new Map();
+        this.inFlightServiceEntityKeyLookups = new Map();
     }
     async aggregateBy(aggregateBy) {
         /*
@@ -64,9 +122,197 @@ export class MetricService extends AnalyticsDatabaseService {
                 aggregateBy.groupByAttributeKeys.length === 0)) {
             const pointType = 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 = 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.
+     */
+    async resolveServiceEntityKeysHint(aggregateBy) {
+        const queryRecord = aggregateBy.query || {};
+        // service + entityScope is never routed (see the entity-MV builder).
+        if (queryRecord["entityScope"] !== undefined &&
+            queryRecord["entityScope"] !== null) {
+            return null;
+        }
+        const attrs = queryRecord["attributes"];
+        if (!attrs || typeof attrs !== "object") {
+            return null;
+        }
+        const attrEntries = Object.entries(attrs);
+        if (attrEntries.length !== 1) {
+            return null;
+        }
+        const [attrKey, attrValue] = attrEntries[0];
+        if (attrKey !== "resource.service.name" ||
+            typeof attrValue !== "string" ||
+            !attrValue) {
+            return null;
+        }
+        const projectIdValue = queryRecord["projectId"];
+        let projectId = "";
+        if (projectIdValue instanceof ObjectID) {
+            projectId = projectIdValue.toString();
+        }
+        else if (typeof projectIdValue === "string") {
+            projectId = projectIdValue;
+        }
+        if (!projectId) {
+            return null;
+        }
+        const cacheKey = `${projectId}|${canonicalizeEntityValue(attrValue)}`;
+        const cached = this.serviceEntityKeysCache.get(cacheKey);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.keys;
+        }
+        const inFlight = this.inFlightServiceEntityKeyLookups.get(cacheKey);
+        if (inFlight) {
+            return inFlight;
+        }
+        const lookup = this.lookupServiceEntityKeys(projectId, attrValue)
+            .then((keys) => {
+            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).
+     */
+    async lookupServiceEntityKeys(projectId, serviceName) {
+        try {
+            const canonicalName = canonicalizeEntityValue(serviceName);
+            const rows = 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 = new Set();
+            for (const row of rows) {
+                const identifying = row.identifyingAttributes || {};
+                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 = 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 [];
+        }
+    }
+    evictExpiredServiceEntityKeyCacheEntries() {
+        if (this.serviceEntityKeysCache.size < SERVICE_ENTITY_KEYS_CACHE_MAX_ENTRIES) {
+            return;
+        }
+        const now = 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 = this.serviceEntityKeysCache
+                .keys()
+                .next().value;
+            if (oldestKey === undefined) {
+                break;
+            }
+            this.serviceEntityKeysCache.delete(oldestKey);
+        }
+    }
     async resolveMetricPointType(aggregateBy) {
         const metricName = this.getExactMetricNameFromQuery(aggregateBy.query);
         if (!metricName) {
@@ -244,6 +490,117 @@ export class MetricService extends AnalyticsDatabaseService {
         });
         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.
+     */
+    getSanitizedTopK(aggregateBy) {
+        const topK = aggregateBy.topK;
+        if (!topK) {
+            return null;
+        }
+        const count = 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.
+     */
+    appendRawGroupExpressionList(statement, groupByKeys, attributeGroupKeys) {
+        let isFirst = 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.)
+     */
+    appendTopKGroupRestriction(data) {
+        const statement = data.statement;
+        const aggregationColumn = 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.
+     */
+    appendTotalGroupsColumn(data) {
+        const 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.
@@ -260,10 +617,11 @@ export class MetricService extends AnalyticsDatabaseService {
      * 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.
      */
     async deleteBy(deleteBy) {
         await super.deleteBy(deleteBy);
@@ -374,11 +732,12 @@ export class MetricService extends AnalyticsDatabaseService {
         const attributeGroupKeys = this.getSanitizedGroupByAttributeKeys(aggregateBy);
         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
@@ -388,9 +747,9 @@ export class MetricService extends AnalyticsDatabaseService {
              */
             if (attributeGroupKeys.length === 0 &&
                 !this.isDistributionMetricAggregate(aggregateBy)) {
-                const hostMvStatement = this.tryBuildHostAggregateMVStatement(aggregateBy);
-                if (hostMvStatement) {
-                    return hostMvStatement;
+                const entityMvStatement = this.tryBuildEntityAggregateMVStatement(aggregateBy);
+                if (entityMvStatement) {
+                    return entityMvStatement;
                 }
                 const mvStatement = this.tryBuildMinuteAggregateMVStatement(aggregateBy);
                 if (mvStatement) {
@@ -528,12 +887,41 @@ export class MetricService extends AnalyticsDatabaseService {
          * attribute combination.
          */
         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 = this.getSanitizedTopK(aggregateBy);
+        const percentileApplyTopK = 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);
         statement.append(` FROM ${databaseName}.${this.model.tableName} WHERE TRUE `);
         statement.append(whereStatement);
         statement.append(this.getRetentionReadFilter());
+        if (percentileApplyTopK) {
+            this.appendTopKGroupRestriction({
+                statement,
+                databaseName,
+                aggregateBy,
+                topK: percentileTopK,
+                groupByKeys,
+                attributeGroupKeys,
+            });
+        }
         statement.append(SQL `) `);
         /*
          * `Total` collapses the window into one row per group: the timestamp
@@ -574,16 +962,23 @@ export class MetricService extends AnalyticsDatabaseService {
         }} `);
         /*
          * 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({
-            additionalSettings: {
-                optimize_aggregation_in_order: 1,
-                optimize_move_to_prewhere: 1,
-                max_threads: 4,
-            },
+            maxExecutionTimeInSeconds: 45,
+            timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
+            additionalSettings: Object.assign({ optimize_aggregation_in_order: 1, optimize_move_to_prewhere: 1, max_threads: 4 }, (percentileApplyTopK ? { transform_null_in: 1 } : {})),
         }));
         const columns = [
             aggregationColumn,
@@ -691,11 +1086,27 @@ export class MetricService extends AnalyticsDatabaseService {
         const sortStatement = this.statementGenerator.toSortStatement(aggregateBy.sort);
         const aggregationExpression = this.getDistributionAwareAggregationExpression(aggregateBy.aggregationType, aggregationColumn);
         const 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 = this.getSanitizedTopK(aggregateBy);
+        const scalarApplyTopK = Boolean(scalarTopK && (groupByKeys.length > 0 || attributeGroupKeys.length > 0));
         statement.append(`SELECT ${aggregationExpression} as ${aggregationColumn}, ${AggregateUtil.buildBucketTimestampSelect(resolvedInterval, aggregationTimestampColumn)}`);
         for (const key of groupByKeys) {
             statement.append(`, ${key}`);
         }
         this.appendAttributeGroupMapColumn(statement, attributeGroupKeys);
+        if (scalarApplyTopK) {
+            this.appendTotalGroupsColumn({
+                statement,
+                databaseName,
+                aggregateBy,
+                groupByKeys,
+                attributeGroupKeys,
+            });
+        }
         if (attributeGroupKeys.length > 0) {
             /*
              * Subquery form: extract the selected keys into `__attr_grp_<i>`
@@ -722,12 +1133,32 @@ export class MetricService extends AnalyticsDatabaseService {
             statement.append(` FROM ${databaseName}.${this.model.tableName} WHERE TRUE `);
             statement.append(whereStatement);
             statement.append(this.getRetentionReadFilter());
+            if (scalarApplyTopK) {
+                this.appendTopKGroupRestriction({
+                    statement,
+                    databaseName,
+                    aggregateBy,
+                    topK: scalarTopK,
+                    groupByKeys,
+                    attributeGroupKeys,
+                });
+            }
             statement.append(SQL `) `);
         }
         else {
             statement.append(` FROM ${databaseName}.${this.model.tableName} WHERE TRUE `);
             statement.append(whereStatement);
             statement.append(this.getRetentionReadFilter());
+            if (scalarApplyTopK) {
+                this.appendTopKGroupRestriction({
+                    statement,
+                    databaseName,
+                    aggregateBy,
+                    topK: scalarTopK,
+                    groupByKeys,
+                    attributeGroupKeys,
+                });
+            }
         }
         /*
          * `Total` drops the time bucket from GROUP BY (it becomes an
@@ -765,12 +1196,14 @@ export class MetricService extends AnalyticsDatabaseService {
             value: Number(aggregateBy.skip),
             type: TableColumnType.Number,
         }} `);
+        /*
+         * 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({
-            additionalSettings: {
-                optimize_aggregation_in_order: 1,
-                optimize_move_to_prewhere: 1,
-                max_threads: 4,
-            },
+            maxExecutionTimeInSeconds: 45,
+            timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
+            additionalSettings: Object.assign({ optimize_aggregation_in_order: 1, optimize_move_to_prewhere: 1, max_threads: 4 }, (scalarApplyTopK ? { transform_null_in: 1 } : {})),
         }));
         const columns = [
             aggregationColumn,
@@ -802,10 +1235,28 @@ export class MetricService extends AnalyticsDatabaseService {
         const innerWhereStatement = this.statementGenerator.toWhereStatement(this.getMutableMetricInnerQuery(aggregateBy.query));
         const outerWhereStatement = this.statementGenerator.toWhereStatement(aggregateBy.query);
         const sortStatement = this.statementGenerator.toSortStatement(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 = this.getSanitizedTopK(aggregateBy);
+        const mutableGroupByKeys = aggregateBy.groupBy
+            ? Object.keys(aggregateBy.groupBy)
+            : [];
+        const mutableApplyTopK = Boolean(mutableTopK && mutableGroupByKeys.length > 0);
         const 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 (
             SELECT
@@ -838,6 +1289,28 @@ export class MetricService extends AnalyticsDatabaseService {
         `)
             .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`
@@ -884,11 +1357,16 @@ export class MetricService extends AnalyticsDatabaseService {
             value: Number(aggregateBy.skip),
             type: TableColumnType.Number,
         }}`);
+        /*
+         * 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({
-            additionalSettings: {
-                optimize_move_to_prewhere: 1,
-                max_threads: 4,
-            },
+            maxExecutionTimeInSeconds: 45,
+            timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
+            additionalSettings: Object.assign({ optimize_move_to_prewhere: 1, max_threads: 4 }, (mutableApplyTopK ? { transform_null_in: 1 } : {})),
         }));
         logger.debug("Mutable metric aggregate statement", {
             metricName: metricName || "",
@@ -901,6 +1379,51 @@ export class MetricService extends AnalyticsDatabaseService {
             columns: select.columns,
         };
     }
+    /**
+     * 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).
+     */
+    buildMutableMetricDedupSource(databaseName, aggregateBy) {
+        const source = 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;
+    }
     getMutableMetricInnerQuery(query) {
         const queryRecord = query;
         const allowedInnerKeys = [
@@ -1012,10 +1535,11 @@ export class MetricService extends AnalyticsDatabaseService {
         });
         /*
          * 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;
@@ -1058,7 +1582,6 @@ export class MetricService extends AnalyticsDatabaseService {
             this.useDefaultDatabase();
         }
         const databaseName = this.database.getDatasourceOptions().database;
-        const intervalLower = interval.toLowerCase();
         let mergedExpr;
         if (aggType === AggregationType.Sum) {
             mergedExpr = `sumMerge(valueSumState)`;
@@ -1085,7 +1608,7 @@ export class MetricService extends AnalyticsDatabaseService {
         const nonTimeWhere = this.statementGenerator.toWhereStatement(this.stripTimeFromQuery(aggregateBy.query));
         const sortStatement = this.statementGenerator.toSortStatement(aggregateBy.sort);
         const statement = SQL ``;
-        statement.append(`SELECT ${mergedExpr} as value, date_trunc('${intervalLower}', toStartOfInterval(bucketTime, INTERVAL 1 ${intervalLower})) as time`);
+        statement.append(`SELECT ${mergedExpr} as value, ${AggregateUtil.buildBucketTimestampExpression(interval, "bucketTime")} as time`);
         statement.append(SQL ` FROM ${databaseName}.MetricItemAggMV1m`);
         statement.append(` WHERE bucketTime >= toDateTime('${this.formatDateTime(aggregateBy.startTimestamp)}') AND bucketTime <= toDateTime('${this.formatDateTime(aggregateBy.endTimestamp)}')${this.getRetentionReadFilter()}`);
         statement.append(SQL ` `).append(nonTimeWhere);
@@ -1100,6 +1623,8 @@ export class MetricService extends AnalyticsDatabaseService {
             type: TableColumnType.Number,
         }} `);
         statement.append(getQuerySettings({
+            maxExecutionTimeInSeconds: 45,
+            timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
             additionalSettings: {
                 optimize_aggregation_in_order: 1,
                 optimize_move_to_prewhere: 1,
@@ -1121,30 +1646,55 @@ export class MetricService extends AnalyticsDatabaseService {
         };
     }
     /*
-     * 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.
      */
-    tryBuildHostAggregateMVStatement(aggregateBy) {
+    tryBuildEntityAggregateMVStatement(aggregateBy) {
         const aggType = aggregateBy.aggregationType;
         const supported = [
             AggregationType.Sum,
@@ -1167,84 +1717,57 @@ export class MetricService extends AnalyticsDatabaseService {
             aggregateBy.groupByAttributeKeys.length > 0) {
             return null;
         }
+        const queryRecord = aggregateBy.query || {};
         /*
-         * 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.
+         * 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 queryRecord = aggregateBy.query || {};
-        const attrs = queryRecord["attributes"];
-        if (!attrs || typeof attrs !== "object") {
-            return null;
+        const projectIdValue = queryRecord["projectId"];
+        let projectId = "";
+        if (projectIdValue instanceof ObjectID) {
+            projectId = projectIdValue.toString();
         }
-        const attrEntries = Object.entries(attrs);
-        if (attrEntries.length !== 1) {
-            return null;
+        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 = 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 = [
             "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 = 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 = queryRecord["projectId"];
-        let projectId = "";
-        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 = keyForHost(projectId, hostIdentifier);
         const interval = AggregateUtil.getAggregationInterval({
             startDate: aggregateBy.startTimestamp,
             endDate: aggregateBy.endTimestamp,
             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;
@@ -1253,7 +1776,6 @@ export class MetricService extends AnalyticsDatabaseService {
             this.useDefaultDatabase();
         }
         const databaseName = this.database.getDatasourceOptions().database;
-        const intervalLower = interval.toLowerCase();
         let mergedExpr;
         if (aggType === AggregationType.Sum) {
             mergedExpr = `sumMerge(valueSumState)`;
@@ -1271,22 +1793,32 @@ export class MetricService extends AnalyticsDatabaseService {
             mergedExpr = `if(countMerge(valueCountState) = 0, 0, sumMerge(valueSumState) / countMerge(valueCountState))`;
         }
         /*
-         * 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 = this.stripAttributesAndTimeFromQuery(aggregateBy.query);
+        const filteredQuery = this.stripEntityFilterAndTimeFromQuery(aggregateBy.query);
         const nonTimeWhere = this.statementGenerator.toWhereStatement(filteredQuery);
         const sortStatement = this.statementGenerator.toSortStatement(aggregateBy.sort);
         const statement = SQL ``;
-        statement.append(`SELECT ${mergedExpr} as value, date_trunc('${intervalLower}', toStartOfInterval(bucketTime, INTERVAL 1 ${intervalLower})) as time`);
-        statement.append(SQL ` FROM ${databaseName}.MetricItemAggMV1mByHostV2`);
+        statement.append(`SELECT ${mergedExpr} as value, ${AggregateUtil.buildBucketTimestampExpression(interval, "bucketTime")} as time`);
+        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`);
         statement.append(SQL ` ORDER BY `).append(sortStatement);
@@ -1299,13 +1831,15 @@ export class MetricService extends AnalyticsDatabaseService {
             type: TableColumnType.Number,
         }} `);
         statement.append(getQuerySettings({
+            maxExecutionTimeInSeconds: 45,
+            timeoutOverflowMode: this.getTimeoutOverflowMode(aggregateBy),
             additionalSettings: {
                 optimize_aggregation_in_order: 1,
                 optimize_move_to_prewhere: 1,
                 max_threads: 4,
             },
         }));
-        logger.debug(`${this.model.tableName} Host MV Aggregate Statement`, {
+        logger.debug(`${this.model.tableName} Entity MV Aggregate Statement`, {
             tableName: this.model.tableName,
         });
         logger.debug(statement, {
@@ -1319,13 +1853,115 @@ export class MetricService extends AnalyticsDatabaseService {
             ],
         };
     }
-    stripAttributesAndTimeFromQuery(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).
+     */
+    resolveEntityMVRouteAndKeys(aggregateBy, queryRecord, projectId) {
+        var _a;
+        const attrs = queryRecord["attributes"];
+        if (attrs !== undefined && attrs !== null && typeof attrs !== "object") {
+            return null;
+        }
+        const attrEntries = attrs && typeof attrs === "object"
+            ? Object.entries(attrs)
+            : [];
+        if (attrEntries.length > 1) {
+            return null;
+        }
+        const scopeValue = queryRecord["entityScope"];
+        const scope = scopeValue !== undefined &&
+            scopeValue !== null &&
+            typeof scopeValue === "object"
+            ? scopeValue
+            : 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 = ENTITY_MV_ROUTES.find((candidate) => {
+                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((_a = scope.attributeValue) !== null && _a !== void 0 ? _a : "") !== 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 = 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 = ENTITY_MV_ROUTES.find((candidate) => {
+            return candidate.attributeKey === scope.attributeKey;
+        });
+        if (!route || route.keyForValue === null) {
+            return null;
+        }
+        const scopeAttributeValue = 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 = route.keyForValue(projectId, scopeAttributeValue);
+        const scopeKeys = Array.isArray(scope.entityKeys)
+            ? scope.entityKeys
+            : [];
+        if (scopeKeys.length !== 1 || scopeKeys[0] !== expectedKey) {
+            return null;
+        }
+        return { route, keys: [expectedKey] };
+    }
+    stripEntityFilterAndTimeFromQuery(query) {
         if (!query || typeof query !== "object") {
             return query;
         }
         const out = {};
         for (const [k, v] of Object.entries(query)) {
-            if (k === "time" || k === "attributes") {
+            if (k === "time" || k === "attributes" || k === "entityScope") {
                 continue;
             }
             out[k] = v;