As a vendor, understanding your bandwidth usage is an invaluable insight into how packages are distributed across your user base and how specific users have grown over a timeframe.

As a user base grows from 10s, 100s, and 1000s of users and package downloads are many multiples of your total number of users, it's essential to understand the distribution of your bandwidth utilisation by a user (or more precisely, entitlement token's) to aid in the identification of token's that make up a large percentage of your overall traffic.

When providing an entitlement token to a user under a specific license, you trust an entitlement token will be used to download packages upon the agreed-upon terms. However, an increase in your total bandwidth may start off slow and continuously grow over several months until it's suddenly become a massive increase in your overall bandwidth. Understanding this usage and precisely where this growth originates helps identify where/where change occurs and provides options to mitigate runaway bandwidth from specific entitlement tokens by changing how those specific users are managed.

How does it work?

Whenever a user downloads a package via an entitlement token, the exact number of bytes transmitted from our servers to the user host is stored for that specific token as an individual log entry. At the end of each day, we calculate the total bandwidth for every user across all of our repositories containing one or more packages and store the result as a daily aggregated value representing bandwidth usage.

The easiest way to get started exploring these metrics is to check out the metrics command within the Cloudsmith CLI. Alternatively, to get more fine-grained metrics, you can implement a programmatic solution using our API or one of the API binding libraries published in various languages.

Getting started quickly! Using the Cloudsmith CLI you can quickly and easily query the total bandwidth usage for your repository by running the following command with your organisation/repository:

cloudsmith metrics tokens OWNER/REPOSITORY

For Example:

cloudsmith metrics tokens demo/examples-repo

The following screenshot shows an example repository containing a number of active and inactive entitlement tokens alongside the total bandwidth used. The statistics table provides a simple insight into min/max/average token usage.

You can also retrieve usage metrics for one or more specific tokens by providing a comma-separated list of Entitlement token identifiers:

cloudsmith metrics tokens cloudsmith/example --tokens=ZGCV58VqT8Sl

If you wish to drill down further into a specific period of usage for a token, you can supply time and date for the start and finish parameters to filter for usage within that period. In this example, a single token is displayed for all of 2019:

cloudsmith metrics tokens cloudsmith/example --tokens=ZGCV58VqT8Sl --start=2019-01-01T00:00:00Z --finish=2019-12-31T00:00:00Z

It's that simple to get started!

You can find more information about Entitlement Tokens in our documentation.