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

   npm add @cap-js-community/business-metrics

2. Enable business metrics in package.json under the cds.requires.telemetry.metrics section:

   {
     "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