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 compete 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.
* 
Enabling aggregation saves on memory. If it is turned off, performance may be affected. If memory grows to an unacceptable level, execute the ResetStatistics service.
Show Percentiles
false
Displays additional statistics for percentiles in the configuration table.
Enable Statistics Persistence
false
When enabled, and the server is restarted, all run time statistics are retained. Data is retained after restarts of the platform.
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.
* 
If aggregation is enabled, it will return one service for all entities.
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 twx.stats.entity.<entityname>.subscriptions.<source of the subscription event>.<subscription type>.<property 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.
Was this helpful?