cds-caching 1.2.1 → 1.3.0

package/app/dashboard/view/Main.view.xml

@@ -0,0 +1,57 @@
+<mvc:View controllerName="cds.plugin.caching.dashboard.controller.Main" displayBlock="true"
+	xmlns="sap.m"
+	xmlns:mvc="sap.ui.core.mvc"
+	xmlns:core="sap.ui.core"
+	xmlns:l="sap.ui.layout"
+	xmlns:f="sap.f"
+	xmlns:fb="sap.ui.comp.filterbar"
+	xmlns:card="sap.f.cards"
+	xmlns:cssgrid="sap.ui.layout.cssgrid"
+	xmlns:viz="sap.viz.ui5.controls"
+	xmlns:viz.feeds="sap.viz.ui5.controls.common.feeds"
+	xmlns:viz.data="sap.viz.ui5.data" core:require="{
+		formatter: 'cds/plugin/caching/dashboard/model/formatter'
+	}">
+
+	<f:DynamicPage title="cds-caching – Dashboard" headerExpanded="true" headerPinned="true">
+		<f:title>
+			<f:DynamicPageTitle>
+				<f:heading>
+					<Title text="cds-caching – Dashboard" />
+				</f:heading>
+				<f:actions>
+					<Button type="Transparent" icon="sap-icon://refresh" text="Refresh" press="onRefresh" />
+				</f:actions>
+			</f:DynamicPageTitle>
+		</f:title>
+
+		<f:content>
+
+			<Table id="cachesList" headerText="Caching Services" mode="SingleSelectMaster" items="{path: '/Caches'}" itemPress="onCacheSelect" noDataText="No caches available">
+				<columns>
+					<Column>
+						<Text text="Name" />
+					</Column>
+					<Column>
+						<Text text="Statistic Tracking Enabled" />
+					</Column>
+					<Column>
+						<Text text="Key Tracking Enabled" />
+					</Column>
+				</columns>
+				<items>
+					<ColumnListItem type="Navigation">
+						<cells>
+							<Text text="{name}" />
+							<Text text="{path: 'metricsEnabled' }" />
+							<Text text="{path: 'keyMetricsEnabled' }" />
+						</cells>
+
+					</ColumnListItem>
+				</items>
+			</Table>
+		</f:content>
+
+	</f:DynamicPage>
+
+</mvc:View>

package/app/dashboard/view/SingleMetric.view.xml

@@ -0,0 +1,337 @@
+<mvc:View controllerName="cds.plugin.caching.dashboard.controller.SingleMetric"
+	xmlns="sap.m"
+	xmlns:mvc="sap.ui.core.mvc"
+	xmlns:core="sap.ui.core"
+	xmlns:l="sap.ui.layout"
+	xmlns:f="sap.f"
+	xmlns:fb="sap.ui.comp.filterbar"
+	xmlns:card="sap.f.cards"
+	xmlns:cssgrid="sap.ui.layout.cssgrid"
+	xmlns:viz="sap.viz.ui5.controls"
+	xmlns:viz.feeds="sap.viz.ui5.controls.common.feeds"
+	xmlns:viz.data="sap.viz.ui5.data"
+	xmlns:form="sap.ui.layout.form" core:require="{
+		formatter: 'cds/plugin/caching/dashboard/model/formatter'
+	}">
+
+	<f:DynamicPage title="Metric Details" showFooter="false">
+		<f:title>
+			<f:DynamicPageTitle>
+				<f:heading>
+					<Title text="Metric: {ui>/metricId}" />
+				</f:heading>
+				<f:actions>
+					<Button icon="sap-icon://refresh" text="Refresh" type="Transparent" press="onRefresh" />
+				</f:actions>
+				<f:navigationActions>
+					<OverflowToolbarButton type="Transparent" icon="sap-icon://full-screen" press="handleFullScreen" tooltip="Enter Full Screen Mode" visible="{= ${app>/layout} !== 'EndColumnFullScreen' }"/>
+					<OverflowToolbarButton type="Transparent" icon="sap-icon://exit-full-screen" press="handleExitFullScreen" tooltip="Exit Full Screen Mode" visible="{= ${app>/layout} === 'EndColumnFullScreen' }"/>
+					<OverflowToolbarButton type="Transparent" icon="sap-icon://decline" press="handleClose" tooltip="Close end column"/>
+				</f:navigationActions>
+			</f:DynamicPageTitle>
+		</f:title>
+
+		<f:content>
+			<cssgrid:CSSGrid id="metricMainGrid" width="100%">
+				<cssgrid:customLayout>
+					<cssgrid:ResponsiveColumnLayout />
+				</cssgrid:customLayout>
+
+				<!-- Read-Through Performance Section -->
+				<VBox renderType="Bare">
+					<layoutData>
+						<cssgrid:ResponsiveColumnItemLayoutData columns="24"/>
+					</layoutData>
+
+					<Title text="Read-Through Performance" titleStyle="H5" class="sapUiMediumMarginTop sapUiTinyMarginBottom" />
+
+					<f:GridContainer id="metricCacheThroughGrid" columnsChange=".onColumnsChange">
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Hit Ratio" subheader="Cache Hit Rate">
+							<TileContent unit="%">
+								<NumericContent valueColor="{formatter: 'formatter.formatHitRatioWithColor', path: 'ui>/hitRatio'}" value="{ path: 'ui>/hitRatio', type: 'sap.ui.model.type.Float', formatOptions: {style: 'short', decimals: 2}}" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Cache Efficiency" subheader="Performance Factor">
+							<TileContent unit="x">
+								<NumericContent valueColor="{formatter: 'formatter.formatCacheEfficiencyWithColor', path: 'ui>/cacheEfficiency'}" value="{path: 'ui>/cacheEfficiency', type: 'sap.ui.model.type.Float', formatOptions: {style: 'short', decimals: 2}}" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Throughput" subheader="Requests per Second">
+							<TileContent unit="req/s">
+								<NumericContent value="{ path: 'ui>/throughput', type: 'sap.ui.model.type.Float', formatOptions: {style: 'short', decimals: 2}}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Error Rate" subheader="Cache Errors">
+							<TileContent unit="%">
+								<NumericContent valueColor="{formatter: 'formatter.formatErrorRateWithColor', path: 'ui>/errorRate'}" value="{ path: 'ui>/errorRate', formatter: 'formatter.formatPercentageValue' }" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Total Requests" subheader="Cache Operations">
+							<TileContent unit="req">
+								<NumericContent value="{= ${ui>/hits} + ${ui>/misses}}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Cache Hits" subheader="Successful Retrievals">
+							<TileContent unit="hits">
+								<NumericContent value="{ui>/hits}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Cache Misses" subheader="Failed Retrievals">
+							<TileContent unit="misses">
+								<NumericContent value="{ui>/misses}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Cache Errors" subheader="Error Count">
+							<TileContent unit="errors">
+								<NumericContent value="{ui>/errors}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Hit Latency" subheader="Cache Hit Response">
+							<TileContent unit="ms">
+								<NumericContent valueColor="{formatter: 'formatter.formatLatencyWithColor', path: 'ui>/avgHitLatency'}" value="{ path: 'ui>/avgHitLatency', type: 'sap.ui.model.type.Float', formatOptions: {style: 'short', decimals: 2}}" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Miss Latency" subheader="Cache Miss Response">
+							<TileContent unit="ms">
+								<NumericContent valueColor="{formatter: 'formatter.formatLatencyWithColor', path: 'ui>/avgMissLatency'}" value="{ path: 'ui>/avgMissLatency', type: 'sap.ui.model.type.Float', formatOptions: {style: 'short', decimals: 2}}" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<!-- Read-Through Distribution Chart -->
+						<f:Card class="sapUiTinyMargin">
+							<f:header>
+								<card:Header title="Read-Through Operations" subtitle="Hit/Miss/Error Distribution" />
+							</f:header>
+							<f:content>
+								<l:VerticalLayout width="100%">
+									<viz:Popover id="metricCacheThroughPopOver"></viz:Popover>
+									<viz:VizFrame id="metricCacheThroughChart" vizType="pie" width="100%" height="300px">
+										<viz:dataset>
+											<viz.data:FlattenedDataset data="{ui>/cacheThroughData}">
+												<viz.data:dimensions>
+													<viz.data:DimensionDefinition name="Operation" value="{operation}" />
+												</viz.data:dimensions>
+												<viz.data:measures>
+													<viz.data:MeasureDefinition name="Count" value="{count}" />
+												</viz.data:measures>
+											</viz.data:FlattenedDataset>
+										</viz:dataset>
+										<viz:feeds>
+											<viz.feeds:FeedItem id="metricCacheThroughValueAxisFeed" uid="size" type="Measure" values="Count" />
+											<viz.feeds:FeedItem id="metricCacheThroughCategoryAxisFeed" uid="color" type="Dimension" values="Operation" />
+										</viz:feeds>
+									</viz:VizFrame>
+								</l:VerticalLayout>
+							</f:content>
+							<f:layoutData>
+								<f:GridContainerItemLayoutData columns="4" minRows="4"/>
+							</f:layoutData>
+						</f:Card>
+
+
+
+
+						<!-- Latency Chart -->
+						<f:Card class="sapUiTinyMargin">
+							<f:header>
+								<card:Header title="Latency Comparison" subtitle="Read-Through Latency Metrics" />
+							</f:header>
+							<f:content>
+								<l:VerticalLayout width="100%">
+									<viz:Popover id="metricLatencyPopOver"></viz:Popover>
+									<viz:VizFrame id="metricLatencyChart" vizType="bar" width="100%" height="300px">
+										<viz:dataset>
+											<viz.data:FlattenedDataset data="{ui>/latencyData}">
+												<viz.data:dimensions>
+													<viz.data:DimensionDefinition name="Operation" value="{operation}" />
+												</viz.data:dimensions>
+												<viz.data:measures>
+													<viz.data:MeasureDefinition name="Latency" value="{latency}" />
+												</viz.data:measures>
+											</viz.data:FlattenedDataset>
+										</viz:dataset>
+										<viz:feeds>
+											<viz.feeds:FeedItem id="metricValueAxisFeed" uid="valueAxis" type="Measure" values="Latency" />
+											<viz.feeds:FeedItem id="metricCategoryAxisFeed" uid="categoryAxis" type="Dimension" values="Operation" />
+										</viz:feeds>
+									</viz:VizFrame>
+								</l:VerticalLayout>
+							</f:content>
+							<f:layoutData>
+								<f:GridContainerItemLayoutData columns="12" minRows="4"/>
+							</f:layoutData>
+						</f:Card>
+
+
+
+					</f:GridContainer>
+				</VBox>
+
+				<!-- Native Function Performance Section -->
+				<VBox renderType="Bare">
+					<layoutData>
+						<cssgrid:ResponsiveColumnItemLayoutData columns="24"/>
+					</layoutData>
+
+					<Title text="Native Function Performance" titleStyle="H5" class="sapUiMediumMarginTop sapUiTinyMarginBottom" />
+
+					<f:GridContainer id="metricNativeGrid" columnsChange=".onColumnsChange">
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Native Throughput" subheader="Operations per Second">
+							<TileContent unit="ops/s">
+								<NumericContent value="{ path: 'ui>/nativeThroughput', formatter: 'formatter.formatNumberValue' }" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Native Error Rate" subheader="Native Function Errors">
+							<TileContent unit="%">
+								<NumericContent valueColor="{formatter: 'formatter.formatErrorRateWithColor', path: 'ui>/nativeErrorRate'}" value="{ path: 'ui>/nativeErrorRate', formatter: 'formatter.formatPercentageValue' }" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Native Sets" subheader="Write Operations">
+							<TileContent unit="sets">
+								<NumericContent value="{ui>/nativeSets}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Native Gets" subheader="Read Operations">
+							<TileContent unit="gets">
+								<NumericContent value="{ui>/nativeGets}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Native Deletes" subheader="Delete Operations">
+							<TileContent unit="deletes">
+								<NumericContent value="{ui>/nativeDeletes}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Native Clears" subheader="Clear Operations">
+							<TileContent unit="clears">
+								<NumericContent value="{ui>/nativeClears}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Delete By Tags" subheader="Tag-based Deletes">
+							<TileContent unit="deletes">
+								<NumericContent value="{ui>/nativeDeleteByTags}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Native Errors" subheader="Error Count">
+							<TileContent unit="errors">
+								<NumericContent value="{ui>/nativeErrors}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+
+						<GenericTile class="sapUiTinyMarginBegin sapUiTinyMarginTop tileLayout" header="Total Native Ops" subheader="All Operations">
+							<TileContent unit="ops">
+								<NumericContent value="{ui>/totalNativeOperations}" withMargin="false" />
+							</TileContent>
+							<layoutData>
+								<f:GridContainerItemLayoutData columns="2" minRows="2"/>
+							</layoutData>
+						</GenericTile>
+						<!-- Native Function Distribution Chart -->
+						<f:Card class="sapUiTinyMargin">
+							<f:header>
+								<card:Header title="Native Function Operations" subtitle="Hit/Miss/Error Distribution" />
+							</f:header>
+							<f:content>
+								<l:VerticalLayout width="100%">
+									<viz:Popover id="metricNativePopOver"></viz:Popover>
+									<viz:VizFrame id="metricNativeChart" vizType="pie" width="100%" height="300px">
+										<viz:dataset>
+											<viz.data:FlattenedDataset data="{ui>/nativeData}">
+												<viz.data:dimensions>
+													<viz.data:DimensionDefinition name="Operation" value="{operation}" />
+												</viz.data:dimensions>
+												<viz.data:measures>
+													<viz.data:MeasureDefinition name="Count" value="{count}" />
+												</viz.data:measures>
+											</viz.data:FlattenedDataset>
+										</viz:dataset>
+										<viz:feeds>
+											<viz.feeds:FeedItem id="metricNativeValueAxisFeed" uid="size" type="Measure" values="Count" />
+											<viz.feeds:FeedItem id="metricNativeCategoryAxisFeed" uid="color" type="Dimension" values="Operation" />
+										</viz:feeds>
+									</viz:VizFrame>
+								</l:VerticalLayout>
+							</f:content>
+							<f:layoutData>
+								<f:GridContainerItemLayoutData columns="4" minRows="4"/>
+							</f:layoutData>
+						</f:Card>
+					</f:GridContainer>
+				</VBox>
+
+			</cssgrid:CSSGrid>
+		</f:content>
+	</f:DynamicPage>
+
+</mvc:View> 

package/cds-plugin.js

@@ -1,7 +1,59 @@
 const cds = require('@sap/cds')
+const { fs, path } = cds.utils;
 const CachingService = require('./lib/CachingService')
 const { scanCachingAnnotations } = require('./lib/util')
 
+// Auto-register plugin entity models based on service configuration.
+// Pushes absolute file paths (without extension) into cds.env.roots so that
+// cds.resolve('*') picks them up during model compilation — before cds.model is set.
+const cachingConfigs = Object.values(cds.env.requires ?? {}).filter(r => r?.impl === 'cds-caching');
+if (cachingConfigs.some(c => c.store === 'cds')) {
+    cds.env.roots.push(path.join(__dirname, 'db', 'cache-store'));
+}
+if (cachingConfigs.some(c => c.statistics)) {
+    cds.env.roots.push(path.join(__dirname, 'db', 'statistics'));
+}
+
+cds.add?.register?.('caching-dashboard', require('./lib/add'))
+
 cds.on('served', scanCachingAnnotations)
+const LOG = cds.log("cds-caching");
+
+// Register HANA build plugin to generate .hdbtable artifacts during `cds build`
+cds.build?.register?.('cds-caching', class CachingBuildPlugin extends cds.build.Plugin {
+    static taskDefaults = { src: cds.env.folders.db }
+
+    init() { }
+    clean() { }
+
+    static hasTask() {
+        const requires = cds.env.requires || {};
+        return Object.values(requires).some(
+            r => r.impl === 'cds-caching' && r.store === 'hana'
+        );
+    }
+
+    async build() {
+        const requires = cds.env.requires || {};
+        for (const [, config] of Object.entries(requires)) {
+            if (config.impl === 'cds-caching' && config.store === 'hana') {
+                const table = config.credentials?.table || 'KEYV';
+                const keySize = config.credentials?.keySize || 255;
+                const content = [
+                    `COLUMN TABLE "${table}" (`,
+                    `  "ID" NVARCHAR(${keySize}) PRIMARY KEY,`,
+                    `  "VALUE" NCLOB`,
+                    `)`,
+                ].join('\n');
+                await this.write(content).to(`src/gen/${table}.hdbtable`);
+                LOG.info('Building cds-caching hana table', { table, keySize });
+            }
+            // For store: 'cds' with HANA, the CacheStore entity from db/cache-store.cds
+            // is loaded via cds.env.roots and deployed automatically by the HDI deployer —
+            // no manual .hdbtable needed. For SQLite/Postgres, CAP's cds deploy handles
+            // table creation from the CDS model.
+        }
+    }
+});
 
 module.exports = cds.service.impl(CachingService)

package/db/cache-store.cds

@@ -0,0 +1,12 @@
+namespace plugin.cds_caching;
+
+/**
+ * Key-value store for the CDS cache adapter (`store: 'cds'`).
+ * Uses CAP's managed DB connection — works with HANA, PostgreSQL, SQLite.
+ * In MTX mode, each tenant's HDI container gets its own table automatically.
+ */
+entity CacheStore {
+    key ID        : String(900);
+        value     : LargeString;
+        expiresAt : Int64;
+}

package/db/statistics.cds

@@ -0,0 +1,128 @@
+namespace plugin.cds_caching;
+
+entity Caches {
+    key name              : String;
+        config            : String;
+        metricsEnabled    : Boolean default false;
+        keyMetricsEnabled : Boolean default false;
+        metrics           : Composition of many Metrics
+                                on metrics.cache = $self.name;
+        keyMetrics        : Composition of many KeyMetrics
+                                on keyMetrics.cache = $self.name;
+}
+
+entity Metrics {
+    key ID                    : String; // e.g., 'daily:2024-03-20' or 'hourly:2024-03-20-15'
+    key cache                 : String;
+        timestamp             : DateTime;
+        period                : String enum {
+            hourly;
+            daily;
+            monthly;
+        }; // Granularity
+
+        // Read-through metrics (hits and misses only)
+        hits                  : Integer default 0;
+        misses                : Integer default 0;
+        errors                : Integer default 0;
+        totalRequests         : Integer default 0;
+        // Read-through latency metrics
+        avgHitLatency         : Double; // average hit latency in milliseconds
+        minHitLatency         : Double; // minimum hit latency
+        maxHitLatency         : Double; // maximum hit latency
+        avgMissLatency        : Double; // average miss latency in milliseconds
+        minMissLatency        : Double; // minimum miss latency
+        maxMissLatency        : Double; // maximum miss latency
+        avgReadThroughLatency : Double; // average read through latency in milliseconds
+
+        // Read-through performance metrics
+        hitRatio              : Double; // hit ratio as percentage
+        throughput            : Double; // requests per second
+        errorRate             : Double; // error rate as percentage
+        cacheEfficiency       : Double; // ratio of miss latency to hit latency
+
+        // Native function metrics (basic counts only)
+        nativeSets            : Integer default 0;
+        nativeGets            : Integer default 0;
+        nativeDeletes         : Integer default 0;
+        nativeClears          : Integer default 0;
+        nativeDeleteByTags    : Integer default 0;
+        nativeErrors          : Integer default 0;
+        totalNativeOperations : Integer default 0;
+        // Native function performance metrics
+        nativeThroughput      : Double; // native operations per second
+        nativeErrorRate       : Double; // native operation error rate
+
+        // Common metrics
+        memoryUsage           : Integer; // in bytes
+        itemCount             : Integer;
+        uptimeMs              : Integer; // uptime in milliseconds
+}
+
+entity KeyMetrics {
+    key ID                    : String;
+    key cache                 : String;
+    key keyName               : String;
+        lastAccess            : DateTime;
+        period                : String enum {
+            current;
+            hourly;
+            daily;
+        };
+
+        // Operation type tracking
+        operationType         : String enum {
+            read_through;
+            native;
+            mixed;
+        };
+
+        // Read-through metrics (hits and misses only)
+        hits                  : Integer default 0;
+        misses                : Integer default 0;
+        errors                : Integer default 0;
+        totalRequests         : Integer default 0;
+        hitRatio              : Double; // hit ratio as percentage
+        cacheEfficiency       : Double; // ratio of miss latency to hit latency
+
+        // Read-through latency metrics
+        avgHitLatency         : Double; // average hit latency in milliseconds
+        minHitLatency         : Double; // minimum hit latency
+        maxHitLatency         : Double; // maximum hit latency
+        avgMissLatency        : Double; // average miss latency in milliseconds
+        minMissLatency        : Double; // minimum miss latency
+        maxMissLatency        : Double; // maximum miss latency
+        avgReadThroughLatency : Double; // average read through latency in milliseconds
+
+        // Read-through performance metrics
+        throughput            : Double; // requests per second
+        errorRate             : Double; // error rate as percentage
+
+        // Native function metrics (counts only)
+        nativeHits            : Integer default 0;
+        nativeMisses          : Integer default 0;
+        nativeSets            : Integer default 0;
+        nativeDeletes         : Integer default 0;
+        nativeClears          : Integer default 0;
+        nativeDeleteByTags    : Integer default 0;
+        nativeErrors          : Integer default 0;
+        totalNativeOperations : Integer default 0;
+        // Native function performance metrics
+        nativeThroughput      : Double; // native operations per second
+        nativeErrorRate       : Double; // native operation error rate
+
+        // Metadata fields
+        dataType              : String;
+        operation             : String; // concatenated cache service operations (e.g., SET, GET, WRAP, RUN...)
+        metadata              : LargeString; // JSON string for additional metadata
+        // Enhanced context information
+        context               : String; // JSON string with detailed context
+        query                 : LargeString; // CQL query text if applicable
+        subject               : LargeString; // JSON string with subject information
+        target                : String; // Target information
+        tenant                : String; // Tenant information
+        user                  : String; // User information
+        locale                : String; // Locale information
+        timestamp             : DateTime; // When this key was first accessed
+        cacheOptions          : String; // JSON string with cache options
+}