Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space DTPDEVEL and version 2020.1

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:

Table of Contents
maxLevel1

Authentication

Basic authentication is not supported. You must first send a request to the server, capture the cookie created during authentication, and include the cookie in your GET method call to the endpoint.

Example

In the following example, a POST request is sent to the login page and the cookie is captured. Credentials are included in the payload using the j_username and j_password parameters:

No Format
curl -v --data 'j_username=<your_username>&j_password=<your_password>' https://<host>:<port>/grs/pst_login_request --cookie-jar cookies.txt
The cookie is passed in a GET request to the License Usage API endpoint, e.g.:

No Format
curl https://<host>:8443/licenseserver/usage/api/v1.0/toolsUsage --cookie cookies.txt

Endpoints

The following endpoints are available:

Table of Content Zone
maxLevel2
minLevel2
locationtop

/toolsUsage

This endpoint returns summary information about tool usage. 

URL

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

Parameters 
Anchor
common-license-usage-api-params
common-license-usage-api-params

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

Example Request

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

No Format
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.

Code Block
languagejs
[
    {
        "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

No Format
<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.

No Format
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.

Code Block
languagejs
[
    {
        "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

No Format
<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.integer
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.

No Format
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. 

Code Block
languagejs
[
    {
        "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

No Format
<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


Anchor
lic-reject-resp-reqFeat-field
lic-reject-resp-reqFeat-field
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>

Anchor
lic-reject-featname-field
lic-reject-featname-field

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


Anchor
lic-reject-resp-field-tool
lic-reject-resp-field-tool
tool 

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


Anchor
lic-reject-resp-toolver-field
lic-reject-resp-toolver-field
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> 

Anchor
lic-reject-timestamp-string
lic-reject-timestamp-string

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

string


user

Anchor
lic-reject-resp-user-field
lic-reject-resp-user-field

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



hostName 

Anchor
lic-reject-resp-hostname-field
lic-reject-resp-hostname-field

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



name 

Anchor
lic-reject-resp-name-field
lic-reject-resp-name-field

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

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

Example Response

Code Block
languagejs
{
  "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.

    No Format
    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.