Support Tool
The Support Tool extension is used for diagnostic operations in ThingWorx, such as collecting thread dumps, monitoring performance, and dumping heap.
Location
This tool is available on support.ptc.com under Download Software > Order or Download Software Updates > ThingWorx Foundation > Release 8.5 > ThingWorx Support Tool > Most Recent Datecode > ThingWorx-Support-Tools--<version>.
Using the Extension
After importing the extension into ThingWorx, the following entities are created:
• SupportTools.Template— Thing Template that contains diagnostic services.
• SupportTools.Entity — Thing instance of the Support Tool that provides access to diagnostic services.
• SupportTools.Repository — File Repository where the Support Tool monitors and generates files.
The extension provides services to allow the following diagnostic operations:
• Writes the Java Virtual Machine's heap state to disk (Heap Dump)
• Writes the Java Virtual Machine's thread state to disk (Thread Dump or Stacktrace)
• Creates a watchdog process on the ThingWorx server that can be used to trigger either of the above events in situations where the ThingWorx Composer is not responding.
◦ To trigger a thread dump / stacktrace using the watchdog:
▪ Create an empty file named runstacktrace in the /ThingworxStorage/repository/SupportTools.Repository directory
▪ Thread dumps will continue to be written to disk every 30 seconds (by default) until this file is deleted again.
◦ To trigger a heap dump using the watchdog:
▪ Create an empty text file named dumpheap in the /ThingworxStorage/repository/SupportTools.Repository directory, no extension.
▪ Heap dump will occur once on the next watchdog check. The heap dump watchdog is then disabled until the next server restart.
◦ To stop a thread dump / stacktrace using the watchdog:
▪ Delete the file named runstacktrace in the /ThingworxStorage/repository/SupportTools.Repository directory.
▪ Use the StopDiagnosticWatchdog service.
Heap Dump Services
Generally, a heap dump is helpful in the following situations:
• Memory issues where a leak is suspected
• Hung server
Dumping the Java Heap to disk is an expensive operation, and will put the ThingWorx server into an unresponsive state while a full garbage collection is done and while the heap is flushed to disk. This process can take a long time to complete for a large JVM Heap (10-30 minutes).
The following heap dump services are available:
• SetHeapDumpFlag— To prevent the heap from being dumped accidentally, the Support Tool extension requires that the SetHeapDumpFlag service is executed before the DumpHeap service, to verify that the user wants to dump heap to disk. This service sets an internal flag that enables the DumpHeap service. This flag does not persist across server restarts, so if the ThingWorx server is restarted, the SetHeapDumpFlag service must be executed again. The internal flag enabling the DumpHeap service can be disabled by running the ClearHeapDumpFlag service.
• ClearHeapDumpFlag— Clears the internal flag that enables the use of the DumpHeap service, disabling the service until the SetHeapDumpFlag service is run again.
• DumpHeap— To prevent accidental heap dumps that can lock up the server for a few minutes while they run, this service can only be executed after the SetHeapDumpFlag service has been executed. This service instructs the JVM to do the following:
◦ Dump the current Thread state to disk (written to /ThingworxStorage/repository/SupportTools.Repository/stacktrace, appending if present)
◦ Dump the current JVM Heap state to disk (written to <TomcatDirectory>/logs/heapdump.hprof, overwriting an existing file if present)
 |
The heap dump is not written out to the Repository by design. It must be compressed outside ThingWorx folders.
|
Thread Dump Services (Stacktraces)
• DumpAllThreads— Writes the JVM's current thread state to disk. By default, stacktraces are written to /ThingworxStorage/repository/SupportTools.Repository/stacktrace . If the file already exists, the new thread dump will be appended to the end of the file. A stacktrace / thread dump consists of:
◦ Timestamp when the thread was collected.
◦ Identifiers, thread states, and thread call stacks for each live thread in the JVM.
Watchdog Operations
The Diagnostic Watchdog is a small process that runs in the background of the ThingWorx server, watching the file system for trigger files. There is no need to stop, start, or adjust this process, unless advised to do so by PTC Technical Support.
This process is automatically started when ThingWorx is restarted and provides the following benefits:
• The ability to generate thread dumps/stacktraces automatically on a regular interval.
• The ability to trigger a thread dump or heap dump when Composer is unresponsive or unreachable.
The following watchdog services are available:
• GetWatchdogInterval— Returns the current interval between watchdog checks, or -1 if the watchdog is not running.
• SetWatchdogInterval— Changes the watchdog interval to a new value in seconds. The default interval is 30 seconds. The new interval will take effect after the next watchdog check.
• StartDiagnosticWatchdog— Starts the Diagnostic Watchdog thread when stopped.
• StopDiagnosticWatchdog— Stops the Diagnostic Watchdog thread when started.