Supervise Squash TM

Java heap size

The Java heap size of Squash TM's JVM, different from the memory allocated to the JVM, can be configured in the startup file via the following property:

startup.sh file:

JAVA_ARGS="-Xms128m -Xmx1024m -server"

startup.bat file:

set JAVA_ARGS=-Xms128m -Xmx1024m %SERVER_MODE%

Xms: initial and minimum Java heap size
Xmx: maximum Java heap size

We recommand that you configure the maximum Java heap size (Xmx) to 2GB for a standard sizing of Squash TM.
In case of high volume of data, you can increase this value to guarantee the app's performance during mass processing (searches, exports, reports).

Focus

Before modifying the Java heap size to the JVM, make sure that the server on which the app is installed has enough RAM.

Manage Logs

You can download Squash TM logs from the administration workspace or from the logs repository on the server. The logs of the day are in the file squash-tm.log whereas the previous logs are suffixed with their date (example: squash-tm.log.20210527)

Logs Level

You can configure the Squash TM's app log rotation in the file conf/log4j2.xml.

In Squash TM, there are three levels of useful logs: "info", "debug", and "trace". The "trace" level is the most precise of the three, but also the most verbose.

To put Squash TM logs in "debug" level, you must:

Stop Squash TM
In the file log4j2.xml, modify the value "info" by "debug" in the line:
```
    <Root level="info">
```
Restart Squash TM

After running your test, come back to the "info" level so as not to overload the server, since the logs are very voluminous in "debug" level.

Squash TM Loggers

The file log4j2.xml already contains a certain number of loggers. You can also individually modify their log level by modifying the value of the property level.

Here is a non-exhaustive list of additional loggers that you can add after the file's last Logger tag:

To get more precise logs for the Jira Server bugtracker:

<Logger name="org.squashtest.tm.plugin.bugtracker.jirarest" level="trace" additivity="false" >
    <AppenderRef ref="Console"/>
    <AppenderRef ref="Daily_log"/>
</Logger>

To increase the Git Connector plugin's logs level:

<Logger name="org.squashtest.tm.plugin.scm.git.internal.GitClientImpl" level="trace" additivity="false" >
     <AppenderRef ref="Console"/>
     <AppenderRef ref="Daily_log"/>
</Logger>

You must restart Squash TM for the app to take the changes made to the file into account.

Xsquash Logs

For Xsquash Cloud, you can download the logs directly from the Jira Cloud administration.

For Xsquash on Jira Server, the plugin logs are merged into the Jira plugins.

You can add a logger in "error" level for the package "org.squashtest.plugin.jira.Xsquash" to activate a more precise view of Xsquash errors in Jira logs.

Here are the steps to follow to add this logger:

In Jira Server, go to Administration > System.
Go to the part "Log in and profile".
In "Default loggers", click on "Configure logging level for another package".
Enter the package "org.squashtest.plugin.jira.Xsquash" and set the logging level to "error".

Monitoring

Servers

As for any other application, the servers hosting Squash TM and its database should be monitored:

disk space: set up an alert when the disk space reaches a certain threshold.
CPU: set up an alert when the CPU usage remains high for a too long period.
RAM: idem.
network (optionally if there is a risk that the network is a bottleneck): idem.

Squash TM

Squash TM is a Spring Boot application, so your monitoring application can use the Actuators web endpoints to query it.

For example:

To use the actuator/health endpoint:
add the following lines in the conf/squash.tm.cfg.properties file:

management.endpoints.enabled-by-default = true
management.endpoints.web.exposure.include = health

the endpoint can then be queried:

>>> curl -s -u "<login>:<password>" https://<host>:<port>/squash/actuator/health | jq
{
"status": "UP"
}

To also use the actuator/metrics endpoint:
modify the second line above in the conf/squash.tm.cfg.properties file:

management.endpoints.web.exposure.include = health,metrics

the endpoint can then be queried:

>>> curl -s -u "<login>:<password>" https://<host>:<port>/squash/actuator/metrics/tomcat.sessions.active.current | jq
{
  "name": "tomcat.sessions.active.current",
  "description": null,
  "baseUnit": "sessions",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 4
    }
  ],
  "availableTags": []
}

(You can use curl -s -u "<login>:<password>" https://<host>:<port>/squash/actuator/metrics to get the list of available metrics.)

Database

Many tools can be used to monitor the PostgreSQL or MariaDB database (PostgreSQL's documentation lists some of them).