Monitoring and troubleshooting

The HOOPS Server facilitates several ways to monitor its health and status. It has a built-in HTTP server to facilitate a RESTful API, and it includes extensive logging capabilities.

Quick Start

The examples described in this document will assume the server has been started with the default configuration found within the HOOPS Communicator package’s quick_start directory. The default port for the HOOPS Server is 11182, which will be found in the examples. Please refer to the article on Starting the Server for detailed info about startup. But for basic startup, you can do the following:

Windows

  1. Install the Communicator package.

  2. View the contents of the package using the Windows File Explorer and navigate into the quick_start directory, which is found in the root directory of the package.

  3. Start the server by double-clicking start_server.bat. A console window will appear and display the message “Successfully started HOOPS Communicator Viewer Services” once the server is fully started and ready to process requests.

Linux/macOS

  1. Install the Communicator package.

  2. Using a terminal, change to the quick_start directory, which is found in the root directory of the package.

  3. Using a terminal, change to the start_server.sh script. This can be done by typing ./start_server.sh in the terminal prompt.

Live monitoring and status

Monitoring the status of the server is done by issuing RESTful requests to the server. This can be done programmatically, or by networking tools like cURL. The examples here will utilize cURL <https://curl.haxx.se/>.

General server status

For the general status of the server, you can issue an HTTP GET request to the api/status endpoint. Using cURL with a terminal, issue the following command (for Windows, use curl.exe):

curl -X GET http://localhost:11182/api/status

The result will be a set of status information in JSON format. The returned values will include all server configuration settings, and transformed server configuration values, such as relative to absolute directory paths, memory usage, and spawned server types and counts.

Active Stream Cache Server statuses

Issuing an HTTP GET to the endpoint api/spawns will return a detailed list of all active Stream Cache Server processes that have been spawned by the server:

curl -X GET http://localhost:11182/api/spawns

Garbage collection

The NodeJS garbage collector can be forced to run by issuing an HTTP POST request to the endpoint api/gc. The REST call will result in return JSON data that includes memory statistics. Since we are changing the internal state of the server you will issue a POST request:

curl -X POST http://localhost:11182/api/gc

It’s not typically necessary to explicitly run the garbage-collector, but it is available to allow a level of control and it may be useful for testing. The NodeJS runtime will occasionally run the collector and HOOPS Server can be also configured to run the collector periodically using the autoGcIntervalTime configuration setting.

This capability requires that the NodeJS runtime has been started with the appropriate flag that exposes the garbage collector capabilities, --expose-gc. If the flag has not been set, this call will return a status indicating the problem.

Force a Stream Cache Server launch

You can request the launch of a new Stream Cache Server by issuing an HTTP POST to either the endpoint api/spawn or the endpoint service. The service endpoint is enabled to provide backward compatibility with earlier versions of the TechSoft 3D server but should be considered deprecated.

The returned JSON will indicate if the launch was a success or a failure. If it was a success, it will return the URI that can be given to the HOOPS WebViewer for CAD model viewing. If the launched Stream Cache Server is not connected to a viewer, the server will eventually time out and exit. The amount of time before exiting is controlled by the server’s spawnInitialUseDuration configuration setting.

It may be useful to use this endpoint for load testing or long term memory usage testing.

Logging

The HOOPS Server includes the ability to save important server events to a log file and/or display them to the console. The location and items that get logged can be set through the server’s configuration settings. See the Configuration section for detailed descriptions of all the available settings.

Log levels, cutoffs, and categories

The HOOPS Server logging utilizes typical logging levels that include: Error, Warn, Info, Verbose, Debug.

There are different categories controlled by configuration settings, and each category can be set to log at any of those levels or be entirely disabled. For example, when a spawned Stream Cache Server initiates an HTTP REST call to the server, that is logged at the level set by the logRestHttpRequestsAsLevel configuration, which defaults to LogLevel.Verbose. Setting that value to null would disable logging of those items.

For both the file and console logging, there are independent cutoff settings which determine which items are logged based on their log level. The cutoff scheme is based on the order of the levels as listed above. If you set the cutoff to LogLevel.Info, then all events with log-levels equal to Info, or to the left in the above list will be logged. All events associated with a log-level to the right of Info will not be logged. For example, logging something as LogLevel.Verbose will not be logged if the cutoff is set to LogLevel.Info.

File logging

The default directory that log files are created is controlled by the logDir configuration, which defaults to ~/ts3d_communicator_logs. When the HOOPS Server is first started, it will create a new log file in the logDir directory with the prefix “comm_server”. The rest of the log file name will include the date and time it was created and the process ID of the server.

The configuration setting logFileLevelCutoff determines what events will get logged to the log file based on the cutoff scheme mentioned earlier. If the cutoff is set to null, then nothing will get logged and the log file will not be created.

Console logging

The configuration setting logConsoleLevelCutoff determines what event will be logged to the console based on the cutoff scheme mentioned earlier. The default is set to LogLevel.Warn, which can help quickly uncover any configuration issues after starting the server.

Stream Cache Server logging

Each Stream Cache Server that is launched by the server will also create a unique log file in the directory specified by logDir. The log file has the prefix “comm_scserver” and will include the creation date and time, and the same UUID that is returned by the api/spawns status information for that Stream Cache Server.

The Stream Cache Server currently uses a different logging system than the HOOPS Server and has a slightly different system that determines what gets logged. The logSpawnFileCategoryMask configuration is used by a spawned Stream Cache Server to control the logging. This is a bitmask of values that can include: Error, Warn, Info, Debug, All. These values are combined using the javascript binary OR operator “|” and the result determines which categories go in the log file. For example, to log just errors and warnings, set logSpawnFileCategoryMask to LogSpawnCategory.Warn | LogSpawnCategory.Error.

You can disable Stream Cache Server logging by setting logSpawnFileCategoryMask to either LogSpawnCategory.None or to null.

Disabling logging

To disable HOOPS Server file logging: set either logDir or logFileLevelCutoff to null.

To disable HOOPS Server console logging: set logFileLevelCutoff to null.

To disable Stream Cache Server logging: set either logDir or logSpawnFileCategoryMask to null.