Telemetry is enabled in the CAP application configuration enableBusinessMetrics is set under cds.requires.telemetry.metrics The project is a CAP Node.js project with service definitions Tenant is the only dimension available, which the README states for the counting annotation
@cap-js-community/business-metrics
An extension of @cap-js/telemetry@cap-js/telemetryAutomatic OpenTelemetry instrumentation for CAP Node.js services and their database calls, exported as traces and metrics to the console, SAP Cloud Logging, Dynatrace, Jaeger or an OTLP endpoint.sap official, cap that turns two CDS annotations into business metrics, a counter on an entity event or action and a gauge on numeric fields.
@cap-js-community/business-metrics is an extension library for @cap-js/telemetry@cap-js/telemetryAutomatic OpenTelemetry instrumentation for CAP Node.js services and their database calls, exported as traces and metrics to the console, SAP Cloud Logging, Dynatrace, Jaeger or an OTLP endpoint.sap official, cap that turns two CDS annotations into metrics, so a count the business asks for is declared in the model instead of written as OpenTelemetry API calls. @UsageMetering.Counting on a service entity or an action emits a counter, raised on the CRUD event the annotation names or on each call of the action, and the annotation's qualifier becomes the metric name. @UsageMetering.Gauge observes numeric fields of an entity, a stock level for instance, under a name fixed to the service and the entity. It needs telemetry enabled in the application's configuration and enableBusinessMetrics set under cds.requires.telemetry.metrics, tenant is the only dimension it captures, and the README asks that no field holding personal data is observed.
Facts
Where it sits
Who is behind it
In the atlas: maintains 10@cap-js-communitymaintainerashutoshtghoratContributes to this
In the atlas: contributes to 1@ashutoshtghoratBhoomikaContributes to this
In the atlas: contributes to 1@bhoomikabedraChristian GeorgiContributes to this
In the atlas: maintains 1, contributes to 53@chgeoHarshith Kumar ReddyContributes to this
In the atlas: contributes to 1@hrsthrdyKS-PrathikshaContributes to this
In the atlas: contributes to 1@KS-PrathikshaKSPrathikshaContributes to this
In the atlas: contributes to 1@KSPrathikshaPrathikshaKSContributes to this
In the atlas: contributes to 1@PrathikshaKSM SahuContributes to this
In the atlas: contributes to 2@sahumadhusudansjvansContributes to this
In the atlas: contributes to 45@sjvans9 contributors
Before choosing this
Conditions
LicenceSAP Developer License Agreement 3.2 CAP§ 1, 2, 3A cds-plugin is used with SAP CAP materials, or an artifact is explicitly identified as a CAP plugin or application.
- § 1 License. Productive customer applications are limited to SAP BTP or another SAP-licensed platform, and mass extraction to a non-SAP product is restricted except where solely required for SAP interoperability.
- § 2 Intellectual Property. The agreement retains SAP's rights in the covered materials and limits making APIs, tools or software available to third parties, while preserving ownership of customer applications subject to SAP's underlying rights.
- § 3 Artificial Intelligence Training. The agreement prohibits use of the covered materials and customer applications for training artificial-intelligence models or systems.
What it declares
Every artifact
- Type
- CDS plugin
- Origin
- By a community org
- Runtime
- Node.js
As a CDS plugin
- Declared for
- >=9
- Distributed through
- npm
For telemetry
- Signals
- Metrics
- Instrumented by
- CDS annotations
Tasks this contributes to
Count a business event as a metricA count the business asks for, how often an order is released or a document read, is emitted as a metric beside the runtime's technical ones, with the tenant on it.
Connections
Traces, metrics and correlation for a running service
OpenTelemetry instrumentation for CAP services
Download
Install
npm add @cap-js-community/business-metricsDerived from the package name. No recipe recorded; the README has the configuration.
README
quoted from cap-js-community/business-metrics under Apache-2.0, readBusiness-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
-
Add
business-metricsto your dependencies via npm add@cap-js-community/business-metricsnpm add @cap-js-community/business-metrics -
Enable business metrics in
package.jsonunder thecds.requires.telemetry.metricssection:{ "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 (#<metricName>), which becomes the metric name in the telemetry output.
annotate <Service>.<Target> with @UsageMetering.Counting #<metricName> : {
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:
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 (
#<metricName>): 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 (#<metricName>).
[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:
annotate <Service>.<Entity> with @UsageMetering.Gauge : {
Key : '****',
Observe : ['****']
};
Example for reference:
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 <service name>.<entity name>. 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. 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.
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 at all times.
Licensing
Copyright 2026 SAP SE or an SAP affiliate company and contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.
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
History
Others providing
Compare all 9 on the Telemetry page →- com.sap.cds:cds-services-bomcom.sap.cds:cds-services-bomThe Maven bill of materials for CAP Java, pinning every com.sap.cds module in a release, from the API and core runtime to the Spring Boot starters and the CQN engine, to the same version.sap official, capMaven bill of materials pinning CAP Java module versions
- @cap-js/telemetry@cap-js/telemetryAutomatic OpenTelemetry instrumentation for CAP Node.js services and their database calls, exported as traces and metrics to the console, SAP Cloud Logging, Dynatrace, Jaeger or an OTLP endpoint.sap official, capOpenTelemetry instrumentation for CAP services
- cds-cachingcds-cachingA caching plugin for CAP covering queries, requests, function results and remote service responses, through a read-through API or @cache annotations, with HCQL and MCP support.independent, capCAP caching plugin for query results and remote service responses
- cap-mcp-guardcap-mcp-guardA CDS plugin — the trust layer for AI agents accessing SAP CAP business data — request interception, policy enforcement, field masking/pseudonymization, and OpenTelemetry-native observability for MCP-enabled applications.independent, capPolicy enforcement and field masking for MCP-enabled CAP apps
- @sanjay-sde/cap-js-log-control@sanjay-sde/cap-js-log-controlA CAP plugin for controlling CDS logger verbosity and OpenTelemetry DiagLogger noise, reducing log clutter so that real errors surface.independent, capCAP plugin controlling CDS logger and OpenTelemetry log verbosity
- @sap-ux/telemetry@sap-ux/telemetryLibrary for sending usage telemetry datasap official, capLibrary for sending usage telemetry data
- cap-ui-telemetrycap-ui-telemetryUI5 frontend performance (FESR) and client error capture for CAP, written as cds.log records and forwarded to SAP Cloud Logging, rather than as OpenTelemetry spans.independent, capUI5 frontend performance and error capture for CAP
- opentelemetry-cdsopentelemetry-cdsopentelemetry support for CDS nodejs runtimeindependent, capOpenTelemetry support for the CDS Node.js runtime
Details
Sources
Sources are graph entities: the same page may back several entries, and an unreachable source flags every row that rests on it.
Compatibility and provenance
Contributors
History in the atlas
- what it does for telemetry, its two stated properties, and the edge to the plugin it extends
- First seen.
For your agent
- Ref
artifact:cap-js-community-business-metrics- JSON
- /artifacts/cap-js-community-business-metrics.json
- MCP
- Connecting an agent