Utilization Subsystem
The services in the utilization subsystem provide execution statistics. The following information can be obtained by using the services in this subsystem:
• The time it takes a service to complete execution (minimum, maximum, and mean time)
• The number of times a service is executed
• The JavaScript services and subscriptions that terminated due to a timeout. See Statistics on Script Execution Terminated Due to Timeout below.
Statistics are recorded (in milliseconds) from the time that the server was last restarted but can be persisted by enabling the Enable Statistics Persistence option. By using the WriteStatisticsReport service, a CSV file that contains these statistics can be written to the ThingworxStorage folder.
 |
Statistics are only provided for completed services. If a service has not finished executing, it will not be included in the statistics.
|
|
Parameter
|
Default
|
Description
|
||
|---|---|---|---|---|
|
Enable Statistics
|
false
|
When enabled, the platform collects statistics. When disabled, the services do not return statistics.
|
||
|
Enable Entity Name Aggregation
|
true
|
If multiple entities are using the same service, aggregated statistics for the services are displayed.
|
||
|
Enable Statistics Persistence
|
false
|
When enabled and the server is restarted, all run-time statistics are retained. Data is retained after the platform restarts.
|
||
|
Show Percentiles
|
false
|
Displays additional statistics for percentiles in the configuration table.
|
UtilizationStatistics Services
|
Service
|
Description
|
||
|---|---|---|---|
|
GetAuthenticationStatistics
|
Returns data on how many authentications occurred for any given authentication type and if they were successful or if they failed. Authentication types include Form login, HTTP Basic, application key, SSO, and custom authenticators.
|
||
|
GetEntityServiceStatistics
|
Returns the min, max, mean, counts of service executions for each entity.
|
||
|
GetEntityStatistics
|
Returns a combo of the statistics in the GetEntityServiceStatistics and GetEntitySubscriptionStatistics services.
|
||
|
GetEntitySubscriptionStatistics
|
Returns the time statistics (minimum, maximum, average, total time) for executing subscriptions on events for entities.
|
||
|
GetPropertyVTQCount
|
Returns the count of properties specified by the query criteria. See Using the GetPropertyVTQCount Service for more information.
|
||
|
GetQueryStatistics
|
Returns the query statistics. See Query Statistics for more information.
|
||
|
GetStatistics
|
Returns all the statistics in the GetEntityServiceStatistics, GetEntitySubscriptionStatistics, and GetAuthenticationStatistics services. Includes minimum time, maximum time, mean time, and count for each executed service.
|
||
|
ResetAuthenticationStatistics
|
Resets the authentication statistics.
|
||
|
ResetEntityServiceStatistics
|
Resets entity service statistics.
|
||
|
ResetEntityStatistics
|
Resets entity statistics.
|
||
|
ResetQueryStatistics
|
Resets query statistics. See Query Statistics for more information.
|
||
|
ResetStatistics
|
Resets all statistics.
|
||
|
ResetEntitySubscriptionStatistics
|
Resets the subscription statistics for an entity.
|
||
|
WriteAuthenticationStatisticsReport
|
Writes a uniquely-named CSV file to the following location: ThingworxStorage/reports/UtilizationStatistics
|
||
|
WriteEntityServiceStatisticsReport
|
Writes a uniquely-named CSV file to the following location: ThingworxStorage/reports/UtilizationStatistics
|
||
|
WriteEntityStatisticsReport
|
Writes a uniquely-named CSV file to the following location: ThingworxStorage/reports/UtilizationStatistics
|
||
|
WriteEntitySubscriptionStatisticsReport
|
Writes a uniquely-named CSV file to the following location: ThingworxStorage/reports/UtilizationStatistics
|
||
|
WriteQueryStatisticsReport
|
Writes the query statistics. See Query Statistics for more information.
|
||
|
WriteStatisticsReport
|
Writes a uniquely-named CSV file to the following location: ThingworxStorage/reports/UtilizationStatistics
|
Naming Pattern for Statistics
The naming pattern is as follows:
• All statistics are collected under the prefix of twx.stats.
• Authentication statistics are collected under twx.stats.authentication.
• Entity statistics are collected under twx.stats.entity.
• Entity service statistics are collected under twx.stats.entity.<entityname>.services.<servicename>.
• Entity subscription statistics are collected under the following names: twx.stats.entity.<entityname>.subscriptions.<subscription-name>.
• Query statistics are collected under twx.stats.query.
The "naming" parameter data types for the services include the following:
• Prefixes - add to the start of the service you want to get returned stats for. For example, to view authentication statistics only, provide the twx.stats.authentication prefix to the GetStatistics service or use the GetAuthententicationStatistics convenience service without parameters.
• Regular expressions- Can be used for entity names and services. You can choose to see all entities that follow a regex pattern if the aggregation option is turned off. You can also use a regex to display certain services that start with the word Get. The regex pattern used follows the Java Regex pattern which is documented at https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html.
Statistics on Script Execution Terminated Due to Timeout
The ThingWorx Platform terminates long running scripts and reports the action to the platform log. The ThingWorx Platform also collects statistics on any script termination caused by a timeout. The statistics are recorded when the execution time exceeds the configured script timeout value. The platform collects the statistics for services and subscriptions written in JavaScript.
|
|
By default the script timeout setting on the ThingWorx platform is 30 seconds. If a script runs longer than this, the platform terminates the execution. A ThingWorx administrator can configure the script timeout in the Basic Settings section of the platform-settings.json configuration file. See also platform-settings.json Configuration Details.
|
The statistics are included in the results from the following services on the utilization subsystem:
• GetStatistics
• GetEntityStatistics
• GetEntityServiceStatistics
• GetEntitySubscriptionStatistics
• WriteStatisticsReport
• WriteEntityStatisticsReport
• WriteEntityServiceStatisticsReport
• WriteEntitySubscriptionStatisticsReport
The timeout statistics are available for services using the following naming pattern:
twx.stats.entity.<entity-name>.services.<service-name>.timedout
Similarly, timeout statistics for subscriptions are available, using the following naming pattern:
twx.stats.entity.<entity-name>.subscriptions.<subscription-name>.timedout
These timedout statistics keep track of occurrences and time duration statistics when the specified scripts time out.