Count and monitor user licenses with the CloudBees User Activity Monitoring plugin

4 minute read

The CloudBees User Activity Monitor plugin provides a dashboard summary of recent user activity and Comma-Separated-Values (CSV) exports of user access details. You can track user activity for a standalone controller or use the operations center to aggregate user information for all connected controllers. The plugin starts monitoring the user activity as soon as it is installed. It does not recompute activity prior to installation.

This plugin is not intended to provide an authoritative, precise measure of the number of users. It is intended to provide a reasonable approximation of user activity for discussion with your CloudBees account team. If you require a more robust licensing management solution, CloudBees CI license usage is available for CloudBees Software Delivery Automation and provides continuous monitoring to maintain a many-to-one mapping of email addresses for a given user, a visual representation of CloudBees CI licenses and their active users, and an API to create custom license usage reports. For more information about CloudBees Software Delivery Automation, contact your CloudBees sales representative.

User data collection

The User Activity Monitoring plugin collects user activity data from two type of events:

  • Authentication (AUTH): A record of every time a user logs into the CloudBees CI instance.

  • Source control management (SCM): A system that tracks changes to a source code repository.

The information collected from users includes:

  • username: Jenkins username or the username extracted from the author.email from the SCM

  • email: Jenkins email or author.email from the SCM

  • accessType: AUTH or SCM

  • lastSeen: The last time a user was tracked using CloudBees CI using a specific access type

User counting

User Activity Monitoring counts and distinguishes between users in a CloudBees CI instance. Per the CloudBees Subscription and Services agreement, a user "is an individual authorized by Customer to log into and use the CloudBees subscribed Products directly or an individual authorized by Customer to perform code commits into a source control management system triggering jobs in or reporting results through CloudBees Products. The licensed User quantity is the total number of unique Users of the Products calculated over the course of the entire Subscription Term."

A user is considered unique in this report when both the username and email address are unique. However, if multiple user entries have the same email address, those entries are considered belonging to the same user even if their user names are different. For example:

user name email address

alice

alice@acme.com

alice2

alice@acme.com

alice

alice@gmail.com

bob

bob@acme.com

bob2

bob@gmail.com

  • The unique users are alice, bob, and bob2 because they each have different email addresses.

  • The user alice2 is considered the same as alice because alice2 shares the same email address.

How unique users are counted:

  • Users are counted from AUTH and SCM access types.

  • Two users are considered the same if they have the same username or if they share the same email address. This approach allows deduplicating most of the users that are stored in a CloudBees CI instance.

Accessing the User Activity dashboard

The User Activity dashboard summarizes user activity with a data retention policy of 40 months. The dashboard displays the 50 most recent user activity entries.

To access the User Activity dashboard, select Manage Jenkins  User Activity.

You must be signed in to a controller or the operations center with Administer permissions to access the User Activity dashboard.
User Activity dashboard
Figure 1. User Activity dashboard
  1. User activity listing: This table lists user activity tracked by the plugin by username, email address, date of last activity, and a user access type of either authenticated (AUTH) or Source Control Management (SCM).

    • Authenticated user access type: Users that are signed in using CloudBees authentication and perform actions directly on the system. These users are indicated by a key key icon icon.

    • SCM user access type: Users that perform code commits to a Source Control Management (SCM) tool that triggers jobs or reports results through CloudBees products. These users are indicated by a source control source control icon icon.

      The 50 most recent users are displayed on the dashboard. For all user activity for the past 40 months, select Download Report.
  2. Total users: Displays the total number of user activity entries (before deduplication).

  3. Unique users: Displays the total number of unique users (after deduplication).

  4. Enter a number of days or months and select Refresh to filter user activity.

  5. Select Download report to download a report containing all user activity for the past 40 months. The report is a CSV file and named user-access-monthly-yyyy-MM-dd-HH-mm-ssss.csv. For more information, refer to Generate reports.

Identifiying users within SCMs

The User Activity Monitoring plugin uses the following fields to identify users.

User Activity Method User Identifier

Instance direct login

username

SCM: git

author.email [1]

SCM: Subversion

user

SCM: Perforce

author

SCM: all other SCM systems

author

1: To limit duplication for Git repositories, the plugin tracks author.email instead of author.name. Research shows that people tend to define slightly different author.name values for each git tool they use.

Generate Reports

If you are only operating a few instances, you can generate detailed user activity reports on a per-controller basis by selecting Download Report.

download report button
Figure 2. Download Report

The report generated is downloaded to the local machine and named user-access-monthly-yyyy-MM-dd-HH-mm-ssss.csv. For example, a report labeled user-access-monthly-2019-07-24-16-34-36-488 indicates a report downloaded on the date 2019-07-24 at the time of 16:34:36:488.

The user activity report is generated in Comma-Separated Values (CSV) format, with a single column labeled FIRST_DAY_OF_MONTH NAME ACCESS_TYPE. This column contains the following information:

  • The first day of the month in which the user registered activity. For example, a FIRST_DAY_OF_MONTH value of 6/1/2018 indicates that the given user logged in some time in the month of June 2018.

  • The name of the user (NAME).

  • The access type: authenticated (AUTH) or SCM (SCM).

The CSV file can be converted from a single column into multiple sortable columns with secondary processing. For example, you can open the CSV file in Microsoft Excel, select the first column of the worksheet, and use the Data  Text to columns wizard to convert the single column to multiple columns.

Download report in JSON format

Using the Jenkins CLI, download the user activity report in JSON format. Navigate to Manage Jenkins  Jenkins CLI to access the in-product CLI documentation for more information.

Contact CloudBees Customer Support

After generating your reports, contact CloudBees Customer Support to discuss the results.

In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.