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 (in milliseconds) 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.
• The time it takes Thing Subscriptions to complete execution (minimum, maximum, and mean time).
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. A service that has not finished executing will not be included in the statistics.
|
|
Parameter
|
Default
|
Description
|
||
|---|---|---|---|---|
|
Enable Time Statistics
|
false
|
When enabled, the platform collects statistics. When disabled, the services do not return statistics.
|
||
|
Enable Memory Size Statistics
|
false
|
When enabled, the platform collects memory size statistics. When disabled, the services do note return statistics.
|
||
|
Show Time Statistics
|
true
|
Displays time statistics
|
||
|
Show Memory Size Statistics
|
false
|
Displays memory size statistics
|
||
|
Enable Entity Name Aggregation
|
true
|
If multiple entities are using the same service, aggregated statistics for the services are displayed.
|
||
|
Show Percentiles
|
false
|
Displays additional statistics for percentiles in the configuration table.
|
|
|
Enable Statistics Persistence configuration is not available in utilization subsystem. On an upgraded system, persisted logs up to the point of the upgrade will be available in the database and can be queried. After the upgrade, Statistics Persistence is not available, and the latest statistics will not be retained after a ThingWorx Platform restart. PTC recommends using the write to file services, such as WriteEntityServiceStatisticsReport, WriteEntityStatisticsReport, and so on.
|
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 and/or memory size statistics (minimum, maximum, average, count) 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. Subscriptions may include memory statistics, too.
|
||
|
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.