cds-caching 1.2.0 → 1.3.0

package/index.cds

@@ -1,132 +1,6 @@
-context 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
-    }
+using from './db/statistics';
 
+context plugin.cds_caching {
 
     @impl: 'cds-caching/srv/caching-api-service'
     service CachingApiService {

package/lib/CachingService.js

@@ -7,6 +7,8 @@ const CacheStatisticsHandler = require('./support/CacheStatisticsHandler');
 const BasicOperations = require('./operations/BasicOperations');
 const CapOperations = require('./operations/CapOperations');
 const AsyncOperations = require('./operations/AsyncOperations');
+const telemetry = require('./support/Telemetry');
+const { isMultitenantMode } = require('./support/MultitenancyDetector');
 
 class CachingService extends cds.Service {
 
@@ -36,7 +38,18 @@ class CachingService extends cds.Service {
         // Create cache store
         const { cache, cleanup } = this.storeManager.createStore(this.options, this.name);
         this.cache = cache;
+
+        // Set default OTel attributes for all cache metrics
+        telemetry.setDefaultAttributes({
+            'cache.name': this.name,
+            'cache.store': this.options.store || 'memory',
+            'cache.namespace': this.options.namespace || this.name
+        });
+
         this.log.info(`Caching service ${this.name} initialized with namespace ${this.options.namespace || this.name}`);
+        if (isMultitenantMode()) {
+            this.log.info(`Multi-tenant mode detected for ${this.name} — tenant-aware caching enabled`);
+        }
 
         // Set up cleanup on shutdown
         cds.once("shutdown", cleanup);

package/lib/add.js

@@ -0,0 +1,17 @@
+const cds = require("@sap/cds-dk");
+const { copy, path, write } = cds.utils;
+const { join } = path;
+
+module.exports = class extends cds.add.Plugin {
+	async run() {
+		const src = join(__dirname, "..", "app", "dashboard");
+		await copy(src).to("app", "caching-dashboard", "webapp");
+
+		const cdsFile = join(cds.root, "srv", "caching-api.cds");
+		if (!cds.utils.fs.existsSync(cdsFile)) {
+			await write(
+				"using {plugin.cds_caching.CachingApiService} from 'cds-caching/index.cds';\n",
+			).to("srv/caching-api.cds");
+		}
+	}
+};

package/lib/operations/AsyncOperations.js

@@ -1,3 +1,4 @@
+const telemetry = require('../support/Telemetry');
 /**
  * Manages async cache operations for function wrapping and execution
  */
@@ -27,9 +28,10 @@ class AsyncOperations {
                 stack: error.stack,
                 context: context
             });
-            return { 
-                success: false, 
-                result: null, 
+            telemetry.recordError({ 'cache.error_operation': operationName });
+            return {
+                success: false,
+                result: null,
                 error: {
                     message: error.message,
                     operation: operationName,
@@ -72,7 +74,7 @@ class AsyncOperations {
         // Create argument placeholders
         const argPlaceholders = args.map((_, index) => `{args[${index}]}`).join(':');
         const template = `${baseKey}:${argPlaceholders}`;
-        
+
         return this.keyManager.createKey(
             { baseKey, args, functionName },
             {
@@ -95,113 +97,138 @@ class AsyncOperations {
      * @returns {function} - the wrapped function
      */
     wrap(key, asyncFunction, options = {}) {
-        return async (...args) => {
-            // Create dynamic key based on function arguments
-            const cacheKey = this.createDynamicKey(key, args, options, asyncFunction.name || 'anonymous');
-
-            const startTime = process.hrtime();
-            const metadata = {
-                dataType: 'Function',
-                operation: 'WRAP',
-                operationType: 'READ_THROUGH',
-                user: cds.context?.user?.id,
-                tenant: cds.context?.tenant,
-                locale: cds.context?.locale,
-                metadata: JSON.stringify({
-                    functionName: asyncFunction.name || 'anonymous',
-                    args: args,
-                    cacheKey: cacheKey
-                }),
-                cacheOptions: JSON.stringify(options)
-            };
+        const self = this;
+        return async function (...args) {
+            const tracer = telemetry.getTracer('cds-caching');
+            if (tracer) {
+                return tracer.startActiveSpan('cds-caching - wrap', async (span) => {
+                    try {
+                        const result = await self._wrap(key, asyncFunction, options, args);
+                        span.setAttribute('cache.hit', result.metadata.hit);
+                        span.setAttribute('cache.key', result.cacheKey);
+                        span.setAttribute('cache.operation', 'wrap');
+                        span.setAttribute('cache.operation_type', 'read_through');
+                        if (!result.metadata.hit) span.setAttribute('cache.ttl_ms', options.ttl || 0);
+                        return result;
+                    } catch (e) {
+                        span.setStatus({ code: telemetry.SpanStatusCode.ERROR, message: e.message });
+                        throw e;
+                    } finally {
+                        span.end();
+                    }
+                });
+            }
+            return self._wrap(key, asyncFunction, options, args);
+        };
+    }
 
-            // Safely check if key exists in cache
-            const hasKeyResult = await this.safeCacheOperation(
-                () => this.cache.has(cacheKey),
-                'has',
-                { key: cacheKey, functionName: asyncFunction.name || 'anonymous' }
-            );
+    /** @private */
+    async _wrap(key, asyncFunction, options, args) {
+        // Create dynamic key based on function arguments
+        const cacheKey = this.createDynamicKey(key, args, options, asyncFunction.name || 'anonymous');
 
-            const hasKey = hasKeyResult.success && hasKeyResult.result;
-            const cacheErrors = [];
-
-            if (hasKey) {
-                const latency = this.getElapsedMs(startTime);
-                
-                // Safely record hit statistics
-                const hitStatsResult = await this.safeCacheOperation(
-                    () => this.statistics.recordHit(latency, cacheKey, metadata),
-                    'recordHit',
-                    { key: cacheKey, latency }
-                );
-                if (!hitStatsResult.success) {
-                    cacheErrors.push(hitStatsResult.error);
-                }
+        const startTime = process.hrtime();
+        const metadata = {
+            dataType: 'Function',
+            operation: 'WRAP',
+            operationType: 'READ_THROUGH',
+            user: cds.context?.user?.id,
+            tenant: cds.context?.tenant,
+            locale: cds.context?.locale,
+            metadata: JSON.stringify({
+                functionName: asyncFunction.name || 'anonymous',
+                args: args,
+                cacheKey: cacheKey
+            }),
+            cacheOptions: JSON.stringify(options)
+        };
 
-                // Safely get value from cache
-                const getResult = await this.safeCacheOperation(
-                    () => this.cache.send("GET", { key: cacheKey }),
-                    'get',
-                    { key: cacheKey }
-                );
-
-                if (getResult.success && getResult.result?.value !== undefined) {
-                    return { 
-                        result: getResult.result.value, 
-                        cacheKey, 
-                        metadata: { hit: true, latency },
-                        cacheErrors: cacheErrors
-                    };
-                }
-            }
+        // Safely check if key exists in cache
+        const hasKeyResult = await this.safeCacheOperation(
+            () => this.cache.has(cacheKey),
+            'has',
+            { key: cacheKey, functionName: asyncFunction.name || 'anonymous' }
+        );
 
-            // Cache miss or cache error - delegate to underlying function
-            try {
-                const response = await asyncFunction(...args);
-                const latency = this.getElapsedMs(startTime);
-                
-                // Safely record miss statistics
-                const missStatsResult = await this.safeCacheOperation(
-                    () => this.statistics.recordMiss(latency, cacheKey, metadata),
-                    'recordMiss',
-                    { key: cacheKey, latency }
-                );
-                if (!missStatsResult.success) {
-                    cacheErrors.push(missStatsResult.error);
-                }
+        const hasKey = hasKeyResult.success && hasKeyResult.result;
+        const cacheErrors = [];
 
-                // Safely store in cache
-                const wrappedValue = {
-                    value: response,
-                    tags: options.tags || [],
-                    timestamp: Date.now()
-                };
-                
-                const setResult = await this.safeCacheOperation(
-                    () => this.cache.send("SET", { key: cacheKey, value: wrappedValue, ttl: options.ttl || 0 }),
-                    'set',
-                    { key: cacheKey, ttl: options.ttl }
-                );
-                if (!setResult.success) {
-                    cacheErrors.push(setResult.error);
-                }
+        if (hasKey) {
+            const latency = this.getElapsedMs(startTime);
+
+            // Safely record hit statistics
+            const hitStatsResult = await this.safeCacheOperation(
+                () => this.statistics.recordHit(latency, cacheKey, metadata),
+                'recordHit',
+                { key: cacheKey, latency }
+            );
+            if (!hitStatsResult.success) {
+                cacheErrors.push(hitStatsResult.error);
+            }
 
-                return { 
-                    result: response, 
-                    cacheKey, 
-                    metadata: { hit: false, latency },
+            // Safely get value from cache
+            const getResult = await this.safeCacheOperation(
+                () => this.cache.send("GET", { key: cacheKey }),
+                'get',
+                { key: cacheKey }
+            );
+
+            if (getResult.success && getResult.result?.value !== undefined) {
+                return {
+                    result: getResult.result.value,
+                    cacheKey,
+                    metadata: { hit: true, latency },
                     cacheErrors: cacheErrors
                 };
-            } catch (functionError) {
-                // If the underlying function fails, throw the error
-                this.log.error('Function execution failed:', {
-                    error: functionError.message,
-                    functionName: asyncFunction.name || 'anonymous',
-                    key: cacheKey
-                });
-                throw functionError;
             }
         }
+
+        // Cache miss or cache error - delegate to underlying function
+        try {
+            const response = await asyncFunction(...args);
+            const latency = this.getElapsedMs(startTime);
+
+            // Safely record miss statistics
+            const missStatsResult = await this.safeCacheOperation(
+                () => this.statistics.recordMiss(latency, cacheKey, metadata),
+                'recordMiss',
+                { key: cacheKey, latency }
+            );
+            if (!missStatsResult.success) {
+                cacheErrors.push(missStatsResult.error);
+            }
+
+            // Safely store in cache
+            const wrappedValue = {
+                value: response,
+                tags: options.tags || [],
+                timestamp: Date.now()
+            };
+
+            const setResult = await this.safeCacheOperation(
+                () => this.cache.send("SET", { key: cacheKey, value: wrappedValue, ttl: options.ttl || 0 }),
+                'set',
+                { key: cacheKey, ttl: options.ttl }
+            );
+            if (!setResult.success) {
+                cacheErrors.push(setResult.error);
+            }
+
+            return {
+                result: response,
+                cacheKey,
+                metadata: { hit: false, latency },
+                cacheErrors: cacheErrors
+            };
+        } catch (functionError) {
+            // If the underlying function fails, throw the error
+            this.log.error('Function execution failed:', {
+                error: functionError.message,
+                functionName: asyncFunction.name || 'anonymous',
+                key: cacheKey
+            });
+            throw functionError;
+        }
     }
 
     /**
@@ -213,6 +240,30 @@ class AsyncOperations {
      * @returns {Promise<any>} - the result
      */
     async exec(key, asyncFunction, args = [], options = {}) {
+        const tracer = telemetry.getTracer('cds-caching');
+        if (tracer) {
+            return tracer.startActiveSpan('cds-caching - exec', async (span) => {
+                try {
+                    const result = await this._exec(key, asyncFunction, args, options);
+                    span.setAttribute('cache.hit', result.metadata.hit);
+                    span.setAttribute('cache.key', result.cacheKey);
+                    span.setAttribute('cache.operation', 'exec');
+                    span.setAttribute('cache.operation_type', 'read_through');
+                    if (!result.metadata.hit) span.setAttribute('cache.ttl_ms', options.ttl || 0);
+                    return result;
+                } catch (e) {
+                    span.setStatus({ code: telemetry.SpanStatusCode.ERROR, message: e.message });
+                    throw e;
+                } finally {
+                    span.end();
+                }
+            });
+        }
+        return this._exec(key, asyncFunction, args, options);
+    }
+
+    /** @private */
+    async _exec(key, asyncFunction, args, options) {
         // Create dynamic key based on function arguments
         const cacheKey = this.createDynamicKey(key, args, options, asyncFunction.name || 'anonymous');
 
@@ -245,7 +296,7 @@ class AsyncOperations {
 
         if (hasKey) {
             const latency = this.getElapsedMs(startTime);
-            
+
             // Safely record hit statistics
             const hitStatsResult = await this.safeCacheOperation(
                 () => this.statistics.recordHit(latency, cacheKey, metadata),
@@ -264,9 +315,9 @@ class AsyncOperations {
             );
 
             if (getResult.success && getResult.result?.value !== undefined) {
-                return { 
-                    result: getResult.result.value, 
-                    cacheKey, 
+                return {
+                    result: getResult.result.value,
+                    cacheKey,
                     metadata: { hit: true, latency },
                     cacheErrors: cacheErrors
                 };
@@ -277,7 +328,7 @@ class AsyncOperations {
         try {
             const response = await asyncFunction(...args);
             const latency = this.getElapsedMs(startTime);
-            
+
             // Safely record miss statistics
             const missStatsResult = await this.safeCacheOperation(
                 () => this.statistics.recordMiss(latency, cacheKey, metadata),
@@ -294,7 +345,7 @@ class AsyncOperations {
                 tags: options.tags || [],
                 timestamp: Date.now()
             };
-            
+
             const setResult = await this.safeCacheOperation(
                 () => this.cache.send("SET", { key: cacheKey, value: wrappedValue, ttl: options.ttl || 0 }),
                 'set',
@@ -304,9 +355,9 @@ class AsyncOperations {
                 cacheErrors.push(setResult.error);
             }
 
-            return { 
-                result: response, 
-                cacheKey, 
+            return {
+                result: response,
+                cacheKey,
                 metadata: { hit: false, latency },
                 cacheErrors: cacheErrors
             };
@@ -332,4 +383,4 @@ class AsyncOperations {
     }
 }
 
-module.exports = AsyncOperations; 
+module.exports = AsyncOperations;

package/lib/operations/BasicOperations.js

@@ -1,3 +1,4 @@
+const telemetry = require('../support/Telemetry');
 /**
  * Manages basic cache operations with statistics tracking
  */
@@ -50,6 +51,14 @@ class BasicOperations {
             cacheOptions: JSON.stringify(options)
         };
         this.statistics.recordNativeSet(createdKey, metadata);
+
+        const span = telemetry.getActiveSpan();
+        if (span) {
+            span.setAttribute('cache.key', createdKey);
+            span.setAttribute('cache.operation', 'set');
+            span.setAttribute('cache.operation_type', 'basic');
+            span.setAttribute('cache.ttl_ms', options.ttl || 0);
+        }
     }
 
     /**
@@ -80,6 +89,14 @@ class BasicOperations {
         const isHit = wrappedValue !== undefined && wrappedValue !== null;
         this.statistics.recordNativeGet(createdKey, isHit, metadata);
 
+        const span = telemetry.getActiveSpan();
+        if (span) {
+            span.setAttribute('cache.hit', isHit);
+            span.setAttribute('cache.key', createdKey);
+            span.setAttribute('cache.operation', 'get');
+            span.setAttribute('cache.operation_type', 'basic');
+        }
+
         return wrappedValue?.value;
     }
 
@@ -127,6 +144,13 @@ class BasicOperations {
         };
         this.statistics.recordNativeDelete(createdKey, metadata);
 
+        const span = telemetry.getActiveSpan();
+        if (span) {
+            span.setAttribute('cache.key', createdKey);
+            span.setAttribute('cache.operation', 'delete');
+            span.setAttribute('cache.operation_type', 'basic');
+        }
+
         return result;
     }
 
@@ -149,6 +173,11 @@ class BasicOperations {
         };
         this.statistics.recordNativeClear(metadata);
 
+        const span = telemetry.getActiveSpan();
+        if (span) {
+            span.setAttribute('cache.operation', 'clear');
+            span.setAttribute('cache.operation_type', 'basic');
+        }
     }
 
     /**
@@ -173,6 +202,12 @@ class BasicOperations {
         };
         this.statistics.recordNativeDeleteByTag(tag, metadata);
 
+        const span = telemetry.getActiveSpan();
+        if (span) {
+            span.setAttribute('cache.tag', tag);
+            span.setAttribute('cache.operation', 'deleteByTag');
+            span.setAttribute('cache.operation_type', 'basic');
+        }
     }
 
     /**