Counting and monitoring user licenses with User Activity Monitoring
The User Activity Monitoring plugin helps you understand licensing and entitlement. It provides you with a summary of user activity, CSV exports of user access details, and JSON reports that can be exported to other applications.
This topic explains how to install the plugin, prepare your instance or instances for reporting, and generate reports.
What counts as a user?
User means "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."
This plugin is not intended to provide an authoritative, precise measure of the number of subscribed users; it is intended to provide a reasonable approximation of user activity for discussion with your CloudBees account team. |
How users are counted
The User Activity Monitoring plugin generates data about user activity on your instance (or instances) over time. There are two different ways you can use the plugin to understand your user activity.
-
For standalone installation: if you only have one master, you may just want a quick and simple accounting of user activity for each instance. If you have more than one master, you must consolidate the data.
-
For large scale installation: if you’re responsible for hundreds or even thousands of instances with a very large and active user base, the instance-by-instance approach doesn’t scale. For administrators who need to aggregate user information at scale, please see large-scale approach.
How duplicate entries are handled
To avoid duplicates, use the same user IDs in your identity provider (LDAP, SAML, etc) and your SCM because Jenkins creates local users from both sources. |
Duplicate user activity entries are automatically managed both within masters and across masters (for situations where you are managing multiple instances). For example, if user-one@example.com
appears on multiple instances, those entries will be deduplicated and only one entry for user activity will be recorded for a given time period.
For installations with multiple instances, deduplication requires that the user is referenced with the same identifier on all of the instances: see how users are identified for details on how individual users are identified. For example, user-one@example.com
will be deduplicated if the user uses the same email address on multiple instances, even if the user appears as an authenticated user in one instance and an SCM user in another.
Deduplication occurs constantly at the master level, and is reflected in the User Activity dashboard in both the number of users and the list of users. Deduplication across masters occurs when the user activity aggregation scripts are executed.
Installing on a standalone installation
If you’re only managing a few instances, it may be more convenient to manually install the plugin on each instance. However, as soon as you have more than one master, you must consolidate the data.
To install the plugin manually, repeat this process on each Operations Center and master instance:
-
Log into the instance.
-
Navigate to
. -
Select the Available tab.
-
Locate and select the User Activity Monitoring plugin.
-
Click on the Install without restart button to install the plugin (if the plugin is already installed, upgrade the plugin and then restart).
-
Verify that the plugin is installed by navigating to Manage Jenkins and confirming that a User Activity entry now exists on the page:
Installing on a large scale installation
The large-scale approach is intended for those administrators who are dealing with multiple hundreds of instances and many thousands of users.
This approach uses several scripts to automate operations and make your data consistent. These scripts will be executed from a local server.
Preparing for the installation
-
First, visit the https://github.com/cloudbees/user-activity-monitoring-scripts GitHub repository maintained by CloudBees.
-
Download all of the following scripts to a single directory:
-
install-user-activity-monitoring-plugin.sh
-
get-user-activity-monitoring-reports.sh
-
merge-user-activity-monitoring-reports.sh
-
count-user-activity.sh
-
CountUsers.groovy
-
MergeReports.groovy
-
-
Log into Operations Center, go to your User Settings, and create an API token for the reporting operation:
-
Locate your username in the upper right corner of the Operations Center UI:
-
Click on the down arrow next to your username, and choose Configure:
-
Create a new token by clicking Add New Token:
-
Provide an informative name and click Generate:
-
Before exiting Operations Center, copy the token value to the clipboard or another safe place:
-
-
Create a file named
.env
in the same location as you saved the scripts. Populate the.env
file with these values:OPS_CENTER_URL=<URL> (1) JENKINS_USER_ID=<USERNAME> (2) JENKINS_API_TOKEN=<API TOKEN> (3)
1 The URL of your Operations Center instance. 2 The username for the CloudBees CI administrator. 3 The API token you generated earlier.
Installation methods
There are two ways to install the plugin on a large scale.
Installing using a cluster operation
Installing the plugin with a cluster operation is the less complicated method of handling a large plugin install.
-
Log into your Operations Center instance.
-
Using the left-side navigation menu, click on New Item.
-
In the New Item interface:
-
Provide an informative name for the new operation (1)
-
Select cluster operation (2)
-
Click on the OK button to save the new cluster operation (3)
-
-
In the cluster operation interface, select Execute concurrent builds if necessary. This permits the Operations Center to perform multiple installs at the same time, instead of one install at a time.
-
Click on the Operations tab or scroll down to the Operations section, and add the following operations in sequence:
-
Click on Add Operation, and select Masters. This indicates that the cluster operation will be performed on the masters connected to Operations Center.
-
Under Source, select From Project Parent. This specifies the scope of the source information, which in this case is a list of masters. From Project Parent indicates that the search for sources should begin in the folder above the folder in which the project is stored.
-
Under Filters, click Add Filter and select Managed Master / Client Master is Online. This specifies that Operations Center will filter the list of masters to only those masters that report that they’re online.
-
Under Steps, click Add Step and select Refresh update center metadata. This step forces the Update Center to refresh its information from the CloudBees servers before performing the cluster operation, and guarantees that the most recent version of the plugin is available.
-
Under Steps, click Add Step and select Install plugin. Change the plugin ID placeholder text to read
user-activity-monitoring
, and the Version placeholder text to read the most recently released version of the plugin. -
Finally, under Steps, click Add Step and select Safe Restart. This performs a "safe restart" on the master instance after the plugin is installed.
-
-
Click the Save button to create and save the cluster operation.
-
The Operations Center will return you to the Operation summary page.
-
Click on Run to start the cluster operation.
Verifying the results of the cluster operation
-
The Build History status indicator shows the progress of the cluster operation:
-
Once the cluster operation completes, click on the down arrow to the right of the build number and select Console Output to review the console output:
-
The console log, if the cluster operation was successful, should look something like this:
Started by user Administrator Running as SYSTEM Building in workspace /Users/testuser/operations-center-one/workspace/deploy-user-activity-monitoring Started #1 master-one (log) #1 master-one finished successfully. master-one: SUCCESS Finished: SUCCESS
-
Clicking on the
log
link for a master (in this case,master-one
), presents a master-level log of the cluster operation. In this case, it looks like this:Started Masters operation on master-one Updating update center core-cm-offline Using UpdateCenter.updateDirectlyNow OK: Requested synchronous update Updated. Updating update center cap-core-cm Using UpdateCenter.updateDirectlyNow OK: Requested synchronous update Updated. com.cloudbees.opscenter.server.clusterops.steps.ClusterOpsResult@104eea0d com.cloudbees.opscenter.server.clusterops.steps.ClusterOpsResult@2c40a396 The plugin 'user-activity-monitoring' is already installed, version '1.1.5' Installed version '1.1.5' is newer than requested version '1.1.5' The plugin 'user-activity-monitoring' is already enabled and active, nothing to do
Installing using shell scripts
Installing using shell scripts is a slightly more labor-intensive method of installing the plugin across a large number of masters.
-
Confirm that you’ve downloaded the required scripts, that both
wget
andjq
are present, and that the.env
file exists and is populated with the correct values. -
First, run the
install-user-activity-monitoring-plugin.sh
script to install the plugin on the list of masters retrieved from Operations Center:shell$ ./install-user-activity-monitoring-plugin.sh Using .jenkins/jenkins-cli.jar. Collecting list of masters...Jul 17, 2019 7:29:09 AM org.apache.sshd.common.util.security.AbstractSecurityProviderRegistrar getOrCreateProvider INFO: getOrCreateProvider(EdDSA) created instance of net.i2p.crypto.eddsa.EdDSASecurityProvider done Install plugin on masters... * master-one: ko
-
Next, run the
get-user-activity-monitoring-reports.sh
script to generate JSON reports for each master and store those reports in the local/out/reports
directory:shell% ./get-user-activity-monitoring-reports.sh Using .jenkins/jenkins-cli.jar. Collecting list of masters...Jul 17, 2019 7:47:11 AM org.apache.sshd.common.util.security.AbstractSecurityProviderRegistrar getOrCreateProvider INFO: getOrCreateProvider(EdDSA) created instance of net.i2p.crypto.eddsa.EdDSASecurityProvider done Generate user activity report on... * master-one: ko
-
Next, run the
merge-user-activity-monitoring-reports.sh
script to generate a unique report called/out/aggregated-user-activity.json
that contains a list of both authenticated and SCM users:shell% ./merge-user-activity-monitoring-reports.sh Merging user activity reports ... Reading individual reports from: out/reports/ File out/aggregated-user-activity.json generated
-
Finally, run the
count-user-activity.sh
script to populate a summary of the total user count to the file/out/aggregated-user-activity.json
, and display the result tostdout
:shell% ./count-user-activity.sh 1 user(s) counted as Authenticated from 2018-10-28 to 2019-02-03 3 user(s) counted as SCM contributor from 2018-10-28 to 2018-12-30 4 user(s) counted as CloudBees Core users from 2018-10-28 to 2019-02-03 Detailed summary available in: ./aggregated-user-activity-summary.json
The User Activity dashboard
The User Activity Monitoring dashboard summarizes user activity after the date of the plugin’s installation, with a data retention policy of one calendar year.
To see the User Activity dashboard, click on
, which displays the dashboard:The dashboard provides the following information:
-
User activity was monitored since field: The amount of time for which user activity has been monitored. This value is a window of the previous 12 months of activity, starting from the date the plugin was installed.
-
The total number of users tracked by the plugin.
The "User activity was monitored since" field
This field reflects the amount of time for which the User Activity Monitoring plugin has been tracking user activity. The plugin does not track activity from before the plugin was installed, and user activity is aggregated monthly.
The user listing
Users are listed by username, with the date of their last activity and the user type:
-
Authenticated users: these users are users that have logged in using CloudBees authentication and have performed actions directly on the system. These users are indicated with a key icon:
-
SCM users: these users are "source control management" users for whom the instance builds or processes code, and these users are identified through build logs. These users are indicated with a source control icon:
Generating Reports
There are two different methods to generate user activity reports:
-
On a per master basis, using the Download Report button.
-
On a large scale, using scripts.
Reporting per master
If you’re only operating a few instances, you can generate detailed user activity reports on a per master basis with the Download Report button:

The Download Report button uses the instance’s GUI to generate reports, and you should generate your user activity reports with Download Report only if you have one to three instances. If you’re monitoring user activity across many instances, you should consult large-scale reporting using scripts for a more efficient large-scale method of collecting user activity data. Using this method means that you will have to combine reports for each instance. |
The report generated by Generate Report is downloaded to the local machine and named user-access-monthly-yyyy-MM-dd-HH-mm-ssss.csv
. For example, 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 report is formatted as Comma-Separated Values (CSV), 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 of6/1/2018
indicates that the given user logged in sometime in the month of June, 2018. -
The name of the user (
NAME
). -
The access type: either 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 | wizard to convert the single column to multiple columns.
Reporting for large-scale installations using scripts
This scripted process is mostly used for large-scale reporting. However, if you use the standalone installation method on multiple masters, you still need to aggregate the reports.
These steps gather information from all of your instances at once and aggregate user activity data into a single report.
Preparing to run the reporting scripts
First, prepare your system:
-
Install and configure the Jenkins CLI Tool.
-
Create a directory to store your reports:
shell% mkdir my-reports
-
Download and install the reporting scripts, and create an
.env
file, by following the directions in Preparing for the installation.
Running the reporting scripts
After you’ve prepared your system, run the reporting scripts:
-
Execute
get-user-activity-monitoring.sh`to generate JSON reports for each master and store those reports in the local `/out/reports/
directory along with logs in/out/logs
:shell% ./get-user-activity-monitoring-reports.sh Using .jenkins/jenkins-cli.jar. Collecting list of masters...Jul 17, 2019 7:47:11 AM org.apache.sshd.common.util.security.AbstractSecurityProviderRegistrar getOrCreateProvider INFO: getOrCreateProvider(EdDSA) created instance of net.i2p.crypto.eddsa.EdDSASecurityProvider done Generate user activity report on... * master-one: ko
-
Execute
merge-user-activity-monitoring-reports.sh
, which creates the/out/aggregated-user-activity.json
report. This report contains a list of allauthAccess
andscmAccess
entries:shell% ./merge-user-activity-monitoring-reports.sh Merging user activity reports ... Reading individual reports from: out/reports/ File out/aggregated-user-activity.json generated
The resulting JSON file contains entries such as:
{ "authAccess": ["admin", "sixtythreebot@example.com", "automation" ...], "scmAccess": ["user-one@example.com", "user-two@example.com", "user-three@example.com", "user-five" ...] }
-
Finally, execute
count-user-activity.sh
, which generates the/out/aggregated-user-activity-summary.json
report (also sent tostdout
). This report provides a consolidated view of user activity across all instances:shell% ./count-user-activity.sh 1 user(s) counted as Authenticated from 2018-10-28 to 2019-02-03 3 user(s) counted as SCM contributor from 2018-10-28 to 2018-12-30 4 user(s) counted as CloudBees Core users from 2018-10-28 to 2019-02-03 Detailed summary available in: ./aggregated-user-activity-summary.json
The resulting JSON file contains entries such as:
{ from:"2019-07-01", to: "2019-07-31", authUsers: ["admin", "sixtythreebot@example.com", "automation" ...], scmUsers: ["user-one@example.com", "user-two@example.com", "user-three@example.com", "user-five" ...], }
Next steps
After generating your reports, contact CloudBees Customer Support and discuss the results together.
Reference: What the scripts do
This section explains the scripts used for large-scale installations and well as generating reports.
install-user-activity-monitoring-plugin.sh
:
-
Collects a list of available masters from Operations Center.
-
Installs or upgrades the User Activity Monitoring plugin across many instances at once.
-
Automatically restarts masters after the script completes.
get-user-activity-monitoring-reports.sh
:
-
requires CloudBees CI version 2.150 or later.
-
Collects a list of available masters from Operations Center.
-
Generates a JSON report for each master and stores those reports in the local
/out/reports
directory.
count-user-activity.sh
:
-
Generates a summary of the user count and writes it to the file
/out/aggregated-user-activity.json
. -
Sends the result to
stdout
.
merge-user-activity-monitoring-reports.sh
:
-
Generates a unique report called
/out/aggregated-user-activity.json
. -
That report contains a list of both
authAccess
entries andscmAccess
entries. -
authAccess
denotes an authenticated user (like administrator). -
scmAccess
denotes a user who only interacts with CloudBees CI via Source Control Management (SCM), such as code checkins. -
User activity is deduplicated: that is, if
user-one@example.com
appears in user activity for multiple instances, only one user activity entry is recorded for the aggregated report.
CountUsers.groovy
: A Groovy script used by count-user-activity.sh
.
MergeReports.groovy
: A Groovy script used by merge-user-activity-monitoring-reports.sh
.