License usage

3 minute readDeveloper productivityData analytics

The license usage reports, licenseReport and userReport, provide visibility into an organization’s CloudBees CI usage to ensure it is compliant with its license entitlements. These reports provide an accurate list of unique CloudBees CI users across all their controllers during a time period.

To try out these reports via the REST API endpoint, scroll to the report section of the CloudBees Software Delivery Automation swagger playground found here: https://<cloudbees-cdro-server>/rest/doc/v1.0/. See Using the RESTful API for complete information about accessing the CloudBees Software Delivery Automation RESTful API.

To try them out from a command line, see the licenseUsage commands. See CloudBees Software Delivery Automation command line access for complete information about command line access to CloudBees Software Delivery Automation APIs.

License report

The license report returns the license information details for a CloudBees CI controller or an operations center. When a CloudBees CI or operations center instance has several licenses, the one that applies is the last one, that is, the one with the newest timestamp sent from CloudBees CI. There can be only one license in existence per controller at one time.

End points

REST API endpoint
https:<cloudbees-cd-server>/rest/v1.0/runLicenseReport
ectool command
ectool runLicenseReport

Request and response formats

For complete information about request parameters and response format, see runLicenseReport.

licenseReport example

Using the REST API:

JSON response: https://<cloudbees-cdro-server>/rest/v1.0/runLicenseReport

Using ectool command line interface:

XML response:  ectool runLicenseReport
JSON response: ectool --format json runLicenseReport
Response body

The response body example below shows 15 available seats, 2 active users, 13 remaining seats

XML
Json
<response requestId="1" nodeId="10.0.0.23">
    <result>
      <total>12</total>
      <availableSeats>15</availableSeats>
      <startsAt>2021-04-30T00:00:00.000Z</startsAt>
      <controllerUrl>http://<cloudbees-ci-controller></controllerUrl>
      <activeUsers>2</activeUsers>
      <savedAt>2021-04-30T17:51:14.397Z</savedAt>
      <remainingSeats>13.00</remainingSeats>
      <url>http://<cloudbees-ci-controller></url>
      <url_count>12</url_count>
      <expiresAt>2021-05-14T23:59:59.000Z</expiresAt>
    </result>
  </response>
{
  "result": [
    {
      "total": "10",
      "availableSeats": "15",
      "startsAt": "2021-04-30T00:00:00.000Z",
      "controllerUrl": "<cloudbees-ci-controller>",
      "activeUsers": "2",
      "savedAt": "2021-04-30T17:51:14.397Z",
      "remainingSeats": "13.00",
      "url": "<cloudbees-ci-controller>",
      "url_count": "10",
      "expiresAt": "2021-05-14T23:59:59.000Z"
    }
  ]
}
Confirmation from the Jenkins user dashboard

Screenshot below from the Jenkins user dashboard confirms a license for 15 users.

User report

The user report produces a list of users based on the applied time filter. If the selected time period is undefined, it selects all users since the license started. A new user entry appears in the report when:

  • The user has logged in the CI system in the selected period.

  • The user has committed in the selected period and it has triggered a new build.

Endpoints

REST API endpoint
https:<cloudbees-cd-server>/rest/v1.0/runUserReport[&optional-query-parameters]
ectool command
ectool runUserReport [optional parameters]

Request and response formats

For complete information about request parameters and response format, see runUserReport.

userReport example

Using the REST endpoint.

XML:  https://<cloudbees-cdro-server>/rest/v1.0/runUserReport?format=xml
JSON: https://<cloudbees-cdro-server>/rest/v1.0/runUserReport?format=json
CSV:  https://<cloudbees-cdro-server>/rest/v1.0/runUserReport?format=csv

Using the ectool command line interface.

XML:  ectool runUserReport
JSON: ectool --format json runUserReport
CSV:  ectool runUserReport --format csv

Response body includes user information for the two active users.

XML
Json
CSV
<responses version="2.3" dispatchId="4857" nodeId="10.0.0.23">
  <response requestId="1" nodeId="10.0.0.23">
    <result>
      <lastLogin>1620330412892.00</lastLogin>
      <loginsCount>4.00</loginsCount>
      <lastLogin_label>2021-05-06T19:46:52.892Z</lastLogin_label>
      <id>b642b421-7b34-31e8-93bd-915fc65c4452</id>
      <category>login</category>
      <email>test@test.com</email>
      <status>success</status>
      <username>test</username>
    </result>
    <result>
      <lastLogin>1620325991029.00</lastLogin>
      <loginsCount>2.00</loginsCount>
      <lastLogin_label>2021-05-06T18:33:11.029Z</lastLogin_label>
      <id>77986701-a1b4-3385-b4e0-7ed70be36f67</id>
      <category>login</category>
      <email>admin@cloudbees.com</email>
      <status>success</status>
      <username>admin</username>
    </result>
  </response>
</responses>
{
   "requestId" : "1",
   "result" : [
      {
         "email" : "test@test.com",
         "lastLogin_label" : "2021-05-06T19:46:52.892Z",
         "status" : "success",
         "loginsCount" : "4.00",
         "lastLogin" : "1620330412892.00",
         "category" : "login",
         "id" : "b642b421-7b34-31e8-93bd-915fc65c4452",
         "username" : "test"
      },
      {
         "email" : "admin@cloudbees.com",
         "lastLogin_label" : "2021-05-06T18:33:11.029Z",
         "status" : "success",
         "loginsCount" : "2.00",
         "lastLogin" : "1620325991029.00",
         "category" : "login",
         "id" : "77986701-a1b4-3385-b4e0-7ed70be36f67",
         "username" : "admin"
      }
   ]
}
lastLogin,loginsCount,lastLogin_label,id,category,email,status,username
1620330412892.00,4.00,2021-05-06T19:46:52.892Z,"b642b421-7b34-31e8-93bd-915fc65c4452",login,test@test.com,success,test
1620325991029.00,2.00,2021-05-06T18:33:11.029Z,"77986701-a1b4-3385-b4e0-7ed70be36f67",login,admin@cloudbees.com,success,admin
Confirmation from Jenkins Users dashboard

Screenshot below from the Jenkins user dashboard confirms two active users.

Additional API interfaces

These reports can also be accessed via API by these additional CloudBees Software Delivery Automation API inferfaces: