You can view tool license usage details by calling the License Usage API. The API reads the ls_access.log.yyyy-MM-dd file stored in the DTP logs folder and returns information for the specified period. By default, logs are stored for the last 90 days. See Configuring License Server for information about changing how long logs are stored.

In this section:

Authentication

You can use basic authentication or OIDC to authenticate. See "Authentication" on the REST API page for more information about using basic authentication and Configuring OpenID Connect for more information about using OIDC.

Endpoints

The following endpoints are available:

/toolsUsage

This endpoint returns summary information about tool usage. 

URL

<protocol>://<host>:<port>/licenseserver/usage/api/v1.0/toolsUsage

Parameters 

The following table describes the parameters common to all endpoints in the API.

ParameterDescriptionTypeRequired
startDate 

Specifies the date of the first record to include in the response. 

By default, the first date in the log is included.

Format: yyyy-MM-dd 

stringOptional
endDate 

Specifies the date of the first record after the start date to exclude from the response. 

By default, no end date is specified.

Format: yyyy-MM-dd 

stringOptional

Response Data

The response is an array of tools and information about the tool usage. The following table describes the response data.

FieldDescriptionType
featuresAtMaxConcurrentLicenseTimeThe features in use at maxConcurrentLicenseTime.array of objects

count Number of license token requests served for the feature.integer

feature Name of the feature for which the license was requested.string

maxConcurrentLicenseCount

The maximum number of license tokens used for the tool at any point in time.integer
maxConcurrentLicenseTime Date and time of the most recent count of license tokens. string
tool Name of the tool.string
uniqueHostCountThe number of unique host names across the entire time period.integer
uniqueUserCount The number of unique users across the entire time period.integer
usageHours The total amount of time for which license tokens were used. The returned value is an aggregate across users and machines on which the tool is hosted. float

Example Request

The following example returns tool usage information for March 1, 2020.

https://myserver:8443/licenseserver/usage/api/v1.0/toolsUsage?startDate=2020-03-01&endDate=2020-03-2

Example Response

The following response shows that one Parasoft Jtest user requested a license for several features for a short period of time.

[
    {
        "featuresAtMaxConcurrentLicenseTime": [
            {
                "count": 1,
                "feature": "Automation"
            },
            {
                "count": 1,
                "feature": "Change Based Testing"
            },
            {
                "count": 1,
                "feature": "Coding Standards"
            },
            {
                "count": 1,
                "feature": "Coverage"
            },
            {
                "count": 1,
                "feature": "Desktop Command Line"
            },
            {
                "count": 1,
                "feature": "Flow Analysis"
            },
            {
                "count": 1,
                "feature": "Unit Test"
            }
        ],
        "maxConcurrentLicenseCount": 1,
        "maxConcurrentLicenseTime": "2020-03-01T20:18:21.369",
        "tool": "jtest!",
        "uniqueHostCount": 1,
        "uniqueUserCount": 1,
        "usageHours": 0.0025158333333333335
    }
]

/featuresUsage

This endpoint returns details about feature usage.

URL

<protocol>://<host>:<port>/licenseserver/usage/api/v1.0/featuresUsage

Parameters

This endpoint supports the common API parameters.

Response Data

The response is an array of features and information about the feature usage. The following table describes the response data.

Field
DescriptionType
featuresList of features that have been used at least once.array of strings

<feature_name> Name of feature used. Contact your Parasoft representative to learn more about available features for your tool.string
tool Name of the tool.string

Example Request

The following example returns feature usage information for March 1, 2020.

https://myserver:8443/licenseserver/usage/api/v1.0/featuresUsage?startDate=2020-03-01&endDate=2020-03-2

Example Response

The following response shows that several Parasoft Jtest features were used at least once within the specified time start and end dates.

[
    {
        "features": [
            "Automation",
            "Change Based Testing",
            "Coding Standards",
            "Coverage",
            "Desktop Command Line",
            "Flow Analysis",
            "Unit Test"
        ],
        "tool": "jtest!"
    }
]

/licenseUsage

This endpoint returns an array showing license usage, including features used, tools, and usage duration, per user.

URL

<protocol>://<host>:<port>/licenseserver/usage/api/v1.0/licenseUsage

Parameters

This endpoint supports the common API parameters.

Response Data

The response is an array of objects that describe license usage. 

FieldDescriptionType
features List of features enabled by the license.array of strings

<feature_name> Name of feature used. Contact your Parasoft representative to learn more about available features for your tool.
tool Name of the tool that consumed a license.string
toolVersion Version of the tool.string
usageHours Total number of hours the license for the tool was used by the user.float
user Host machine from which the tool was executed and user name that requested the license.  object

hostname Name of the machine from which the tool was executed.string

name User name of the tool user that requested the license token.string

Example Request

The following example returns license usage information for March 1, 2020.

https://myserver:8443/licenseserver/usage/api/v1.0/licenseUsage?startDate=2020-03-01&endDate=2020-03-2

Example Response

The following response shows that the user "devtest" used a Jtest license with several features on a machine called "lin-dtp-vm2" for a short period of time. 

[
    {
        "features": [
            "Automation",
            "Change Based Testing",
            "Coding Standards",
            "Coverage",
            "Desktop Command Line",
            "Flow Analysis",
            "Unit Test"
        ],
        "tool": "jtest!",
        "toolVersion": "10.4",
        "usageHours": 0.0025158333333333335,
        "user": {
            "hostName": "lin-dtp-vm2",
            "name": "devtest"
        }
    }
]

/licenseRejection

This endpoint returns an array of objects showing license requests that we were rejected by the server.

URL

<protocol>://<host>:<port>/licenseserver/usage/api/v1.0/licenseRejection

Parameters

This endpoint supports the common API parameters.

Response Data

The response is an array of objects that describe the license request rejections that have been logged.

FieldDescriptionType
noMoreTokens Lists the instances when a license request was rejected because no more tokens were available. array of objects

requestKey License request properties for which license have been rejected.object


requestedFeatures 

Lists the features that were requested for the tool. When a license request from a tool is made, the request applies to all tools that the user attempted to enable in the .properties file or UI configuration.  array of strings



<feature_name>

Name of feature requested. Contact your Parasoft representative to learn more about available features for your tool.string


tool 

Name of the tool for which the license request was rejected.string


toolVersion 

Version of the tool. string

responseStatistics 

Statistical information about the rejected license requests.

object



noMoreTokensCount Number of times the license request was rejected because no more license tokens were available.integer


noMoreTokensUserCount Number of users that made license requests that were rejected because no more license tokens were available.integer


noMoreTokensUsers Lists information about the users for whom license requests were rejected.array of objects



noMoreTokensCount Number of times the user requested a license. integer



noMoreTokensTime List of timestamps marking when the user requested the license.array of strings




<timestamp> 

Date and time of when the license tokens were requested. Default format: yyyy-MM-dd h:m:s:ms

string


user

Host machine from which the rejected license was requested and user name that requested the license.  object



hostName 

Name of the machine from which the license was requested.string



name 

User name of the tool user that requested the license token.string
noFeatures Lists the instances when a license request was rejected because one or more of the features requested were missing from the license. In these cases, users can still use the license token for the features enabled per their license agreement.array of objects

requestKey License request properties for which license have been rejected.array of objects


grantedFeatures Names of features for which a license token was available.array of strings



<feature_name> See feature_name See feature_name 


requestedNoFeatures List of features that were missing from the license.array of strings



<feature_name> See feature_name See feature_name 



toolSee toolSee tool


toolVersionSee toolVersionSee toolVersion

responseStatisticsStatistical information about the rejected license requests.object


noFeaturesCountNumber of times the license request was rejected because the requested features were missing from the license.integer


noFeaturesUserCount Number of users that made license requests that were rejected because the requested features were missing from the license.integer


noFeaturesUsersLists information about the users for whom license requests were rejected.array of objects



noFeaturesCount Number of times the  license request was rejected for the specific user because the requested features were missing from the license.integer



noFeaturesTime List of timestamps marking when the user requested the license.array of strings




<timestamp>See timestamp See timestamp 



user See user See user 




hostNameSee hostName See hostName 




name See name See name 
requestDenied Lists the instances when a license request was rejected because the administrator configured license tokens requests to exclude access for the specific user name, host name, or group (see Filtering License Access).array of objects

requestKey License request properties for which license have been rejected.array of objects


requestedFeatures See requestedFeaturesSee requestedFeatures


toolSee toolSee tool


toolVersion See toolVersionSee toolVersion

responseStatistics Statistical information about the rejected license requests.


requestsDeniedCount Number of times the license request was denied.integer


requestDeniedUserCount Number of users for whom license requests were denied.integer


requestDeniedUsersLists information about the users for whom license requests were denied.array of objects



requestDeniedCount Number of times the license request was denied for the specific user.integer



requestDeniedTime List of timestamps marking when the user requested the license.array of strings




<timestamp>See timestamp See timestamp 



userSee user 




hostName See hostName See hostName 




nameSee name See name 

Example Request

https://myserver:8443/licenseserver/usage/api/v1.0/licenseRejection

Example Response

{
  "noFeatures": [
    {
      "requestKey": {
        "grantedFeatures": [
          "Automation",
          "Change Based Testing",
          "Coding Standards",
          "Coverage"
        ],
        "requestedNoFeatures": [
          "CWE Rules",
          "DTP Publish",
          "Desktop Command Line",
          "Flow Analysis",
          "OWASP Rules",
          "PCI DSS Rules",
          "Security Rules",
          "Unit Test"
        ],
        "tool": "jtest!",
        "toolVersion": "10.4"
      },
      "responseStatistics": {
        "noFeaturesCount": 4,
        "noFeaturesUserCount": 1,
        "noFeaturesUsers": [{
          "noFeaturesCount": 4,
          "noFeaturesTime": [
            "2020-02-12 14:05:08.951",
            "2020-02-12 14:19:08.959",
            "2020-02-12 14:33:08.927",
            "2020-02-12 14:47:08.944"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    },
    {
      "requestKey": {
        "grantedFeatures": [
          "Automation",
          "Change Based Testing",
          "Coding Standards",
          "Coverage"
        ],
        "requestedNoFeatures": [
          "CWE Rules",
          "DTP Publish",
          "Flow Analysis",
          "OWASP Rules",
          "PCI DSS Rules",
          "Security Rules",
          "Unit Test"
        ],
        "tool": "jtest!",
        "toolVersion": "10.4"
      },
      "responseStatistics": {
        "noFeaturesCount": 10,
        "noFeaturesUserCount": 1,
        "noFeaturesUsers": [{
          "noFeaturesCount": 10,
          "noFeaturesTime": [
            "2020-02-12 15:00:12.015",
            "2020-02-12 15:00:15.364",
            "2020-02-12 15:00:33.480",
            "2020-02-12 15:01:08.924",
            "2020-02-12 15:15:08.953",
            "2020-02-12 15:21:09.053",
            "2020-02-12 15:35:09.158",
            "2020-02-12 15:42:09.243",
            "2020-02-12 15:56:09.369",
            "2020-02-12 16:10:09.374"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    },
    {
      "requestKey": {
        "grantedFeatures": [
          "Command Line",
          "Jtest Connect",
          "Message Packs",
          "RuleWizard",
          "SOA",
          "Stub Desktop",
          "Stub Server",
          "Web"
        ],
        "requestedNoFeatures": ["Server API Enabled"],
        "tool": "SOAtest",
        "toolVersion": "9.10"
      },
      "responseStatistics": {
        "noFeaturesCount": 10,
        "noFeaturesUserCount": 1,
        "noFeaturesUsers": [{
          "noFeaturesCount": 10,
          "noFeaturesTime": [
            "2020-02-12 13:39:35.481",
            "2020-02-12 13:39:35.506",
            "2020-02-12 13:40:05.580",
            "2020-02-12 13:40:05.630",
            "2020-02-12 13:40:06.692",
            "2020-02-12 13:40:06.708",
            "2020-02-12 13:40:31.765",
            "2020-02-12 13:40:31.781",
            "2020-02-12 13:40:55.839",
            "2020-02-12 13:40:55.854"
          ],
          "user": {
            "hostName": "caprica",
            "name": "modtest"
          }
        }]
      }
    }
  ],
  "noMoreTokens": [
    {
      "requestKey": {
        "requestedFeatures": [],
        "tool": "jtest!",
        "toolVersion": "10.4"
      },
      "responseStatistics": {
        "noMoreTokensCount": 4,
        "noMoreTokensUserCount": 1,
        "noMoreTokensUsers": [{
          "noMoreTokensCount": 4,
          "noMoreTokensTime": [
            "2020-02-12 21:46:09.516",
            "2020-02-12 22:00:09.534",
            "2020-02-12 22:14:09.573",
            "2020-02-12 22:28:09.578"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    },
    {
      "requestKey": {
        "requestedFeatures": [
          "Automation",
          "CWE Rules",
          "Change Based Testing",
          "Coding Standards",
          "Coverage",
          "DTP Publish",
          "Desktop Command Line",
          "Flow Analysis",
          "OWASP Rules",
          "PCI DSS Rules",
          "Security Rules",
          "Unit Test",
          "Unit Test Bulk Creation",
          "Unit Test Spring Framework"
        ],
        "tool": "jtest!",
        "toolVersion": "10.4"
      },
      "responseStatistics": {
        "noMoreTokensCount": 3,
        "noMoreTokensUserCount": 1,
        "noMoreTokensUsers": [{
          "noMoreTokensCount": 3,
          "noMoreTokensTime": [
            "2020-02-12 12:00:46.576",
            "2020-02-12 12:00:46.840",
            "2020-02-12 12:01:17.713"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    },
    {
      "requestKey": {
        "requestedFeatures": ["Server API Enabled"],
        "tool": "SOAtest",
        "toolVersion": "9.10"
      },
      "responseStatistics": {
        "noMoreTokensCount": 4,
        "noMoreTokensUserCount": 1,
        "noMoreTokensUsers": [{
          "noMoreTokensCount": 4,
          "noMoreTokensTime": [
            "2020-02-12 13:46:30.425",
            "2020-02-12 13:46:30.463",
            "2020-02-12 13:47:06.557",
            "2020-02-12 13:47:06.579"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    }
  ],
  "requestDenied": [
    {
      "requestKey": {
        "requestedFeatures": [],
        "tool": "SOAtest",
        "toolVersion": "9.10"
      },
      "responseStatistics": {
        "requestDeniedCount": 10,
        "requestDeniedUserCount": 2,
        "requestDeniedUsers": [
          {
            "requestDeniedCount": 2,
            "requestDeniedTime": [
              "2020-02-12 13:46:30.447",
              "2020-02-12 13:47:06.567"
            ],
            "user": {
              "hostName": "home",
              "name": "kprzybyla"
            }
          },
          {
            "requestDeniedCount": 8,
            "requestDeniedTime": [
              "2020-02-12 13:21:23.734",
              "2020-02-12 13:21:38.810",
              "2020-02-12 13:22:36.874",
              "2020-02-12 13:32:58.201",
              "2020-02-12 13:33:24.331",
              "2020-02-12 13:34:23.410",
              "2020-02-12 13:34:27.483",
              "2020-02-12 13:34:35.555"
            ],
            "user": {
              "hostName": "caprica",
              "name": "modtest"
            }
          }
        ]
      }
    },
    {
      "requestKey": {
        "requestedFeatures": ["Server API Enabled"],
        "tool": "SOAtest",
        "toolVersion": "9.10"
      },
      "responseStatistics": {
        "requestDeniedCount": 6,
        "requestDeniedUserCount": 1,
        "requestDeniedUsers": [{
          "requestDeniedCount": 6,
          "requestDeniedTime": [
            "2020-02-12 13:37:30.630",
            "2020-02-12 13:37:30.668",
            "2020-02-12 13:38:13.751",
            "2020-02-12 13:38:13.773",
            "2020-02-12 13:38:50.842",
            "2020-02-12 13:38:50.857"
          ],
          "user": {
            "hostName": "caprica",
            "name": "modtest"
          }
        }]
      }
    }
  ]
}

Accessing the API Page

You can call the API from the SwaggerUI shipped withDTP, which provides a point-and-click interface for viewing license usage information. The SwaggerUI is available after logging in. No additional authentication is required.  

  1. Open the License Server home page.
  2. Choose Management> Tools Usage to access the API.

You can right-click on an endpoint to copy the URL and use it in a script. You can also query the endpoint in your browser to quickly view the data. For example: 

  1. Paste the URL into a browser bar and add any additional queries.

    http://<host>/licenseserver/usage/api/v1.0/toolsUsage?startDate=<yyyy-MM-dd>&endDate=<yyyy-MM-dd>
  2. Press the Return key to query the endpoint.



  • No labels