{"_id":"@cap-js-community/business-metrics","_rev":"3-165478819f86f7bfc1443ec5edb4d83d","name":"@cap-js-community/business-metrics","dist-tags":{"latest":"1.0.0"},"versions":{"0.0.0":{"name":"@cap-js-community/business-metrics","version":"0.0.0","_id":"@cap-js-community/business-metrics@0.0.0","maintainers":[{"name":"sap_extncrepos","email":"mob.extrepo.stores@sap.com"},{"name":"cap-npm","email":"cap@sap.com"},{"name":"sap-ospo-admin","email":"ospo@sap.com"}],"dist":{"shasum":"e3f95e16e5efd3046f7983945083d82ba8526ccd","tarball":"https://registry.npmjs.org/@cap-js-community/business-metrics/-/business-metrics-0.0.0.tgz","fileCount":1,"integrity":"sha512-uFW8WfOJIjAJTYXghE6IbaKG4NHjwzMF4oXpTBYD/z3dtK0kSX5OUSDcfxRMR97azf+UgELDA75FN0UmduvuXA==","signatures":[{"sig":"MEUCIQClfwU7bcZlHqhhCvD0HCQ2a7sZJJolo3zbO1JrWoMt4AIgT3MqYF6GcL28wbj5s109Jz5Y4uEG2KjPRtBfIjUOHZ8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73},"_npmUser":{"name":"cap-npm","email":"cap@sap.com"},"_npmVersion":"11.15.0","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/business-metrics_0.0.0_1781788767702_0.005548343434605085","host":"s3://npm-registry-packages-npm-production"},"deprecated":"this release was a dummy release and should not be used"},"1.0.0":{"name":"@cap-js-community/business-metrics","version":"1.0.0","license":"Apache-2.0","_id":"@cap-js-community/business-metrics@1.0.0","maintainers":[{"name":"sap_extncrepos","email":"mob.extrepo.stores@sap.com"},{"name":"cap-npm","email":"cap@sap.com"},{"name":"sap-ospo-admin","email":"ospo@sap.com"}],"homepage":"https://github.com/cap-js-community/business-metrics#readme","bugs":{"url":"https://github.com/cap-js-community/business-metrics/issues"},"dist":{"shasum":"4ea781534f0b5c279b6c95fff25a1d2b054ce981","tarball":"https://registry.npmjs.org/@cap-js-community/business-metrics/-/business-metrics-1.0.0.tgz","fileCount":5,"integrity":"sha512-aFFj8EwfeNYAkBUCZyUZw40tbVPXkxPpSnnfIxOVKCi6AsJ4Mi4qfUFqDoW21jLyPOa/6eSAt+ebtheQCiRR6Q==","signatures":[{"sig":"MEUCIQDrVBiFuHsr53uOyVaNU9lvvo7mJGJloVoA7+2Z9cV2aQIgWSfyJAxYK6CTMV+oj5iVDdvfrti68tj1fCl/KpI57Bg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cap-js-community%2fbusiness-metrics@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":29579},"main":"cds-plugin.js","gitHead":"4367e112fd7a0c231dc2766afe247dc99fdb2270","scripts":{"lint":"npx eslint .","test":"npx jest --maxWorkers=1 --silent --detectOpenHandles --forceExit","start":"cds-serve","coverage":"npx jest --coverage --maxWorkers=1 --silent --detectOpenHandles","test-file":"npx jest test/counter-metrics.test.js --silent"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:51c89004-68bb-4760-8291-d0816db8a615"}},"repository":{"url":"git+https://github.com/cap-js-community/business-metrics.git","type":"git"},"_npmVersion":"11.13.0","description":"Counter and Guage metrics for @cap-js/telemetry","directories":{},"_nodeVersion":"24.16.0","dependencies":{"@opentelemetry/api":"^1.9.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.5","eslint":"^9.23.0","@cap-js/sqlite":"^2.4.0","@cap-js/cds-test":"^1.0.1","business-metrics":"file:.","@cap-js/cds-types":"^0.17.0"},"peerDependencies":{"@sap/cds":">=9","@cap-js/telemetry":"^1.6.0"},"_npmOperationalInternal":{"tmp":"tmp/business-metrics_1.0.0_1782105965987_0.5925611737191137","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-06-18T13:19:27.535Z","modified":"2026-06-22T07:28:18.852Z","0.0.0":"2026-06-18T13:19:27.826Z","1.0.0":"2026-06-22T05:26:06.126Z"},"bugs":{"url":"https://github.com/cap-js-community/business-metrics/issues"},"license":"Apache-2.0","homepage":"https://github.com/cap-js-community/business-metrics#readme","repository":{"url":"git+https://github.com/cap-js-community/business-metrics.git","type":"git"},"description":"Counter and Guage metrics for @cap-js/telemetry","maintainers":[{"name":"cap-npm","email":"cap@sap.com"},{"name":"sap_extncrepos","email":"mob.extrepo.stores@sap.com"},{"name":"sap-ospo-admin","email":"ospo@sap.com"}],"readme":"# Business-metrics\n\n[![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)\n\n## About this project\n\n**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.\n\n## Requirements and Setup\n\nTo use this library in your CAP project, ensure the following:\n\n- SAP CAP runtime (`@sap/cds`)\n- A CAP-based Node.js project with service definitions\n- Telemetry enabled in the CAP application configuration\n\n### Installation\n\n1. Add `business-metrics` to your dependencies via npm add `@cap-js-community/business-metrics`\n\n    ```bash\n    npm add @cap-js-community/business-metrics\n    ```\n\n2. Enable business metrics in `package.json` under the `cds.requires.telemetry.metrics` section:\n\n    ```json\n    {\n      \"cds\": {\n        \"requires\": {\n          \"telemetry\": {\n            \"metrics\": {\n              \"enableBusinessMetrics\": true\n            }\n          }\n        }\n      }\n    }\n    ```\n\n---\n\n## Features\n\n- **Counter Metrics**: Track the number of times specific events occur for service entities or actions (e.g., READ, DELETE or custom actions like releaseSalesOrder).\n- **Gauge Metrics**: Monitor and observe specific fields of entities, such as stock levels or other numeric values.\n\n### Counting Annotation\n\nUse 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 (`#<metricName>`), which becomes the metric name in the telemetry output.\n\n```cds\nannotate <Service>.<Target> with @UsageMetering.Counting #<metricName> : {\n    Dimensions : { tenant },\n    Operation  : { CRUDType : '****' }\n};\n```\n\nCounting Metrics can be annotated for service entities, bound actions, or unbound actions.\n\nExample for reference in entity, bound action, and unbound action scenarios:\n\n```cds\nservice CategoryService {\n    @odata.draft.enabled\n    entity Books as projection on my.Books actions {\n        action buyBook() returns String;\n    };\n\n    action purchaseBook() returns String;\n}\n\n// Entity — CRUD metrics (READ + DELETE)\nannotate CategoryService.Books with @(\n    UsageMetering.Counting #myBooksReadMetric : {\n        Dimensions : { tenant },\n        Operation  : { CRUDType : 'Read' }\n    },\n    UsageMetering.Counting #myBooksDeleteMetric : {\n        Dimensions : { tenant },\n        Operation  : { CRUDType : 'Delete' }\n    }\n);\n\n// Bound action\nannotate CategoryService.Books with actions {\n    buyBook @UsageMetering.Counting #myBuyBookCallsMetric : {\n        Dimensions : { tenant }\n    };\n};\n\n// Unbound action\nannotate CategoryService.purchaseBook with @UsageMetering.Counting #myPurchaseBookCallsMetric : {\n    Dimensions : { tenant }\n};\n```\n\n- **Qualifier (`#<metricName>`)**: The metric name used in the telemetry output.\n- **CRUDType**: For entity counters, specifies which CRUD event triggers the increment. Valid values: `Read`, `Create`, `Update`, `Delete`. (Not required for action counters.)\n- **Dimensions**: Define dimensions (e.g. `tenant`) to include in the metrics. The library supports the capture of tenant information only.\n\n##### Example `counting metrics` outputs:\n\nThe counter metric name is the qualifier from the annotation (`#<metricName>`).\n\n```\n[telemetry] - myBooksReadMetric: {\n  attributes: { tenant: '' },\n  startTime: [ 100000000, 400000000 ],\n  endTime: [ 100000000, 600000000 ],\n  value: 3\n}\n```\n\n### Gauge Annotation\n\nUse the `@UsageMetering.Gauge` annotation in your `services.cds` file to enable gauge metrics for specific entities which is mentioned below:\n\n```cds\nannotate <Service>.<Entity> with @UsageMetering.Gauge : {\n    Key     : '****',\n    Observe : ['****']\n};\n```\n\nExample for reference:\n\n```cds\nservice CategoryService {\n    entity BookStock as projection on my.Books {\n        ID,\n        title,\n        stock\n    };\n}\n\nannotate CategoryService.BookStock with @UsageMetering.Gauge : {\n    Key     : 'ID',\n    Observe : ['stock']\n};\n```\n\n##### Example `gauge metrics` outputs:\n\nThe gauge metric name always follows the pattern `<service name>.<entity name>`. This pattern is fixed and cannot be changed or overridden.\n\n```\n[telemetry] - CategoryService.BookStock: {\n  attributes: { entity_gauge: 'CategoryService.BookStock', key: 271 },\n  startTime: [ 1755508380, 604000000 ],\n  endTime: [ 1755508380, 604000000 ],\n  value: 22\n}\n```\n- **Key**: Specify the unique key for the entity.\n- **Observe**: Define the fields to observe for gauge metrics.\n\n## Support, Feedback, Contributing\n\nThis 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).\n\n## Code of Conduct\n\nWe 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.\n\n## Licensing\n\nCopyright 2026 SAP SE or an SAP affiliate company and <your-project> 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).\n\n## Disclaimer\n\nMetrics 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 \n","readmeFilename":"README.md"}