CDS pluginCDS plugintypeInstalls into a CAP project and extends the runtime. CAP loads it through cds.requires or the plugin hook.See every one →What this type is →by a community orgby a community orgoriginPublished by a community organisation, so it outlives any one maintainer.See every one →

@cap-js-community/business-metrics

An extension of @cap-js/telemetry 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 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

Latestv1.0.0ReleasedLast pushLicenceApache-2.0

Where it sits

Lives in
Provides
TelemetryCAPTelemetrycapabilitySeeing what a running service did — traces across handlers and database calls, metrics, and correlation that survives an async boundary.
Flavors
Node.jsfrom its runtime
Requires
@sap/cds≥ 9@sap/cdsartifactThe peer range, as published.@cap-js/telemetry@cap-js/telemetryartifactThe metrics are produced through the telemetry plugin this library extends, and its README lists telemetry enabled in the CAP application configuration among the prerequisites.

Who is behind it

cap-js-communitycap-js-communityOrganisationMaintains this
In the atlas: maintains 10
@cap-js-community
maintainerashutoshtghoratPersonContributes to this
In the atlas: contributes to 1
@ashutoshtghorat
BhoomikaPersonContributes to this
In the atlas: contributes to 1
@bhoomikabedra
Christian GeorgiPersonContributes to this
In the atlas: maintains 1, contributes to 53
@chgeo
Harshith Kumar ReddyPersonContributes to this
In the atlas: contributes to 1
@hrsthrdy
KS-PrathikshaPersonContributes to this
In the atlas: contributes to 1
@KS-Prathiksha
KSPrathikshaPersonContributes to this
In the atlas: contributes to 1
@KSPrathiksha
PrathikshaKSPersonContributes to this
In the atlas: contributes to 1
@PrathikshaKS
M SahuPersonContributes to this
In the atlas: contributes to 2
@sahumadhusudan
sjvansPersonContributes to this
In the atlas: contributes to 45
@sjvans
9 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.
SAP Developer License Agreement 3.2 CAP →

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 to1Beta

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.Node.js, JavaCovers, under conditionsmetrics declared in the model

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

All options on the Telemetry page →

Connections2

@cap-js-community/business-metrics connections@cap-js-community/business-metricsPROVIDES→ provides1provides stated Emits counter and gauge metrics declared in the CDS model: a counter per annotated entity CRUD event or action call, and a gauge over the numeric fields an entity annotation names, with the tenant as the one available dimension. Business-metrics — README, About this project: https://raw.githubusercontent.com/cap-js-community/business-metrics/eee01d0e28e5a76bdb3d58900f8068d516d1ab17/README.md Business-metrics — README, Features: https://raw.githubusercontent.com/cap-js-community/business-metrics/eee01d0e28e5a76bdb3d58900f8068d516d1ab17/README.md Business-metrics — README, Features: https://raw.githubusercontent.com/cap-js-community/business-metrics/eee01d0e28e5a76bdb3d58900f8068d516d1ab17/README.md Business-metrics — README, Counting Annotation: https://raw.githubusercontent.com/cap-js-community/business-metrics/eee01d0e28e5a76bdb3d58900f8068d516d1ab17/README.mdTelemetryNEEDS→ needs1needs stated The metrics are produced through the telemetry plugin this library extends, and its README lists telemetry enabled in the CAP application configuration among the prerequisites. Business-metrics — README, About this project: https://raw.githubusercontent.com/cap-js-community/business-metrics/eee01d0e28e5a76bdb3d58900f8068d516d1ab17/README.md Business-metrics — README, Requirements and Setup: https://raw.githubusercontent.com/cap-js-community/business-metrics/eee01d0e28e5a76bdb3d58900f8068d516d1ab17/README.md@cap-js/telemetry

Install

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

Derived from the package name. No recipe recorded; the README has the configuration.

README

quoted from cap-js-community/business-metrics under Apache-2.0, read
cap-js-community/business-metrics/README.mdOn GitHub

Business-metrics

REUSE status

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

Apache-2.0, read

History

Latest

v1.0.0

Features 1

Notes
Added
  • Initial release
5downloads per week, npm
Weekly downloads for @cap-js-community/business-metrics26 complete calendar weeks from 2026-05-11 to 2026-11-08; the latest total is 5.11 May – 17 May: 018 May – 24 May: 025 May – 31 May: 01 Jun – 7 Jun: 08 Jun – 14 Jun: 015 Jun – 21 Jun: 6622 Jun – 28 Jun: 22029 Jun – 5 Jul: 96 Jul – 12 Jul: 1713 Jul – 19 Jul: 1320 Jul – 26 Jul: 727 Jul – 2 Aug: 43 Aug – 9 Aug: 410 Aug – 16 Aug: 617 Aug – 23 Aug: 424 Aug – 30 Aug: 1131 Aug – 6 Sept: 47 Sept – 13 Sept: 614 Sept – 20 Sept: 3521 Sept – 27 Sept: 428 Sept – 4 Oct: 35 Oct – 11 Oct: 312 Oct – 18 Oct: 919 Oct – 25 Oct: 1326 Oct – 1 Nov: 202 Nov – 8 Nov: 5
Telemetry
  1. com.sap.cds:cds-services-bomMaven bill of materials pinning CAP Java module versions
  2. @cap-js/telemetryOpenTelemetry instrumentation for CAP services
  3. cds-cachingCAP caching plugin for query results and remote service responses
  4. cap-mcp-guardPolicy enforcement and field masking for MCP-enabled CAP apps
  5. @sanjay-sde/cap-js-log-controlCAP plugin controlling CDS logger and OpenTelemetry log verbosity
  6. @sap-ux/telemetryLibrary for sending usage telemetry data
  7. cap-ui-telemetryUI5 frontend performance and error capture for CAP
  8. opentelemetry-cdsOpenTelemetry support for the CDS Node.js runtime

Details

Sources5
npm registrydiscovered herechecked
GitHub APIdiscovered here, cap-js-communitychecked
npm registry, @cap-js-community/business-metricsversion, releases, installschecked
github.com/git+https://github.com/cap-js-community/business-metrics.gittree, pushes, contributors, CIchecked
README.mdquoted, and what the entry declareschecked

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
runtimesnode
declared for>=9
latestv1.0.0
first release
releases and cadence2
discovered vianpm registry, GitHub API · cap-js-community
first seen in the atlas
ecosystem and domaincap, operations-and-runtime
Contributors9
History in the atlas2
  1. what it does for telemetry, its two stated properties, and the edge to the plugin it extends
  2. First seen.
For your agent
Ref
artifact:cap-js-community-business-metrics
JSON
/artifacts/cap-js-community-business-metrics.json
MCP
Connecting an agent