Usage statistics and billing

To view usage statistics

Requirements

APPLICATION ACCESS:

The user must have access to the Administration application of a Management tenant or an Enterprise tenant.

ROLES & PERMISSIONS:

  • To view tenants usage statistics: READ permission for the permission type “Tenant management”.

The Usage statistics page provides statistical information on each subtenant.

Subtenant statistics

The following information is provided for each subtenant (not completely visible in the screenshot above due to space restrictions):

Field Description
ID ID of the subtenant
Tenant Name of the subtenant
API requests Total number of API requests, including requests from devices and applications
Device API requests Number of API requests from devices
Storage (MB) Amount of data stored in your account
Peak storage (MB) Peak value of storage
Root devices Number of root devices excluding child devices, see also Devices count details
Peak root devices Peak number of root devices, excluding child devices
Devices Total number of devices connected to the subtenant, including child devices
Peak devices Peak number of devices, including child devices
Endpoint devices Leaf machines, without gateways and edges
Subscribed applications Number of applications that the subtenant is subscribed to
Creation time Date and time of the creation of the subtenant
Alarms created Number of alarms created
Alarms updated Number of updates on alarms
Inventories created Number of managed objects created
Inventories updated Number of updates on managed objects
Events created Number of events created
Events updated Number of updates on events
Measurements created Number of measurements created
Total inbound transfer Sum of all inbound transfers (alarms created, alarms updated, events created, events updated, inventories created, inventories updated, measurements created)
CPU (M) Microservice CPU usage, specified in CPU millicores, see Microservice usage for details
Memory (MB) Microservice memory usage, see Microservice usage for details
Parent tenant Name of the parent tenant (available only for Management tenant)
External reference This field is for individual usage, for example, you can add a link to the CRM system here or an internal customer number

Moreover custom properties are displayed, if configured.

Custom properties may be defined in the properties library and then set their values in the Custom properties tab of the tenant.

You can filter the usage statistics list for a time period by adding the start and end date in the top menu bar and click Apply. The Usage statistics page will show the numbers for all subtenants for this time period.

Info
If a tenant was created after the selected time period, it will show up but the numbers are “0”.

You can also filter and sort the list on any column by clicking the filter icon next to the column name and providing the filtering criteria. See also Filtering.

Important
The date/time range used here might differ from your server time due to different time zones.

To export the usage statistics table

  1. Click Export CSV at the right of the top menu bar to export the current view of the statistics table to a CSV file.
  2. In the resulting dialog box you can customize the CSV output by specifying a field separator, decimal separator and charset.
  3. Click Download to start the export.

The CSV file will be downloaded to your file system.

Devices count details

The device count calculations assume that only top-level devices are marked with the device marker fragment c8y_IsDevice. Accordingly, the following formulas are used in the calculations:

  • root devices - all devices with the c8y_IsDevice fragment
  • all devices - all devices with the c8y_IsDevice fragment and their children from the whole device hierarchy
  • leaf devices - only leafs of the device hierarchies starting from devices with the c8y_IsDevice fragment

If child devices are also marked with the c8y_IsDevice fragment, the calculation results may look different than expected.

Microservice usage

The microservice usage feature gathers information on the resource usage per subtenant for each microservice. This enables Enterprise tenants and service providers to charge tenants not only based on subscriptions but also based on resources usage.

Billing modes

Cumulocity IoT offers two billing modes:

  • Subscription-based billing - charges a constant price when a tenant is subscribed to a microservice while resource usage is assigned to the owner.

  • Resource-based billing - exposes the number of resources used by a microservice to calculate billing.

The billing modes are specified per microservice in the microservice manifest and are set in the field “billingMode”.

RESOURCES: Sets the billing mode to resources-based. This is the default mode and will be applied to all microservices that are not explicitly switched to subscription-based billing mode.

SUBSCRIPTION: Sets the billing mode to subscription-based.

Isolation level

Two isolation levels are distinguished for microservices: per-tenant isolation and multi-tenant isolation.

In case of subscription-based billing, the entire resources usage is always assigned to the microservice owner, independent of the isolation level, while the subscribed tenant will be billed for the subscription.

In case of resources-based billing, charging depends on the isolation level:

  • Per-tenant - the subscriber tenant is charged for used resources.
  • Multi-tenant - the owner of the microservice is charged for used resources.

In case of multi-tenant isolation level, the owner of a microservice (for example the Management tenant of an Enterprise tenant or a service provider) is charged for the used resources of the subtenants. The subtenants should be charged based on the subscription according to the agreement between the microservice owner and the subscribed tenant. The list of subscribed applications is available as part of the tenant applications as subscribedApplications.

Resources usage assignment for billing mode and isolation level

Billing mode Microservice Isolation Resources usage assigned to
Subscription-based Per-tenant Owner
Subscription-based Multi-tenant Owner
Resources-based Per-tenant Subscriber
Resources-based Multi-tenant Owner

Collected values

The following values are collected on a daily base for each tenant:

  • CPU usage, specified in CPU millicores (1000m = 1 CPU)
  • Memory usage, specified in MB

Microservice resources are counted based at limits defined in the microservice manifest per day. At the end of each day, the information about resource usage is collected into the tenant statistics. It is also considered that a microservice might not be subscribed for a whole day.

Example

If a tenant was subscribed to a microservice for 12h and the microservice has 4 CPU and 4 GB of memory it should be counted as 2000 CPU millicores and 2048 MB of memory.

For billing purposes, in addition to CPU usage and memory usage the cause for the billing is collected (for example owner, subscription for tenant):

{
  "name": "cep",
	"cpu": 6000,
	"memory": "20000",
	"cause": "Owner"
},
{
  "name": "cep-small",
  "cpu": 1000,
  "memory": "2000",
  "cause": "Subscription for tenant"
}

The information on the microservice usage is presented in the Usage statistics page.

Tenant statistics

For more details, refer to Tenants in the Cumulocity IoT OpenAPI Specification. Note that details are available only for daily usage. For a summary query only the sum of all issued requests is returned.

Scaling

Auto-scaling monitors your microservices and automatically adjusts capacity to maintain steady, predictable performance at the lowest possible cost. It is easy to configure the microservice scaling by setting the property scale in the Microservice manifest.

For instance, when you have a microservice with scale policy set to AUTO and the CPU usage points that it is needed to start a new microservice instance for three hours, the billing logs: (24/24 + 3/24) * consumed resources.

  • 24/24 - one instance active for the whole day
  • 3/24 - second instance active only three hours

Note that an audit record is created for every change of the number of instances.

For more information, refer to Audits in the Cumulocity IoT OpenAPI Specification.

Timezone handling

Important
Cumulocity IoT platform servers by default work at UTC timezone. Other time zones are also supported by the platform and can be selected by the service provider at installation time. Thus, the general metering functionality is also guaranteed for non-UTC server time zones.

The tenant usage statistics are collected on a daily base according to the beginning of day (BOD) and the end of day (EOD), which are defined by the server timezone. As a result, if the local time zone of a user is different from the server timezone, an operation triggered by the user may be assigned to a different day according to the server time.

Examples

Request counting - Example 1
Device Server
Time zone CEST +2h UTC
Send measurement time 26.08.2020T01:30:00+02:00 25.08.2020T23:30:00Z

Result:

The request will be billed to the day 25.08.2020 as this is the server time of the request handing.

Request counting - Example 2
Device Server
Time zone UTC UTC
Send measurement time 26.08.2020T01:30:00Z 26.08.2020T01:30:00Z

Result:

The request will be billed to the day 26.08.2020 as the server time is the same as the device time.

Microservice resource billing - Example 1
User Server
Time zone CEST +2h UTC
Subscribe time 26.08.2020T12:00:00+02:00 26.08.2020T10:00:00Z
Unsubscribe time 27.08.2020T12:00:00+02:00 27.08.2020T10:00:00Z

Result:

The resources will be assigned mainly to the day 26.08.2020 as according to the UTC time zone the microservice was active for 14 hours that day and for 10 hours the next day. This might be a bit different from what a user expects as from his perspective the microservice was active for 12 hours each day.

Microservice resource billing - Example 2
User Server
Time zone KI +14h (Kiribati Islands) UTC
Subscribe time 26.08.2020T12:00:00+14:00 25.08.2020T22:00:00Z
Unsubscribe time 26.08.2020T20:00:00+14:00 26.08.2020T06:00:00Z

Result:

From the user perspective the microservice was subscribed for 8 hours at 26.08.2020 but at server time it was 2 hours before EOD of 25.08.2020 and 6 hours after BOD at 26.08.2020.

Microservice resource billing - Example 3
User Server
Time zone CEST AS -11h (American Samoa)
Subscribe time 26.08.2020T12:30:00+2:00 25.08.2020T23:30:00Z
Unsubscribe time 26.08.2020T13:00:00+2:00 25.08.2020T24:00:00Z

Result:

In this case we have a big time shift between the server and the user time. All resources will be billed to the day 25.08.2020 according to the server time.

Daily routine

Usage statistics consist of values that are progressive like the request count and values that are snapshots of a state at a given time period. In case of the second type of data, values are refreshed several times each day but the value from EOD is the value that is assigned for the given day.

Value type Refreshed
Request count flush Every 5 minutes
Used storage 9, 17 and EOD
Device count 9, 17 and EOD
Subscribed applications 9, 17 and EOD
Microservice resources 9, 17 and EOD

Lifecycle

Tenant

A Cumulocity IoT platform tenant can have several states:

  • Active - the common state when the tenant can interact with the platform. In that state all billing values are stored and updated.
  • Suspended - suspended tenants are not billed for request count and microservice resources, the only value that is still counted is the existence of the tenant and the storage size. The microservice resource usage is billed as “used”, that means, when the tenant is switched to suspended state all microservices are stopped so there are no resources to bill.
  • Deleted - this is the point of no return. The tenant is not billed for any resources but there is no way of restoring the data also.

Microservice

Any extension deployed to the platform as a microservice is billed as “used” and the billing starts according to the begin of usage. After the application is subscribed to the tenant a process of application startup is triggered which will go through several high level phases:

  • Pending - the microservice has been scheduled to be started but the Docker container is not running yet. In this state the microservice is not yet billed.
  • Scheduled - the microservice has been assigned to a node, the Docker container initialization has been started. The resources for the microservice have already been allocated so billing is started.
  • Not ready - the microservice container is not ready yet to handle incoming traffic but the application is already running.
  • Ready - the microservice container is ready to handle incoming traffic. “Ready” is resolved based on liveness and readiness probes defined in the microservice manifest. If probes are not defined then the microservice is immediately ready.

A tenant that is billed for resources can view the point in time when the microservices billing has been changed in the audit logs. The audit log entries, for example “Scaling application ‘…’ from X to Y instances” contain the information about the changes of instances and resources consumed by the microservice.

Tenants should also be able to see the full application lifecyle in the application details. In the Status tab, you can see an Events section that is showing very low level stages of the application startup. Some of the most important are:

  • Pod "apama-ctrl-starter-scope-..." created. - a new microservice instance has been scheduled to be started for the tenant. This means that the resource allocation has been successful but the application is not running yet (maps to the state “Scheduled”).
  • Pulling image "apama-ctrl-starter-scope-..." - the microservice initialization process has been started and the Docker image download is already in progress (state “Scheduled”).
  • Container created. - the microservice container has been created but not started yet (state “Scheduled”).
  • Container started. - the microservice container is started but not ready yet to handle incoming traffic (state “Not ready”).
Info
There is no event in the Events section when the microservice has reached the state “Ready” as this happens according to the readiness probe.

Audit logs and events are stored at tenant space according to the isolation level. For multi-tenant isolated microservices this is the tenant that is the owner of the microservice and in case of per-tenant isolation level it is the subscribed tenant.

Billing pricing models

The Cumulocity IoT platform collects a lot of different usage statistics data which is used for billing customers.

Based on the contract, there are two pricing models for billing:

  • Tenant usage pricing model - based on tenant usage statistics
  • Device pricing model - based mostly on device statistics and microservice resource usage

The table below presents which values are used in each model for billing purposes:

Source Name Tenant usage pricing model Device pricing model
TenantUsageStatistics ID x x
TenantUsageStatistics Tenant x x
TenantUsageStatistics API requests x
TenantUsageStatistics Device API requests x
TenantUsageStatistics Storage x x
TenantUsageStatistics Peak storage x
TenantUsageStatistics Root device x
TenantUsageStatistics Peak root device x
TenantUsageStatistics Devices x x
TenantUsageStatistics Peak devices x
TenantUsageStatistics Endpoint devices x
TenantUsageStatistics Subscribed applications x
TenantUsageStatistics Creation time x x
TenantUsageStatistics Alarms created x
TenantUsageStatistics Alarms updated x
TenantUsageStatistics Inventories created x
TenantUsageStatistics Inventories updated x
TenantUsageStatistics Events created x
TenantUsageStatistics Events updated x
TenantUsageStatistics Measurements created x
TenantUsageStatistics Total inbound transfer x
TenantUsageStatistics Parent tenant x x
TenantUsageStatistics Tenant domain x
TenantUsageStatistics Can create subtenants x
TenantUsageStatistics External reference x x
TenantUsageStatistics Total microservice CPU usage x
TenantUsageStatistics Total microservice memory usage x
MicroserviceUsageStatistics Per microservice CPU usage x
MicroserviceUsageStatistics Per microservice memory usage x
DeviceStatistics Monthly measurements, events and alarms created and updated per device x