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.
| Parameter | Description | Type | Required |
|---|---|---|---|
startDate | Specifies the date of the first record to include in the response. By default, the first date in the log is included. Format: | string | Optional |
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: | string | Optional |
Response Data
The response is an array of tools and information about the tool usage. The following table describes the response data.
| Field | Description | Type | |
|---|---|---|---|
featuresAtMaxConcurrentLicenseTime | The 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 | |
| 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 | |
uniqueHostCount | The 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.
curl https://myserver:8443/licenseserver/usage/api/v1.0/toolsUsage?startDate=2020-03-01&endDate=2020-03-2 --cookie cookies.txt
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 | Description | Type | |
|---|---|---|---|
features | List 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.
| Field | Description | Type | |
|---|---|---|---|
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.
| Field | Description | Type | ||||
|---|---|---|---|---|---|---|
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 | ||||
| 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 | ||||
| Name of feature requested. Contact your Parasoft representative to learn more about available features for your tool. | string | ||||
| Name of the tool for which the license request was rejected. | string | ||||
| Version of the tool. | string | ||||
| 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 | ||||
| Date and time of when the license tokens were requested. Default format: yyyy-MM-dd h:m:s:ms | string | ||||
| Host machine from which the rejected license was requested and user name that requested the license. | object | ||||
| Name of the machine from which the license was requested. | string | ||||
| 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 | ||||
tool | See tool | See tool | ||||
toolVersion | See toolVersion | See toolVersion | ||||
responseStatistics | Statistical information about the rejected license requests. | object | ||||
noFeaturesCount | Number 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 | ||||
noFeaturesUsers | Lists 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 | ||||
hostName | See 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 requestedFeatures | See requestedFeatures | ||||
tool | See tool | See tool | ||||
toolVersion | See toolVersion | See 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 | ||||
requestDeniedUsers | Lists 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 | ||||
user | See user | |||||
hostName | See hostName | See hostName | ||||
name | See 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.
- Open the License Server home page.
- 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:
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>
- Press the Return key to query the endpoint.
