Table of contents

Plugin management


Count and monitor 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 and CSV exports of user access details.

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."

Note

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.

Prerequisites

  1. The plugin must be installed on all instances for which you want to report user activity, including CloudBees Core Operations Center instances, CloudBees Masters or Jenkins masters.

  2. The Jenkins version must be greater than or equal to 2.7.4.

  3. If you want to aggregate user activity, you must have console access to each instance.

  4. The jq tool must be installed.

Installation procedure

To install the User Activity Monitoring Plugin, repeat this process as needed on each instance:

  1. Log into the instance.

  2. Navigate to Manage Jenkins  Manage Plugins.

  3. Select the Available tab.

  4. Locate and select the User Activity Monitoring Plugin.

  5. Click on the Install without restart button to install the plugin (if the plugin is already installed, upgrade the plugin and then restart).

  6. Verify that the plugin is installed by navigating to Manage Jenkins and confirming that a User Activity entry now exists on the page:

    The User Activity menu item

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 Manage Jenkins  User Activity, which displays the dashboard:

The User Activity Monitoring dashboard

Summary

The User Activity Monitoring dashboard Summary section

The "Summary" section of the dashboard displays the following values:

  • User activity was monitored since indicates the start date of user activity monitoring. This is a window of the previous 12 months, starting with the date the plugin was installed.

    • The plugin does not recompute activity from before the plugin was installed.

    • User activity is aggregated weekly, with weeks starting on Sunday. Therefore, the monitor start date is the Sunday before the day the plugin was installed.

  • Authenticated Users are users that authenticated through the instance’s login mechanism.

  • SCM users are "source control management" users for whom the instance builds or processes code, as reported through build logs.

Detailed Activity Report

The User Activity Monitoring dashboard Detailed Activity section

You can generate detailed user activity reports for each instance by clicking on Generate Reports.

Important

This section uses the instance’s GUI to generate reports, and these instructions are only suitable if you have one or only a few instances. If you’re monitoring user activity across many instances, you should consult Aggregating user activity across multiple instances for a more efficient method of collecting user activity data.

Each report details activity per user and per week, and reports are generated for both user activity and user SCM activity.

Reports are stored on the instance’s file system under $JENKINS_HOME/user-activity-reports, named as follows:

  • User authentication reports are named auth-access-weekly-${timestamp(yyyy-MM-dd-HH-mm-ssss)}.csv

  • User SCM activity reports are named scm-access-weekly-${timestamp(yyyy-MM-dd-HH-mm-ssss)}.csv

The reports are formatted as Comma-Separated Values (CSV), with the following columns:

  • FIRST_DAY_OF_WEEK: The Sunday of the week during which the user was active.

  • NAME: The name or identifier of the user.

  • LAST_SEEN: A timestamp in yyyy-MM-dd-HH-mm-sss format indicating the last time the user was active.

User identifiers

The User Activity Monitoring Plugin uses the following identifiers to track users.

User Activity Counter User Identifier

Instance authentication/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!

Aggregating user activity across multiple instances

Note
The get-user-activity-monitoring-reports.sh script requires CloudBees Core version 2.150 or later.

If you are monitoring user activity for a large number of instances, using Manage Jenkins  User Activity and clicking Generate Reports for each instance doesn’t scale.

Instead, you should use scripted operations to gather information from all of your instances at once, and to aggregate user activity data into a single report.

Preparing to run the reporting scripts

First, prepare your system:

  1. Install and configure the Jenkins CLI Tool.

  2. Create a directory where you will store your reports.

  3. Go to the https://github.com/cloudbees/user-activity-monitoring-scripts GitHub repository.

  4. Download the following scripts and save them in the directory you created:

    1. get-user-activity-monitoring-reports.sh

    2. count-user-activity.sh

    3. merge-user-activity-monitoring-reports.sh

    4. CountUsers.groovy

    5. MergeReports.groovy

  5. Log into Operations Center and create a new API token on your user settings for the reporting operation:

    1. In the Operations Center UI, locate your username in the upper right corner.

    2. Click on the down arrow next to your username, and choose Configure.

    3. Create a new token by clicking Add New Token.

    4. Provide an informative name and click Generate.

    5. Before exiting Operations Center, copy the token value to the clipboard or another safe place.

  6. 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=<USER ID> (2)
    JENKINS_API_TOKEN=<API TOKEN> (3)
    1. The URL of your Operations Center instance.

    2. Your Operations Center user ID; if you’re not sure what this is, look at the Operations Center URL, and the user ID appears after the /user/ section.

    3. Remember the API token you saved earlier? Use that value here.

Run the reporting scripts

After you’ve prepared your system, run the reporting scripts:

  1. Execute get-user-activity-monitoring.sh, which creates two directories:

    • /out/reports contains the user activity reports for each master.

    • /out/logs contains the logs from the script operation.

  2. Execute merge-user-activity-monitoring-reports.sh, which creates a report:

    • /out/aggregated-user-activity.json contains a list of all authAccess and scmAccess entries.

  3. Finally, execute count-user-activity.sh, which generates a report (also sent to stdout):

    • /out/aggregated-user-activity-summary.json provides a consolidated view of user activity across all instances.

Next steps

After running count-user-activity.sh, you should contact CloudBees Customer Support and review the results together.