cds-caching 3.0.0 → 3.1.0

package/lib/support/CacheStatisticsHandler.js

@@ -26,15 +26,17 @@ class CacheStatisticsHandler {
             persistenceInterval: 10 * 1000, // 10 seconds 
             maxLatencies: 2000,
             maxKeyMetrics: 1000, // Track top accessed keys
+            maxTagMetrics: 1000, // Track top accessed tags
             maxMetricFieldLength: MAX_FIELD_LENGTH, // Cap per free-text KeyMetrics field
             keyMetricsEnabled: false,
+            tagMetricsEnabled: false,
             metricsEnabled: false, // Main metrics enabled flag (process default)
             ...options
         };
 
         /** @type {Map<string, object>} */
         this._buckets = new Map();
-        /** @type {Map<string, { metricsEnabled?: boolean, keyMetricsEnabled?: boolean }>} */
+        /** @type {Map<string, { metricsEnabled?: boolean, keyMetricsEnabled?: boolean, tagMetricsEnabled?: boolean }>} */
         this._overlays = new Map();
         /** Throwaway bucket for MTX writes outside a tenant context (discarded). */
         this._discardBucket = null;
@@ -71,6 +73,7 @@ class CacheStatisticsHandler {
             nativeErrors: 0,
             totalNativeOperations: 0,
             keyAccess: new Map(),
+            tagAccess: new Map(),
             startTime: Date.now(),
             lastReset: Date.now()
         };
@@ -134,13 +137,22 @@ class CacheStatisticsHandler {
         return this.options.keyMetricsEnabled === true;
     }
 
+    _tagMetricsOn(tenantId) {
+        const key = tenantId ?? this._bucketKey();
+        if (key && this._overlays.has(key)) {
+            const overlay = this._overlays.get(key);
+            if (overlay.tagMetricsEnabled !== undefined) return overlay.tagMetricsEnabled;
+        }
+        return this.options.tagMetricsEnabled === true;
+    }
+
     _isBucketEmpty(bucket) {
         const c = bucket?.current;
         if (!c) return true;
         return c.hits === 0 && c.misses === 0 && c.errors === 0
             && c.nativeSets === 0 && c.nativeGets === 0 && c.nativeDeletes === 0
             && c.nativeClears === 0 && c.nativeDeleteByTags === 0 && c.nativeErrors === 0
-            && c.keyAccess.size === 0;
+            && c.keyAccess.size === 0 && c.tagAccess.size === 0;
     }
 
     /**
@@ -153,7 +165,7 @@ class CacheStatisticsHandler {
             try {
                 if (isMultitenantMode()) {
                     await this.persistAllTenantMetrics();
-                } else if (this._metricsOn(DEFAULT_TENANT) || this._keyMetricsOn(DEFAULT_TENANT)) {
+                } else if (this._metricsOn(DEFAULT_TENANT) || this._keyMetricsOn(DEFAULT_TENANT) || this._tagMetricsOn(DEFAULT_TENANT)) {
                     await this.persistMetrics();
                 }
             } catch (error) {
@@ -184,6 +196,17 @@ class CacheStatisticsHandler {
         }
     }
 
+    enableTagMetrics(enabled) {
+        if (isMultitenantMode() && hasTenantContext()) {
+            const t = currentTenant();
+            const overlay = this._overlays.get(t) || {};
+            overlay.tagMetricsEnabled = enabled;
+            this._overlays.set(t, overlay);
+        } else {
+            this.options.tagMetricsEnabled = enabled;
+        }
+    }
+
     enableMetrics(enabled) {
         if (isMultitenantMode() && hasTenantContext()) {
             const t = currentTenant();
@@ -218,11 +241,16 @@ class CacheStatisticsHandler {
             this.recordKeyAccess(key, 'hit', { ...metadata, latency });
         }
 
+        // Record tag access if tag metrics is enabled (independent of main metrics)
+        if (this._tagMetricsOn()) {
+            this._recordTagsAccess(metadata.tags, 'hit', { ...metadata, latency });
+        }
+
         // Emit OTel metric (independent of metricsEnabled)
         telemetry.recordHit(latency, { 'cache.name': this.options.cache });
 
         // Log for debugging
-        this.log.debug(`Recorded HIT for key: ${key}, latency: ${latency}ms, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}`);
+        this.log.debug(`Recorded HIT for key: ${key}, latency: ${latency}ms, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}, tagMetrics: ${this._tagMetricsOn()}`);
     }
 
     /**
@@ -248,11 +276,16 @@ class CacheStatisticsHandler {
             this.recordKeyAccess(key, 'miss', { ...metadata, latency });
         }
 
+        // Record tag access if tag metrics is enabled (independent of main metrics)
+        if (this._tagMetricsOn()) {
+            this._recordTagsAccess(metadata.tags, 'miss', { ...metadata, latency });
+        }
+
         // Emit OTel metric (independent of metricsEnabled)
         telemetry.recordMiss(latency, { 'cache.name': this.options.cache });
 
         // Log for debugging
-        this.log.debug(`Recorded MISS for key: ${key}, latency: ${latency}ms, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}`);
+        this.log.debug(`Recorded MISS for key: ${key}, latency: ${latency}ms, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}, tagMetrics: ${this._tagMetricsOn()}`);
     }
 
     /**
@@ -279,11 +312,15 @@ class CacheStatisticsHandler {
             this.recordKeyAccess(key, 'set', { ...metadata, latency });
         }
 
+        if (this._tagMetricsOn()) {
+            this._recordTagsAccess(metadata.tags, 'set', { ...metadata, latency });
+        }
+
         // Emit OTel metric (independent of metricsEnabled)
         telemetry.recordSet({ 'cache.name': this.options.cache });
 
         // Log for debugging
-        this.log.debug(`Recorded SET for key: ${key}, latency: ${latency}ms, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}`);
+        this.log.debug(`Recorded SET for key: ${key}, latency: ${latency}ms, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}, tagMetrics: ${this._tagMetricsOn()}`);
     }
 
     /**
@@ -310,11 +347,15 @@ class CacheStatisticsHandler {
             this.recordKeyAccess(key, 'delete', { ...metadata, latency });
         }
 
+        if (this._tagMetricsOn()) {
+            this._recordTagsAccess(metadata.tags, 'delete', { ...metadata, latency });
+        }
+
         // Emit OTel metric (independent of metricsEnabled)
         telemetry.recordDelete({ 'cache.name': this.options.cache });
 
         // Log for debugging
-        this.log.debug(`Recorded DELETE for key: ${key}, latency: ${latency}ms, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}`);
+        this.log.debug(`Recorded DELETE for key: ${key}, latency: ${latency}ms, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}, tagMetrics: ${this._tagMetricsOn()}`);
     }
 
     /**
@@ -341,11 +382,15 @@ class CacheStatisticsHandler {
             this.recordKeyAccess(key, 'nativeSet', metadata);
         }
 
+        if (this._tagMetricsOn()) {
+            this._recordTagsAccess(metadata.tags, 'nativeSet', metadata);
+        }
+
         // Emit OTel metric (independent of metricsEnabled)
         telemetry.recordSet({ 'cache.name': this.options.cache });
 
         // Log for debugging
-        this.log.debug(`Recorded NATIVE SET for key: ${key}, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}`);
+        this.log.debug(`Recorded NATIVE SET for key: ${key}, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}, tagMetrics: ${this._tagMetricsOn()}`);
     }
 
     /**
@@ -372,8 +417,12 @@ class CacheStatisticsHandler {
             this.recordKeyAccess(key, hit ? 'nativeHit' : 'nativeMiss', metadata);
         }
 
+        if (this._tagMetricsOn()) {
+            this._recordTagsAccess(metadata.tags, hit ? 'nativeHit' : 'nativeMiss', metadata);
+        }
+
         // Log for debugging
-        this.log.debug(`Recorded NATIVE GET for key: ${key}, hit: ${hit}, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}`);
+        this.log.debug(`Recorded NATIVE GET for key: ${key}, hit: ${hit}, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}, tagMetrics: ${this._tagMetricsOn()}`);
     }
 
     /**
@@ -400,11 +449,15 @@ class CacheStatisticsHandler {
             this.recordKeyAccess(key, 'nativeDelete', metadata);
         }
 
+        if (this._tagMetricsOn()) {
+            this._recordTagsAccess(metadata.tags, 'nativeDelete', metadata);
+        }
+
         // Emit OTel metric (independent of metricsEnabled)
         telemetry.recordDelete({ 'cache.name': this.options.cache });
 
         // Log for debugging
-        this.log.debug(`Recorded NATIVE DELETE for key: ${key}, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}`);
+        this.log.debug(`Recorded NATIVE DELETE for key: ${key}, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}, tagMetrics: ${this._tagMetricsOn()}`);
     }
 
     /**
@@ -748,6 +801,157 @@ class CacheStatisticsHandler {
         }
     }
 
+    /**
+     * Normalize tags from metadata into a deduped list of resolved tag strings.
+     * @param {string[]|undefined} tags
+     * @returns {string[]}
+     * @private
+     */
+    _normalizeTags(tags) {
+        if (!Array.isArray(tags) || tags.length === 0) return [];
+        const seen = new Set();
+        const out = [];
+        for (const tag of tags) {
+            if (typeof tag !== 'string' || !tag) continue;
+            if (seen.has(tag)) continue;
+            seen.add(tag);
+            out.push(tag);
+        }
+        return out;
+    }
+
+    /**
+     * Record access for every tag on a metadata object.
+     * @param {string[]|undefined} tags
+     * @param {string} operation
+     * @param {object} metadata
+     * @private
+     */
+    _recordTagsAccess(tags, operation, metadata = {}) {
+        for (const tag of this._normalizeTags(tags)) {
+            this.recordTagAccess(tag, operation, metadata);
+        }
+    }
+
+    /**
+     * Record tag access with latency tracking.
+     * A hit on an entry with N tags increments N tag rows — tag totals may exceed cache totals.
+     * @param {string} tag - resolved tag string
+     * @param {string} operation - hit|miss|set|delete|nativeHit|nativeMiss|nativeSet|nativeDelete
+     * @param {object} metadata
+     */
+    recordTagAccess(tag, operation, metadata = {}) {
+        if (!tag) {
+            this.log.warn('recordTagAccess called with null/undefined tag');
+            return;
+        }
+
+        if (!this.stats.current.tagAccess.has(tag)) {
+            this.stats.current.tagAccess.set(tag, {
+                tag,
+                hits: 0,
+                misses: 0,
+                sets: 0,
+                deletes: 0,
+                errors: 0,
+                totalRequests: 0,
+                hitRatio: 0,
+                cacheEfficiency: 0,
+                hitLatencies: [],
+                missLatencies: [],
+                setLatencies: [],
+                deleteLatencies: [],
+                avgHitLatency: 0,
+                avgMissLatency: 0,
+                avgReadThroughLatency: 0,
+                minHitLatency: Infinity,
+                maxHitLatency: 0,
+                minMissLatency: Infinity,
+                maxMissLatency: 0,
+                throughput: 0,
+                errorRate: 0,
+                nativeHits: 0,
+                nativeMisses: 0,
+                nativeSets: 0,
+                nativeDeletes: 0,
+                nativeErrors: 0,
+                totalNativeOperations: 0,
+                nativeThroughput: 0,
+                nativeErrorRate: 0,
+                lastAccess: Date.now(),
+                timestamp: Date.now(),
+            });
+        }
+
+        const tagStats = this.stats.current.tagAccess.get(tag);
+        tagStats.lastAccess = Date.now();
+
+        switch (operation) {
+            case 'hit':
+            case 'miss':
+            case 'set':
+            case 'delete': {
+                const pluralMap = { hit: 'hits', miss: 'misses', set: 'sets', delete: 'deletes' };
+                const prop = pluralMap[operation];
+                if (prop) tagStats[prop]++;
+                tagStats.totalRequests = tagStats.hits + tagStats.misses;
+                if (metadata.latency !== undefined) {
+                    this.recordKeyLatency(tagStats, operation, metadata.latency);
+                }
+                break;
+            }
+            case 'nativeHit':
+            case 'nativeMiss':
+            case 'nativeSet':
+            case 'nativeDelete': {
+                const nativeProperty = {
+                    nativeHit: 'nativeHits',
+                    nativeMiss: 'nativeMisses',
+                    nativeSet: 'nativeSets',
+                    nativeDelete: 'nativeDeletes',
+                }[operation];
+                if (!nativeProperty) return;
+                tagStats[nativeProperty]++;
+                tagStats.totalNativeOperations = tagStats.nativeHits + tagStats.nativeMisses + tagStats.nativeSets + tagStats.nativeDeletes;
+                break;
+            }
+            default:
+                this.log.warn(`Unknown tag operation type: ${operation}`);
+                return;
+        }
+
+        const totalReadThrough = tagStats.hits + tagStats.misses;
+        if (totalReadThrough > 0) {
+            tagStats.hitRatio = (tagStats.hits / totalReadThrough) * 100;
+        }
+
+        const uptimeMs = Date.now() - tagStats.timestamp;
+        if (uptimeMs > 0) {
+            tagStats.throughput = (tagStats.totalRequests / uptimeMs) * 1000;
+            tagStats.nativeThroughput = (tagStats.totalNativeOperations / uptimeMs) * 1000;
+        }
+
+        if (tagStats.totalRequests > 0) {
+            tagStats.errorRate = (tagStats.errors / tagStats.totalRequests) * 100;
+        }
+        if (tagStats.totalNativeOperations > 0) {
+            tagStats.nativeErrorRate = (tagStats.nativeErrors / tagStats.totalNativeOperations) * 100;
+        }
+        if (tagStats.avgHitLatency > 0 && tagStats.avgMissLatency > 0) {
+            tagStats.cacheEfficiency = tagStats.avgMissLatency / tagStats.avgHitLatency;
+        }
+
+        if (this.stats.current.tagAccess.size > this.options.maxTagMetrics) {
+            const entries = Array.from(this.stats.current.tagAccess.entries());
+            entries.sort((a, b) => {
+                const totalA = a[1].totalRequests + a[1].totalNativeOperations;
+                const totalB = b[1].totalRequests + b[1].totalNativeOperations;
+                return totalB - totalA;
+            });
+            this.stats.current.tagAccess = new Map(entries.slice(0, this.options.maxTagMetrics));
+        }
+    }
+
     /**
      * Record latency for a specific key operation
      * @param {object} keyStats - the key statistics object
@@ -999,7 +1203,7 @@ class CacheStatisticsHandler {
      */
     async persistMetrics() {
         // Only persist if at least one type of metrics is enabled
-        if (!this._metricsOn() && !this._keyMetricsOn()) {
+        if (!this._metricsOn() && !this._keyMetricsOn() && !this._tagMetricsOn()) {
             this.log.debug(`PersistStats called but all statistics are disabled for cache ${this.options.cache}`);
             return;
         }
@@ -1026,6 +1230,7 @@ class CacheStatisticsHandler {
         try {
             await this.persistenceManager.persistHourlyStats(stats, hourlyId, hourlyTimestamp, this._metricsOn());
             await this.persistenceManager.persistKeyMetrics(this.stats.current.keyAccess, this._keyMetricsOn());
+            await this.persistenceManager.persistTagMetrics(this.stats.current.tagAccess, this._tagMetricsOn());
 
             this.resetCurrentStats(tenantKey);
 
@@ -1157,6 +1362,24 @@ class CacheStatisticsHandler {
         return this.stats.current.keyAccess;
     }
 
+    async getTagMetrics(tag, from, to) {
+        if (!this._tagMetricsOn() || !isPluginModelAvailable()) return null;
+        const query = SELECT.from("plugin_cds_caching_TagMetrics")
+            .where({ cache: this.options.cache, tag });
+
+        if (from) query.and({ timestamp: { '>=': from.toISOString() } });
+        if (to) query.and({ timestamp: { '<=': to.toISOString() } });
+
+        query.orderBy({ timestamp: 'desc' });
+
+        return await query;
+    }
+
+    async getCurrentTagMetrics() {
+        if (!this._tagMetricsOn()) return null;
+        return this.stats.current.tagAccess;
+    }
+
     async getCurrentStats() {
         if (!this._metricsOn()) return null;
 
@@ -1259,10 +1482,10 @@ class CacheStatisticsHandler {
      * Manually trigger persistence (for testing and debugging)
      */
     async triggerPersistence() {
-        this.log.info(`Manually triggering persistence for cache ${this.options.cache}, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}`);
+        this.log.info(`Manually triggering persistence for cache ${this.options.cache}, enabled: ${this._metricsOn()}, keyMetrics: ${this._keyMetricsOn()}, tagMetrics: ${this._tagMetricsOn()}`);
         if (isMultitenantMode()) {
             await this.persistAllTenantMetrics();
-        } else if (this._metricsOn() || this._keyMetricsOn()) {
+        } else if (this._metricsOn() || this._keyMetricsOn() || this._tagMetricsOn()) {
             await this.persistMetrics();
         } else {
             this.log.info(`Persistence skipped - all statistics are disabled for cache ${this.options.cache}`);
@@ -1276,6 +1499,7 @@ class CacheStatisticsHandler {
         return {
             metricsEnabled: this._metricsOn(),
             keyMetricsEnabled: this._keyMetricsOn(),
+            tagMetricsEnabled: this._tagMetricsOn(),
             intervalExists: this.persistInterval !== null,
             lastPersisted: this.stats.lastPersisted,
             persistenceInterval: this.options.persistenceInterval,
@@ -1297,6 +1521,19 @@ class CacheStatisticsHandler {
         this.resetCurrentStats();
     }
 
+    async clearTagMetrics() {
+        if (isPluginModelAvailable()) {
+            await this.persistenceManager.deleteTagMetrics();
+        }
+        // Clear only in-memory tag buckets; leave key/cache counters intact
+        for (const bucket of this._buckets.values()) {
+            bucket.current.tagAccess = new Map();
+        }
+        if (this._discardBucket) {
+            this._discardBucket.current.tagAccess = new Map();
+        }
+    }
+
     /**
      * Delete metrics (alias for clearMetrics for compatibility)
      * @returns {Promise<void>}
@@ -1312,6 +1549,14 @@ class CacheStatisticsHandler {
     async deleteKeyMetrics() {
         return this.clearKeyMetrics();
     }
+
+    /**
+     * Delete tag metrics (alias for clearTagMetrics for compatibility)
+     * @returns {Promise<void>}
+     */
+    async deleteTagMetrics() {
+        return this.clearTagMetrics();
+    }
 }
 
 module.exports = CacheStatisticsHandler; 

package/lib/support/RuntimeConfigurationManager.js

@@ -115,6 +115,23 @@ class RuntimeConfigurationManager {
         this.log.debug(`Key tracking ${enabled ? 'enabled' : 'disabled'} for cache ${this.cacheName}`);
     }
 
+    /**
+     * Update tag metrics enabled status in database
+     * @param {boolean} enabled - Whether tag metrics should be enabled
+     */
+    async setTagMetricsEnabled(enabled) {
+        if (!isPluginModelAvailable()) return;
+        if (isMultitenantMode() && !hasTenantContext()) {
+            this.log.debug(`Skipping setTagMetricsEnabled in MTX mode (no tenant context)`);
+            return;
+        }
+        const db = await cds.connect.to('db');
+        const { Caches } = cds.entities('plugin.cds_caching');
+        await db.update(Caches, this.cacheName).with({ tagMetricsEnabled: enabled });
+
+        this.log.debug(`Tag tracking ${enabled ? 'enabled' : 'disabled'} for cache ${this.cacheName}`);
+    }
+
 
 
     /**
@@ -125,7 +142,7 @@ class RuntimeConfigurationManager {
         const keyManagement = this._resolveKeyManagement();
 
         if (!isPluginModelAvailable()) {
-            return { metricsEnabled: false, keyMetricsEnabled: false, keyManagement, throwOnErrors: this.options.throwOnErrors };
+            return { metricsEnabled: false, keyMetricsEnabled: false, tagMetricsEnabled: false, keyManagement, throwOnErrors: this.options.throwOnErrors };
         }
 
         // In MTX mode without tenant context, skip DB access — return defaults
@@ -133,6 +150,7 @@ class RuntimeConfigurationManager {
             return {
                 metricsEnabled: false,
                 keyMetricsEnabled: false,
+                tagMetricsEnabled: false,
                 keyManagement,
                 throwOnErrors: this.options.throwOnErrors
             };
@@ -146,6 +164,7 @@ class RuntimeConfigurationManager {
             return {
                 metricsEnabled: cacheConfig?.metricsEnabled === true || cacheConfig?.metricsEnabled === 1 || false,
                 keyMetricsEnabled: cacheConfig?.keyMetricsEnabled === true || cacheConfig?.keyMetricsEnabled === 1 || false,
+                tagMetricsEnabled: cacheConfig?.tagMetricsEnabled === true || cacheConfig?.tagMetricsEnabled === 1 || false,
                 keyManagement,
                 throwOnErrors: this.options.throwOnErrors
             };
@@ -154,6 +173,7 @@ class RuntimeConfigurationManager {
             return {
                 metricsEnabled: false,
                 keyMetricsEnabled: false,
+                tagMetricsEnabled: false,
                 keyManagement,
                 throwOnErrors: this.options.throwOnErrors
             };

package/lib/support/StatisticsPersistenceManager.js

@@ -77,6 +77,31 @@ class StatisticsPersistenceManager {
         }
     }
 
+    /**
+     * Persist tag metrics
+     * @param {Map} tagAccess - Tag access data
+     * @param {boolean} tagMetricsEnabled - Whether tag metrics are enabled
+     */
+    async persistTagMetrics(tagAccess, tagMetricsEnabled) {
+        if (!tagMetricsEnabled || tagAccess.size === 0 || !isPluginModelAvailable()) return;
+
+        if (isMultitenantMode() && !hasTenantContext()) {
+            this.log.debug(`Skipping tag metrics persistence in MTX mode (no tenant context)`);
+            return;
+        }
+
+        this.log.debug(`Persisting ${tagAccess.size} tag access records for cache ${this.cacheName}`);
+
+        const { TagMetrics } = cds.entities('plugin.cds_caching');
+        for (const [tag, tagStats] of tagAccess) {
+            try {
+                await this._persistTagMetric(TagMetrics, tag, tagStats);
+            } catch (error) {
+                this.log.error(`Failed to persist tag metric for tag ${tag}:`, error);
+            }
+        }
+    }
+
     /**
      * Delete metrics for this cache
      */
@@ -107,6 +132,21 @@ class StatisticsPersistenceManager {
         this.log.debug(`Deleted key metrics for cache ${this.cacheName}`);
     }
 
+    /**
+     * Delete tag metrics for this cache
+     */
+    async deleteTagMetrics() {
+        if (!isPluginModelAvailable()) return;
+        if (isMultitenantMode() && !hasTenantContext()) {
+            this.log.debug(`Skipping deleteTagMetrics in MTX mode (no tenant context)`);
+            return;
+        }
+        const db = await cds.connect.to('db');
+        const { TagMetrics } = cds.entities('plugin.cds_caching');
+        await db.delete(TagMetrics).where({ cache: this.cacheName });
+        this.log.debug(`Deleted tag metrics for cache ${this.cacheName}`);
+    }
+
     /**
      * Create new hourly stats record
      * @private
@@ -235,7 +275,7 @@ class StatisticsPersistenceManager {
         // Calculate read-through performance metrics
         if (totalRequests > 0) {
             updatedStats.hitRatio = (updatedStats.hits / totalRequests) * 100;
-            updatedStats.throughput = totalRequests / (stats.uptimeMs / 1000);
+            updatedStats.throughput = stats.uptimeMs > 0 ? totalRequests / (stats.uptimeMs / 1000) : 0;
             updatedStats.errorRate = (updatedStats.errors / totalRequests) * 100;
         }
 
@@ -247,7 +287,7 @@ class StatisticsPersistenceManager {
         // Calculate native function performance metrics
         const totalNativeOps = updatedStats.totalNativeOperations;
         if (totalNativeOps > 0) {
-            updatedStats.nativeThroughput = totalNativeOps / (stats.uptimeMs / 1000);
+            updatedStats.nativeThroughput = stats.uptimeMs > 0 ? totalNativeOps / (stats.uptimeMs / 1000) : 0;
             updatedStats.nativeErrorRate = (updatedStats.nativeErrors / totalNativeOps) * 100;
         }
 
@@ -380,9 +420,9 @@ class StatisticsPersistenceManager {
                 : 0,
 
             // Update percentiles (use max/min of existing and current, with min using mergeMin)
-            minHitLatency: mergeMin(Number(existingKey.minHitLatency) || 0, keyStats.minHitLatency),
+            minHitLatency: mergeMin(Number(existingKey.minHitLatency) || 0, keyStats.minHitLatency === Infinity ? 0 : keyStats.minHitLatency),
             maxHitLatency: Math.max(Number(existingKey.maxHitLatency) || 0, keyStats.maxHitLatency || 0),
-            minMissLatency: mergeMin(Number(existingKey.minMissLatency) || 0, keyStats.minMissLatency),
+            minMissLatency: mergeMin(Number(existingKey.minMissLatency) || 0, keyStats.minMissLatency === Infinity ? 0 : keyStats.minMissLatency),
             maxMissLatency: Math.max(Number(existingKey.maxMissLatency) || 0, keyStats.maxMissLatency || 0)
         };
 
@@ -399,6 +439,99 @@ class StatisticsPersistenceManager {
             .set(updatedKeyStats)
             .where({ ID: keyId, cache: this.cacheName, keyName: key });
     }
+
+    /**
+     * Persist a single tag metric
+     * @private
+     */
+    async _persistTagMetric(TagMetrics, tag, tagStats) {
+        const tagId = `tag:${this.cacheName}:${tag}`;
+
+        const existingTag = await SELECT.one.from(TagMetrics)
+            .where({ ID: tagId, cache: this.cacheName, tag });
+
+        if (!existingTag) {
+            await this._createTagMetric(TagMetrics, tag, tagStats, tagId);
+        } else {
+            await this._updateTagMetric(TagMetrics, tag, tagStats, tagId, existingTag);
+        }
+    }
+
+    /**
+     * Create new tag metric record
+     * @private
+     */
+    async _createTagMetric(TagMetrics, tag, tagStats, tagId) {
+        await INSERT.into(TagMetrics).entries([{
+            ID: tagId,
+            cache: this.cacheName,
+            tag,
+            lastAccess: new Date(tagStats.lastAccess).toISOString(),
+            period: 'current',
+            hits: tagStats.hits,
+            misses: tagStats.misses,
+            errors: tagStats.errors,
+            totalRequests: tagStats.totalRequests,
+            hitRatio: tagStats.hitRatio,
+            cacheEfficiency: tagStats.cacheEfficiency,
+            avgHitLatency: tagStats.avgHitLatency || 0,
+            minHitLatency: tagStats.minHitLatency === Infinity ? 0 : tagStats.minHitLatency,
+            maxHitLatency: tagStats.maxHitLatency || 0,
+            avgMissLatency: tagStats.avgMissLatency || 0,
+            minMissLatency: tagStats.minMissLatency === Infinity ? 0 : tagStats.minMissLatency,
+            maxMissLatency: tagStats.maxMissLatency || 0,
+            avgReadThroughLatency: tagStats.avgReadThroughLatency || 0,
+            throughput: tagStats.throughput || 0,
+            errorRate: tagStats.errorRate || 0,
+            nativeHits: tagStats.nativeHits || 0,
+            nativeMisses: tagStats.nativeMisses || 0,
+            nativeSets: tagStats.nativeSets || 0,
+            nativeDeletes: tagStats.nativeDeletes || 0,
+            nativeErrors: tagStats.nativeErrors || 0,
+            totalNativeOperations: tagStats.totalNativeOperations || 0,
+            nativeThroughput: tagStats.nativeThroughput || 0,
+            nativeErrorRate: tagStats.nativeErrorRate || 0,
+            timestamp: new Date(tagStats.timestamp).toISOString(),
+        }]);
+    }
+
+    /**
+     * Update existing tag metric record
+     * @private
+     */
+    async _updateTagMetric(TagMetrics, tag, tagStats, tagId, existingTag) {
+        const totalHits = (Number(existingTag.hits) || 0) + tagStats.hits;
+        const totalMisses = (Number(existingTag.misses) || 0) + tagStats.misses;
+
+        const updatedTagStats = {
+            hits: totalHits,
+            misses: totalMisses,
+            errors: (Number(existingTag.errors) || 0) + (tagStats.errors || 0),
+            totalRequests: totalHits + totalMisses,
+            lastAccess: new Date(tagStats.lastAccess).toISOString(),
+            hitRatio: (totalHits + totalMisses) > 0 ? (totalHits / (totalHits + totalMisses)) * 100 : 0,
+            nativeHits: (Number(existingTag.nativeHits) || 0) + (tagStats.nativeHits || 0),
+            nativeMisses: (Number(existingTag.nativeMisses) || 0) + (tagStats.nativeMisses || 0),
+            nativeSets: (Number(existingTag.nativeSets) || 0) + (tagStats.nativeSets || 0),
+            nativeDeletes: (Number(existingTag.nativeDeletes) || 0) + (tagStats.nativeDeletes || 0),
+            nativeErrors: (Number(existingTag.nativeErrors) || 0) + (tagStats.nativeErrors || 0),
+            totalNativeOperations: (Number(existingTag.totalNativeOperations) || 0) + (tagStats.totalNativeOperations || 0),
+            avgHitLatency: totalHits > 0
+                ? (((Number(existingTag.avgHitLatency) || 0) * (Number(existingTag.hits) || 0)) + (tagStats.avgHitLatency * tagStats.hits)) / totalHits
+                : 0,
+            avgMissLatency: totalMisses > 0
+                ? (((Number(existingTag.avgMissLatency) || 0) * (Number(existingTag.misses) || 0)) + (tagStats.avgMissLatency * tagStats.misses)) / totalMisses
+                : 0,
+            minHitLatency: mergeMin(Number(existingTag.minHitLatency) || 0, tagStats.minHitLatency === Infinity ? 0 : tagStats.minHitLatency),
+            maxHitLatency: Math.max(Number(existingTag.maxHitLatency) || 0, tagStats.maxHitLatency || 0),
+            minMissLatency: mergeMin(Number(existingTag.minMissLatency) || 0, tagStats.minMissLatency === Infinity ? 0 : tagStats.minMissLatency),
+            maxMissLatency: Math.max(Number(existingTag.maxMissLatency) || 0, tagStats.maxMissLatency || 0),
+        };
+
+        await UPDATE(TagMetrics)
+            .set(updatedTagStats)
+            .where({ ID: tagId, cache: this.cacheName, tag });
+    }
 }
 
 module.exports = StatisticsPersistenceManager;