File Transfer Subsystem Metrics

ThingWorx Model Definition in Composer > System > Subsystems > File Transfer Subsystem > File Transfer Subsystem Metrics

The File Transfer monitoring metrics are updated as described below. The following metrics are in the File Transfer subsystem under the /Metrics endpoint and are available after starting the file transfer.

The older metrics did not have labels, which in turn needed multiple metrics to know the status and details. The new metrics have label configurations that the users can configure as required and get all the operation details using one metric. Each metric has configurable labels, that categorize operations based on their properties. For example: target repository, source repository, and state. The following labels are available for all the endpoints.

• LABEL_KEY: Defines the category. For example, target, source, state.

• LABEL_DESCRIPTION: Describes the purpose of the label .

• LABEL_VALUE_TYPE: Defines the type of allowed value. For example, string.

• LABEL_VALUES: Specifies the valid values for the label.

• CATCH-ALL : Provide the fallback values for unrecognized inputs.

Old Metrics	New Metrics	Description
• uploadFailedTransfers • uploadStartedTransfers • uploadCompletedTransfers • uploadCancelledTransfers	thingworx_file_transfer_upload_total	This metric captures the file upload operations. At the definition time the included filters will be Target and State.
• downloadCompletedTransfers • downloadCancelledTransfers • downloadFailedTransfers • downloadStartedTransfers	thingworx_file_transfer_download_total	This metric captures the file Download operations. At the definition time the included filters will be Source and State.
• acrossRepoStartedTransfers • acrossRepoCancelledTransfers • acrossRepoFailedTransfers • acrossRepoCompletedTransfers	thingworx_file_transfer_acrossrepo_total	This metric captures the file transfer across repositories. At the definition time the included filters will be Source, Target, and State.

To configure the labels, use the service ConfigureMetricsAttributeFiltering in the Platform Subsystem.

For example. while uploading, metricName should be thingworx_file_transfer_upload and metricAttributesValueBasedFilterConfig. The JSON can be as follows:

{
"labelConfig": [
{
"LABEL_NAME": "target",
"ALLOWED_VALUES": [
"SystemRepository",
"SupportRepository"
],
"DEFAULT_VALUE": "otherrepository"
}
]
}

Here, if the files are transferred from repositories, other than the repositories in the ALLOWED_VALUES, the target will have otherrepository as its value. The same behavior can be observed for Download and Copy operation with its labels. Multiple label configurations can be added inside labelConfig, separated by comma(,).

Disabling Old Metrics

For new installation of ThingWorx Platform 9.7.x, only the new metrics are available. For users upgrading the ThingWorx Platform 9.6.x to ThingWorx Platform 9.7.x, the older metrics will be available. PTC highly recommends the upgraded users to use the new metrics.

For new installation

While using installer, old File Transfer metrics are not available at /Metrics and /GetPerformanceMetrics endpoint. Only new file transfer metrics are available.

For upgrade

While using installer, old and new File Transfer metrics are available.

At the time of upgrade, you can disable the old metrics by changing the disable metrics list. Use the DisabledMetricsList in platform-settings.json file to disable metrics. For more information, see Option to Disable Metrics and platform-settings.json Configuration Details.

Migration

After migration, old File Transfer metrics are not available. Only new file transfer metrics are available.

Histogram metrics

The following Histogram metrics can be used to know the file transfer size and file transfer duration.

These metrics are available in the File Transfer subsystem under the /Metrics endpoint only after the completion of the file transfer operation.

Metric	Description
thingworx_file_transfer_size_bytes	This metric will show the total size for the file being transferred. This metric has the operation label. The values can be UPLOAD, DOWNLOAD, and ACROSSREPO depending on the type of operation performed. This metric has the default set of buckets - <1KB, 10KB, 100KB, 1M, 10M, 100M, 1G, >1G
thingworx_file_transfer_duration_ms	This metric will show the duration of the file being transferred. This metric has the operation label. The values can be UPLOAD, DOWNLOAD, and ACROSSREPO depending on the type of operation performed. This metric has the default set of buckets - 100ms, 1s, 10s, 100s, 1000s, >1000s

Histogram buckets are incremental in the following way:

• For the File Transfer Time Histogram - If the transfer takes more than 100ms, and less than or equal to 1s, it will fall into 1s bucket and other corresponding buckets.

• For the File Transfer Size Histogram - If the transfer has a file size of more than 1KB, and less than or equal to 10KB, then it will fall into 10KB bucket and other corresponding buckets.

To change the default bucket sizes, for example .to customise thingworx_file_transfer_duration_ms to [200 ,2000, 20000, 200000] and thingworx_file_transfer_size_bytesto [2048, 20480, 204800, 2097152, 20971520], update the following

For On-premise

Update the platform-settings.json file as follows.

"PlatformSettingsConfig"
{
"MetricsSettings":
{
"HistogramMetricsBucketSizeList":
{
"thingworx_file_transfer_duration_ms":[200 ,2000, 20000, 200000],
"thingworx_file_transfer_size_bytes ":[2048, 20480, 204800, 2097152, 20971520]
}
}
}

For Docker

Update the following files.

◦ In .env file add the following, if not available.

HISTOGRAM_BUCKET_SIZE_LIST: '
{
"thingworx_file_transfer_duration_ms":[200,2000,20000,200000],
"thingworx_file_transfer_size_bytes ":[2048,20480, 204800,2097152,20971520]
}'

◦ In the docker-compose file add the following, if not available.

HISTOGRAM_BUCKET_SIZE_LIST: ${HISTOGRAM_BUCKET_SIZE_LIST}