Business-metrics

About this project

Business-metrics is an extension library for @cap-js/telemetry ddesigned for Cloud Application Programming (CAP) 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 you have the following:

• Node.js (version 14 or higher)
• 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, such as READ, DELETE, or custom actions like releaseSalesOrder.
• Gauge Metrics: Monitor and observe specific entity fields, such as stock levels or other numeric values.

Counter Annotation

Use the @Counter annotation in your services.cds file to enable counter metrics for specific entities or actions.

@(Counter: [
    {
        event     : '****',
        attributes: [
            ***
        ]
    }
])

You can annotate counter metrics for service entities or actions.

For reference, here are examples in both scenarios:

    service CategoryService {
        @(Counter: [
            {
            event: 'READ',
            attributes: [
                tenant
            ]
            },
            {
            event: 'DELETE',
            attributes: [
                tenant
            ]
            }
        ])
        entity Books as projection on my.Books;

        @(Counter: {attributes: [
            tenant
        ]})
        action purchaseBook() returns String;
    }

• Events: Specify the events for which the counter metrics are triggered. For a complete list of available events, see the CAP documentation.
• Attributes: Define the attributes to include in the metrics, such as tenant. The library supports the capture of tenant information only.

Example: Counter Metrics Outputs :

The counter metric name always follows the pattern .__total. You can’t change or override this pattern.

[telemetry] - CategoryService.Books_READ_total: {
  attributes: { tenant: '' },
  startTime: [ 100000000, 400000000 ],
  endTime: [ 100000000, 600000000 ],
  value: 3
}

Gauge Annotation

Use the @Gauge annotation in your services.cds file to enable gauge metrics for specific entities:

    @(Gauge: {
        key    : '****',
        observe: ['****']
    })

For reference, here is the examples:

    service CategoryService {
        @(Gauge: {
            key: 'ID',
            observe: ['stock']
        })
        entity BookStock as
            projection on my.Books {
            ID,
            title,
            stock
            };
    }

Example: Gauge Metrics Outputs :

The gauge metric name always follows the pattern .. You can’t change or override this pattern.

[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.

Disclaimer

Metrics collected by this library will be propagated to monitoring dashboards. When using the @Gauge annotation, ensure that any fields containing personal data is not observed, as this may lead to unintended data exposure. For @Counter annotation, avoid using any attribute other than tenant if it may contain personal data (such as user).

Support, Feedback, Contributing

This project is open to feature requests, suggestions, bug reports, etc. through GitHub issues. We encourage and welcome your contributions and feedback. For more information about how to contribute, see ourContribution Guidelines, which include details about the project structure and additional contribution information.

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 or copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.