# Business-metrics [![REUSE status](https://api.reuse.software/badge/github.com/cap-js-community/business-metrics)](https://api.reuse.software/info/github.com/cap-js-community/business-metrics) ## About this project **Business-metrics** is an extension library for **@cap-js/telemetry** designed for CAP (Cloud Application Programming) applications. It allows you to effortlessly track usage and performance by integrating Counter and Gauge metrics directly into your CAP service entities and actions. These metrics enable better observability and can be exported to telemetry tools for monitoring. ## Requirements and Setup To use this library in your CAP project, ensure the following: - SAP CAP runtime (`@sap/cds`) - A CAP-based Node.js project with service definitions - Telemetry enabled in the CAP application configuration ### Installation 1. Add `business-metrics` to your dependencies via npm add `@cap-js-community/business-metrics` ```bash npm add @cap-js-community/business-metrics ``` 2. Enable business metrics in `package.json` under the `cds.requires.telemetry.metrics` section: ```json { "cds": { "requires": { "telemetry": { "metrics": { "enableBusinessMetrics": true } } } } } ``` --- ## Features - **Counter Metrics**: Track the number of times specific events occur for service entities or actions (e.g., READ, DELETE or custom actions like releaseSalesOrder). - **Gauge Metrics**: Monitor and observe specific fields of entities, such as stock levels or other numeric values. ### Counting Annotation Use the `@UsageMetering.Counting` annotation in your `services.cds` file to enable counter metrics for specific entities or actions. Each metric is identified by a qualifier (`#`), which becomes the metric name in the telemetry output. ```cds annotate . with @UsageMetering.Counting # : { Dimensions : { tenant }, Operation : { CRUDType : '****' } }; ``` Counting Metrics can be annotated for service entities, bound actions, or unbound actions. Example for reference in entity, bound action, and unbound action scenarios: ```cds service CategoryService { @odata.draft.enabled entity Books as projection on my.Books actions { action buyBook() returns String; }; action purchaseBook() returns String; } // Entity — CRUD metrics (READ + DELETE) annotate CategoryService.Books with @( UsageMetering.Counting #myBooksReadMetric : { Dimensions : { tenant }, Operation : { CRUDType : 'Read' } }, UsageMetering.Counting #myBooksDeleteMetric : { Dimensions : { tenant }, Operation : { CRUDType : 'Delete' } } ); // Bound action annotate CategoryService.Books with actions { buyBook @UsageMetering.Counting #myBuyBookCallsMetric : { Dimensions : { tenant } }; }; // Unbound action annotate CategoryService.purchaseBook with @UsageMetering.Counting #myPurchaseBookCallsMetric : { Dimensions : { tenant } }; ``` - **Qualifier (`#`)**: The metric name used in the telemetry output. - **CRUDType**: For entity counters, specifies which CRUD event triggers the increment. Valid values: `Read`, `Create`, `Update`, `Delete`. (Not required for action counters.) - **Dimensions**: Define dimensions (e.g. `tenant`) to include in the metrics. The library supports the capture of tenant information only. ##### Example `counting metrics` outputs: The counter metric name is the qualifier from the annotation (`#`). ``` [telemetry] - myBooksReadMetric: { attributes: { tenant: '' }, startTime: [ 100000000, 400000000 ], endTime: [ 100000000, 600000000 ], value: 3 } ``` ### Gauge Annotation Use the `@UsageMetering.Gauge` annotation in your `services.cds` file to enable gauge metrics for specific entities which is mentioned below: ```cds annotate . with @UsageMetering.Gauge : { Key : '****', Observe : ['****'] }; ``` Example for reference: ```cds service CategoryService { entity BookStock as projection on my.Books { ID, title, stock }; } annotate CategoryService.BookStock with @UsageMetering.Gauge : { Key : 'ID', Observe : ['stock'] }; ``` ##### Example `gauge metrics` outputs: The gauge metric name always follows the pattern `.`. This pattern is fixed and cannot be changed or overridden. ``` [telemetry] - CategoryService.BookStock: { attributes: { entity_gauge: 'CategoryService.BookStock', key: 271 }, startTime: [ 1755508380, 604000000 ], endTime: [ 1755508380, 604000000 ], value: 22 } ``` - **Key**: Specify the unique key for the entity. - **Observe**: Define the fields to observe for gauge metrics. ## Support, Feedback, Contributing This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js-community/business-metrics/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md). ## Code of Conduct We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](CODE_OF_CONDUCT.md) at all times. ## Licensing Copyright 2026 SAP SE or an SAP affiliate company and contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/cap-js-community/business-metrics). ## Disclaimer Metrics collected by this library will be propagated to monitoring dashboards. When using the `@UsageMetering.Gauge` annotation, ensure that any fields containing Personal Data is not observed, as this may lead to unintended data exposure. For `@UsageMetering.Counting` annotation, only tenant is supported as dimension