18. System Maintenance

Topics

This chapter covers topics related to maintenance of the Polarion system over time.

Low Resource Notifications

Polarion monitors Java system memory and disk storage resources and automatically notifies the Polarion administrator by email when on or both of these are approaching failure levels. The actual algorithm is fairly complex. The main points you need to know as an administrator are:

  • A warning message is sent if the available free disk space is running low. By default, notifications are sent when free disk space:

    • is less than 5%

    • is less than 1 GB

    • less than 100 MB

    The free disk space limit is configurable. See Configuring Free Space Limit, below.

  • If Java is not able to recover enough heap memory during garbage collection, condition may indicate that Polarion is running out of memory, and the administrator may want to increase the -Xmx setting in polarion.ini (Windows) or etc/config.sh (Linux) and restart the server.

    Therefore, a warning message is sent when Java heap space is less than 5%.

    If Polarion is installed as a service

    If Polarion installed as a service, as it is in the default Windows installation, you will also need to uninstall then reinstall the service.

    Uninstall and reinstall the Polarion service:

    1. Launch a command prompt window as an administrator.

    2. Type cd Polarion\polarion and hit Enter

    3. Type net stop polarion and hit Enter

    4. Type service -uninstall and hit Enter

    5. Type service -install and hit Enter

    6. Type net start polarion and hit Enter

The Sending of these administrator notifications can be disabled by setting com.polarion.platform.monitoring.notifications.disabled=true in the system properties file polarion.properties (Follow the link if you need the location).

The email address(s) for the recipient(s) of these notifications can be set by specifying a comma-delimited list of email addresses in the system property: com.polarion.platform.monitoring.notifications.receivers

The sender can be set in the property com.polarion.platform.monitoring.notifications.sender, the email subject prefix can be set in com.polarion.platform.monitoring.notifications.subject.prefix.

Configuring Free Space Limit

The system property com.polarion.platform.monitoring.notifications.freeSpacePercent controls when notifications about low free disk space will be sent. Default value is 5 (i.e. 5%), meaning that when the free disk space on the disk where polarion data is stored is lower than 5% of the disk's capacity, notifications will be sent to the Polarion administrator.

It is not enough to simply set this property - monitoring of system resources must be configured as well. The following properties should be set:

com.polarion.platform.monitoring.notifications.disabled=false
com.polarion.platform.monitoring.notifications.receivers=<valid@email>
                

Prevent Long Running Transactions from Clogging up the Server.

Some processes, poorly optimized custom reports in particular, can run for hours and clog up valuable server resources.

The problem is compounded when users get impatient and refresh the view in the hopes that it will speed up the process.

At best, these multiple parallel runs slow down the server.

At worst they can completely deplete the server's resources and result in an out of memory error that requires a reindex.

To prevent clogging up the server, a functionality was implemented in 18.2 that interrupts the processing of UI requests that take longer than a specified amount of time.

Only "read-only" user requests are affected. Requests with write operations are not.

These new properties (below) prevent the scenario described above by "killing" any user UI requests a few seconds before the connection timeout (defined by the Apache configuration) expires and display the following error:

Your request [id: REQ_<NUMBER>] took too long to process and was stopped to avoid clogging the server.

Possible reasons it took so long: High server load, too much processed data or non-optimal scripts.

The interrupted request will also be logged in the log files. The following exception indicates such a request interruption:

com.polarion.core.util.exceptions.OperationTimeoutException

The information in the exception and stack trace might indicate why the request is taking so long to process. Use the request identifier REQ_<NUMBER> to match the request and log record.

The following two properties were introduced and are enabled by default to prevent long running transactions:

Properties:

com.siemens.polarion.platform.threadKillingMode=killAll

Possible values:

  • killAll: All long, read-only UI requests will be killed. (The default value.)

  • reportOnly: Only requests related to Rich Text or Wiki Pages (read-only) will be killed.

  • disabled: Only logs the long running transactions and doesn't interrupt them.

com.siemens.polarion.platform.threadKillingTimeout=590000

Sets the time period (in milliseconds) after which a request can potentially be killed.

The default value is 590000 (9 minutes, 50 seconds: 10 seconds before the default Apache timeout).

If the value is 0 or less than 0, the default value will be used.

Notes:

  • Set this property with a time period less than the Apache ProxyPass timeout value configured in the polarion.conf or polarion-cluster.conf files.

  • UI requests that make any write operation are marked as non-interruptible and will continue to be processed in the background until they are complete.

  • Custom extensions invoked by UI requests that operate outside the Polarion API, may also be considered interruptible.

    (If you think that they might exceed the set timeout period and be affected by a termination of the request, then disable this feature or call the preventThreadKilling() method from the ITransactionService class within the custom extension.)

Activities Index Cleanup

Administrators can schedule an automated cleanup of the activity stream storage area.

The default setting runs the Activities Index Cleanup on a weekly basis.

(Every Sunday at Midnight.)

Benefits:

  • The bigger the index, the slower it is to read and write to it.

  • In a clustered environment, the index is located in a shared storage environment. If never cleaned, it will grow indefinitely.

  • In a single-instance environment, the activities index is cleaned with every reindex.

Configure Activity Cleaner:

By default Activity Cleaner job keeps a maximum of 5000 activities that are not older than 90 days for each source.

These limits can be configured granularly per source and type by editing the following lines in the polarion.properties file.

In (C:\Polarion\polarion\configuration\) by default.

maxActivitiesLimit=5000
                

maxActivitiesLimit = The number of activities that are kept by Activity Cleaner.

(Can be set individually for particular sources and types, or globally for all sources.)

If no property is specified, the limit is controlled per source by default.

A search for the value is done in following order:

  1. 'Source.type' System Property:

    com.polarion.activity.(sourceID).(type).maxActivitiesLimit

  2. 'Source' System Property:

    com.polarion.activity.(sourceID).maxActivitiesLimit

  3. The System Property for all Sources and Types:

    com.polarion.activity.maxActivitiesLimit

  4. The default Source/Type limit:

    Returned by; IActivitySource.getHistoryLimitCount(type)

maxActivitiesAge=90
        

maxActivitiesAge = How long, in days, that activities are preserved by the Activity Cleaner.

(Can also be set individually for particular sources and types, or globally for all sources.)

If no property is specified, the duration is controlled per source by default.

A search for the value is done in following order:

  1. 'Source.type' System Property:

    com.polarion.activity.(sourceID).(type).maxActivitiesAge

  2. 'Source' System Property:

    com.polarion.activity.(sourceID).maxActivitiesAge

  3. The System Property for all Sources and Types:

    com.polarion.activity.maxActivitiesAge

  4. The default Source/Type limit:

    Returned by; IActivitySource.getHistoryLimitDays(type)

See 'Configuring the Scheduler' below for more information on scheduling maintenance jobs.

Configuring the Scheduler

Polarion comes with a default set of scheduled jobs. Scheduler allows you to configure scheduled jobs such as builds, dashboard updates, system cleanup, etc. You can alter the properties of scheduled jobs, such as the day of the week when the job should run. You can also add additional scheduled jobs to the default set, or remove jobs from the default jobs set. You can optionally invoke any job explicitly in the Monitor topic.

Defining and Modifying Jobs

This configuration is available only for the global (repository) scope. If you are not familiar with the basics of the different scopes, you may want to review Administration Basics: The Administration Interface. The configuration is specified in the Scheduler topic of Administration.

Reference information including cron expressions and examples for configuring jobs is embedded on the Scheduler configuration page (scroll down if necessary to see it). The same information is available in the Administration Reference: Scheduler.

Accessing the configuration

To access the Scheduler configuration:

  1. Log in with administration rights for the repository.

  2. Enter the Administration interface (click the Administration) link in the tool view of Navigation).

  3. Select Repository in the Open Project or Project Group dialog.

    (See User Guide: Accessing Projects.)

  4. In the Navigation pane, select the Scheduler topic.

    The Scheduled Jobs Configuration page loads in your browser. This page has an embedded XML editor which displays the XML code of the current configuration.

  5. Edit the XML code as needed to make the changes or additions you want. Refer to the embedded help text that appears below the embedded XML editor.

  6. Click the Save button to save the changes to the Scheduler configuration. Changes are immediately in effect - it is not necessary to restart the server.

Spawning Multiple Jobs

Jobs can spawn other jobs. The ID for such a job is multi.job. Jobs to spawn are referenced by their names from schedule.xml. It is possible to run jobs either sequentially (default) or in parallel, and possible to terminate sequential execution if a job fails. Default is to ignore the failure. The job reports failure if at least one of the executed jobs fails.

The following listing shows the multi.job scheduler configuration:

<job id="multi.job" ...>
    <parallel>_true_OR_false_</parallel>
    <terminateOnFailure>_true_OR_false_</terminateOnFailure>
    <delegateFailure>_true_OR_false_</delegateFailure>
    
    <jobs>
        <job>_JOB_NAME_</job>
        . . .
    </jobs>
<job>    
	            

It is possible to fail the job if at least one of the executed jobs fails. Default is to finish successfully no matter what. Aborting will always fail the multi.job.

Extended Configurability
  • _JOB_NAME_ may contain execution expression. Execution expression consists of:

    • Job name

    • Sequential operator ,

    • Parallelization operator |

  • Operator precedence is (from highest to lowest): | ,

  • Sequential operator will execute job groups in sequence. Failures coming from these jobs are ignored and not delegated.

  • Parallelization operator will execute job groups in parallel. Failures coming from these jobs are ignored and not delegated.

Example: J1,J2|J3|J4,J5 will execute three groups of jobs in parallel, first group consists of sequence J1,J2, the second group is a single job J3, and the last group is a sequence of J4 and J5.

Jobs in a Clustered Setup

Scheduled jobs should be reviewed for a cluster, and convenient Node selectors (i.e. the node attribute of <job> elements) should be specified depending on the nature of the job. The following default jobs should have node="*" specified for them in a clustered setup:

  • Index Checker

  • Suspend DB History Creator

  • Resume DB History Creator

Running Scripts Via Jobs

You can define a job that runs a custom script. The job ID in the scheduler must be script.job. Groovy (groovy) and JavaScript/ECMAScript (js) scripts are supported. Script files must be stored in the scripts folder of the installation's file system.

The job has the following required parameters:

  • scriptName: Name of the script to run

  • scriptEngine: Name of the scripting engine to use (groovy or js)

In the script you will be able to access following variables:

  • logger: A com.polarion.platform.jobs.ILogger you can use to log messages for the job

  • scope: A com.polarion.platform.context.IContext that repesents the scope of the job.

  • workDir: A java.io.File pointing to the working directory of the job.

  • jobUnit: The com.polarion.platform.jobs.IJobUnit that runs the script.

Every property is defined inside the <properties> element of the job. The property in the example below would be accessible as variable with the name "myProperty" containing the value "myPropertyValue".

<job name="Script Job" id="script.job" cronExpression="" disabled="true" scope="system">
    <scriptName>test.js</scriptName>
    <scriptEngine>js</scriptEngine>
    <properties>
        <myProperty>myPropertyValue</myProperty>
    </properties>
</job>
	            

Running Scripts Directly

The internal script engine that executes scripts via jobs, and also script-based workflow conditions and functions for Work Items and Documents (ScriptCondition, ScriptFunction) can run a script without installing it into the scripts folder. To run a script directly, direct your web browser to: [POLARION SERVER]/polarion/scripting (where [POLARION SERVER] is replaced with the actual domain of your server).

The page provides an interface that you can use to input and run a script. The variables visible to the script are the same as for script jobs. (Actually, the script is run as a job). The system property com.polarion.scripting.servlet.enabled must be enabled in the system configuration file polarion.properties in order to run scripts directly. By default, only administrators are allowed to run scripts this way, as it is potentially dangerous.

Starting and Stopping the Scheduler

As mentioned, Jobs are defined (scheduled) and run in the global scope. You can start or stop the Scheduler from the Scheduler topic in Administration.

To invoke one of these operations:

  1. Log in to Polarion with administrator permissions for the repository.

  2. Enter the Administration interface.

  3. Select Repository in the Open Project or Project Group dialog to work in the global scope.

    (See User Guide: Accessing Projects.)

    A button appears at the top of the Scheduler page, just under the main heading. If the Scheduler is currently running the button label is Stop Scheduler. If the Scheduler is currently stopped, the button label is Start Scheduler.

  4. Click the button for the operation you want to invoke. When the Scheduler is stopped, configured scheduled jobs will not run. When the Scheduler is started (i.e. running), the configured jobs will be run according to the configured schedule.

Scheduling Jobs to Run Immediately

You can run any scheduled job immediately from the Monitor topic. The Scheduler must be running. (See Starting and Stopping the Scheduler.) Check the job(s) you want to run in the Scheduled Jobs section and click the Execute Now button to launch the job(s) you selected.

Note

Running jobs uses server system resources, and some types of jobs can be very resource intensive. Administrators generally schedule jobs to run at times when user demand is low. Be aware that explicit running of jobs has the potential to degrade performance for end users and use discretion accordingly.

Executing System Commands/Utilities

You can use the execute.command job to immediately run some system command or utility. For example, the following will run the PDT diagnostic utility.

<job id="execute.command" name="PDT" scope="system">
    <command>$[com.polarion.home]/diagtool/run$[shellExtension]</command>
    <arguments>
        <argument>-sendResults</argument>
        <argument>no</argument>
        <argument>-resultsDir</argument>
        <argument>$[jobDir]</argument>
    </arguments>
</job>
                    

Disable execute.command Job Execution

Administrators can add com.siemens.polarion.security.executeCommandJob.enabled=false to the polarion.properties file to disable all execute.command jobs for increased security.

When set to False, users will not be able to execute execute.command jobs and will be prompted with a security warning if they attempt to do so.

Note

The Polarion Diagnostic Tool is also an execute.command job and will also be disabled.

Viewing Jobs in the Monitor

You can see the status of all Jobs in the Monitor topic. This topic is available in the Navigation pane when you exit from Administration and return to project or portal content topics.

To access the Monitor:

  1. In the Open Project or Project Group dialog, select either Repository or a Project (you must have the relevant permissions).

  2. If you are in Administration, click the link in the top panel of Navigation to return to the portal Home or the project.

  3. In the Navigation pane, select Monitor.

Cleaning Up Temporary Folders

Jobs create temporary folders, which in turn store job logs. At some point, you will want to clean up these folders. There is a job jobs.cleanup that deletes these temporary folders and their data. The job can be scheduled to run periodically, or launched explicitly. You can optionally use the preserveAgeHours to specify how long to preserve temporary file after jobs start. The value of the parameter is hours (see the following example). If the parameter is not specified, the job defaults to 24 hours.

Example:

<job cronExpression="0 55 * ? * *" id="jobs.cleanup" name="Cleanup of Temporary Files" scope="system">
   <preserveAgeHours>36</preserveAgeHours>
</job>	                
	            

In this example, temporary folders and data are preserved for 36 hours.

Backing up Polarion Data

This section discusses the system location of data that administrators should be sure to include in regular backup operations.

References to installation locations.

For the purposes of discussing the location of various folders that administrators may wish to include in backups, this section will define some variables and their meaning on different operating systems This is because the installation structure differs somewhat on Windows vs. Linux.

Variables and equivalent paths

This section documents the system variables and their locations of different operating systems.

Variable: POLARION_HOME

  • Description: Location of Polarion binaries

  • Windows: C:\Polarion

  • Linux: /opt/polarion

Note

The above paths are the defaults. You can configure the root location during installation.

Variable: POLARION_DATA

  • Description: Root for Polarion data files

  • Windows: %POLARION_HOME%\data

  • Linux: /var/lib/polarion

Note

The above paths are the defaults. You can configure the data files location during installation.

Subversion Repository

An essential component to back up is the Subversion repository, located in %POLARION_DATA%/svn. The default storage method is file-based and so does not modify existing files, only adds new ones. This is very convenient for incremental back-up methods.

Project Builds

Project builds are located in %POLARION_DATA%/bir/projects .

The contents can be very large. Developers and project managers should know what is most critical to back up. It is usually not necessary to back up all the nightly builds for example. It also makes sense not to back up the demo project builds (installed by default by the Windows installer program).

Reports

Reports are generally not critical to back up because they can be recreated any time, with one exception: the trends.

To back up the trends you need to collect all *trend*.xml files (e.g. workitems-trend-data.xml) in the structure beneath the folder %POLARION_DATA%/RR. Backing up the entire folder will most likely be a significant waste of backup space (up to 99%).

If you use SCRUM calculation, you should back up scrum-data.xml because it holds the historic values for all past sprints.

User-modified Data

The following data may or may not need to be backed up depending on whether it was modified after Polarion was installed.

Polarion Configuration File

It may make sense to back up the root Polarion configuration file polarion.properties (follow link for location). This file can be recreated by reinstalling Polarion and filling in all the original arguments. However, if the file was modified after the installation to customize the system configuration, it is a good idea to back it up.

Modified installation structure

If the original folder structure of the installation was modified - to add more Maven plugins or Apache modules, or if some graphics or templates were modified - it is a good idea to back up such modifications in case it is ever necessary to reinstall Polarion (on new hardware, for example).

Connectors Data

If any Connectors are configured for any projects (in Administration > Connectors), include the folder %POLARION_DATA%/synchronizer in your backups. The folder contains a database that stores the relation between Work Items and the items in the connected third-party systems, and also baseline data that is used to detect which fields were changed. Losing that data would mean losing the relation between Work Items and the items in the other systems, and when the items are synchronized they will be recreated instead of updated, thereby corrupting the data integrity of both systems.

Backup Tips for Polarion Server

From best to worst scenario:

  1. Do a snapshot of suspended virtual machine in which Polarion server runs (in case virtual machines like VMWare are used).

  2. Stop Polarion server, do the backup, run server again.

  3. On Windows, do not use backup software which opens files in write mode, because that may cause corruption of index-related files and would require a re-index operation afterwards)

  4. If running on Windows and backup software does open files in write mode, configure the job "Live Plan Refresh" not to run during the backup (this job is most likely to work with the index and stands the greatest chance of index corruption resulting)

When doing recovery from a backup of the running system (i.e., not a snapshot of the virtual machine, or the server was not stopped during the backup), it will most probably be necessary to run a re-index operation.

Indexing and Reindex

Polarion stores all data in the Subversion repository. While this approach brings many advantages (history, branching, etc.), compared to traditional database approach it does entail some performance trade-offs. Polarion uses advanced caching and indexing techniques to achieve acceptable performance levels. In most standard situations, the caching and indexing behaves transparently and users do not need to take care of it. However, the caching and indexing logic imposes certain restrictions and requirements for what users can and cannot do. This section explains these limitations in more detail.

Index Synchronization

The following events initiate index updating:

  • Commits to the Subversion repository (including changes initiated by Polarion)

  • Polarion start-up

The index contains information about location of all entities (Work Items, etc.) in the repository and their history, so the term "index" refers to more things then just the index used by the Search feature. Rather it is the entire indexing scheme that enables optimal performance.

During the index update the Polarion checks all changes made to repository since the last indexed revision and update the index accordingly.

Changing sort order of an enumeration, dates of time points, etc. which are already referenced will cause inconsistency in the sorting. Some referrals will be sorted by to the old sort order, and some by the new. A complete index rebuild solves this problem.

Note

If all you need to do is refresh lists of enumerations because of changes to some enumeration(s), you do not necessarily need to run a full re-index. For more information see: Administrator's Guide: Configuring Enumerations: Enumerations and Database Issues.

When to Repair the Index

Symptoms of a "broken" index tend to be the following: some Work Items are not up-to-date, some are missing, history cannot be viewed or shows invalid or truncated information.

First Remedies

You may not need to completely rebuild the index if you observe the above symptoms.

  1. Try an index refresh on the repository, or on a specific project. This corrects problems with information updating.

    Go to the Administration interface and open the Repository (if you want to refresh the entire repository), or a project (if the problem seems to affect only that project). Then, in Navigation, select Maintenance. In the Index section, check the index(s) to refresh and click Refresh Index. (Note that the indexes listed varies depending on whether you are working in Repository or project scope).

  2. If number 1 above does not fix all symptoms, try running the Check Index button. The index check job should bring back Work Items that are missing from view.

If the above steps do not fix the symptoms, then you will need to rebuild the index, as described in the next section.

How to Rebuild the Index

The procedure may sometimes be referred to as "index rebuild", "rebuild index", "index synchronization", or "index rebuilding".

There are two important things for an administrator to keep in mind before initiating an index rebuild:

  • The Polarion server must be shut down before commencing an index rebuild.

  • Depending on the size of the repository, reindexing time can range from a few minutes to several hours. End users will not be able to use the system during the reindexing process.

    If possible, you should plan to perform any re-index operation at a time when system usage is low, and downtime is not critical for end users.

Configuring CPU Usage for Indexing

It is possible to configure how many CPU cores ("workers") are used in these phases of the indexing process. There is one basic system property - com.polarion.startup.workers - that can be configured to define total number of workers for all phases of reindex that can run in parallel. Administrators can also specify different numbers for individual phases in instances of the system property com.polarion.startup.workers.phase#, where # can be any of the following:

  • 3 - for Context Initialization (phase 3)

  • 7 - for Data Indexing (phase 7)

  • 8 - for calculating calculated fields (phase 8)

  • 10 - for Attachment indexing (phase 10, AttachmentIndexer job)

  • 11 - for History Indexing (phase 11, DBHistoryCreator job)

By default, the number of CPU cores used for the above phases is total cores, divided by 2, plus 1. For example, on a CPU with 4 cores, the default usage is (4/2) + 1 = 3 cores. Maximum workers for all phases is limited to 8.

In the default setup, the jobs are configured to run only between 19:00 and 08:00 (and they can be stopped and started by scheduled jobs) so in most cases there should be no need to redefine the number of workers. Adjusting the number of workers may be worth doing for the jobs running after Polarion start-up that may cause performance to slow.

To explicitly set core usage for all index phases and/or the configurable index phases listed above, you must add the following lines to the system properties file polarion.properties:

  • Total workers for all phases:

    com.polarion.startup.workers=[N] (where [N] is an integer value that should not exceed the total available CPU cores).

    Example: com.polarion.startup.workers=8

  • Workers for specific phases:

    com.polarion.startup.workers.phase#=[N] (where # is the phase, and [N] is an integer value specifying the number of workers to be used for the specified phase.

    Examples:

    • com.polarion.startup.workers.phase3=2

    • com.polarion.startup.workers.phase10=3

Note

The location of the polarion.properties file can be found in the Administrator's Reference: System Properties File Location.

Launching the Index Rebuild Scripts

You perform the reindexing by running the appropriate reindexing script for your operating system:

  • Windows: C:\Polarion\polarion\reindex.bat

  • Linux: $POLARION_HOME$/bin/polarion.init reindex

Progress of the reindexing operation is reported in the console and written to a log file.

Important

Do not interrupt the index rebuild process. The process writes messages to the console and the log4j-startup-TIMESTAMP.log log file. Check this file for the status of the process. As mentioned, with large repositories the index rebuild can take several hours, and it may seem that nothing is happening for long periods.

Reindex must be restarted if interrupted. If you believe there may be a problem with the process, contact Polarion technical support before attempting to kill the reindex rebuild process.

Understanding the Re-index Process

The reindexing scripts perform the following operations:

  1. Back up of the polarion-data folder. (The folder is renamed to polarion-data.backup.)

    (Path: $POLARION_HOME$/data/workspace/polarion-data)

  2. Start the Polarion service. (As mentioned previously, the service should be shut down before running the script.)

  3. Regenerate the index in the polarion-data folder. As previously noted, this can take considerable time during which users will not be able to access the system.

User Impact

Users cannot use the system while the system indexes are being rebuilt. They can, however, use the system while the historical database is being reindexed.

The embedded historical SQL database, which replicates the Subversion repository to facilitate complex queries, is indexed in the background. Although users can use the system, some features are either not available, or do not display information until the database reindex is complete. A message is displayed at the top of the Navigation panel warning users that database indexing is in progress. When the message is present...

  • Baseline (Time Machine) feature is not available.

  • Reports that contain SQL queries on the historical database do not work and display error messages.

  • Burn-up and burn-down charts in Plans do not work and display error messages.

  • Test management form extensions do not work.

Using Polarion Diagnostics

Polarion comes with a self-diagnostic utility, Polarion Diagnostic Tool (PDT). If your system is not performing as it should, you can use this tool to run comprehensive diagnostic tests and communicate the results to the technical support team by email or FTP upload. PDT checks if Polarion is running in a cluster and gathers configurations from shared folders.

The utility is bundled into all product distributions. It is located in the diagtool folder under the root of your Polarion installation. Complete documentation (diagtool.pdf) covering setting up and running the PDT utility is included in that folder.

Reminder

If administrators disable all execute.command jobs the Polarion Diagnostic Tool (PDT) is also disabled.

Recovering Disk Space

Over time your server's disk storage can accumulate a large amount of data that does not need to be kept. For example, if your process involves nightly or other frequent builds, these can eventually consume a lot of disk storage, but the don't really need to be kept indefinitely. Old log files can also consume disk space. This section discusses ways to clean up your server's disk storage and recover disk space.

Cleaning Up Old Builds

Polarion comes pre-configured with the build.clean job for cleaning up builds and related things like local deployment space.

To have the job delete the local deployment space directory, set the localDeploymentSpaceName to the name of the local deployment space. For example:

<job name="Builds Cleanup" id="build.clean" cronExpression="0 0 1 ? * MON-SAT" scope="system">
    <localDeploymentSpaceName>_default</localDeploymentSpaceName> 
</job>                    
                

To have old builds deleted from BIR, three job parameters must be set:

  • maxBuildAgeDays

  • minSuccessfulBuildsCount

  • buildArtifacts

The job deletes builds of all build artifacts that match at least one of the selectors from buildArtifacts, but only those builds that were started at least before maxBuildAgeDays days. At least the number of builds specified in minSuccessfulBuildsCount are preserved provided at least that number of successful builds exist (i.e. builds with status OK). Build selector format is GROUP_ID:ARTIFACT_ID, where each part can include a suffix * matching any string. For example:

<job name="Builds Cleanup" id="build.clean" cronExpression="0 0 1 ? * MON-SAT" scope="system">
    <maxBuildAgeDays>7</maxBuildAgeDays>
    <minSuccessfulBuildsCount>3</minSuccessfulBuildsCount>
    <buildArtifacts>
        <buildArtifact>org.acme.*:*</buildArtifact>
    </buildArtifacts>
</job>                    
                

See also: Administrator's Guide: System Maintenance: Configuring the Scheduler.

Cleanup Old Log Files

You can configure and run the logs.cleanup job to delete log files with specified names that are older than a specified date. (See Configuring the Scheduler for more information on working with scheduled jobs.)

Scheduler Configuration

The following example shows the basic structure of the log cleanup job configuration.

<job name="_ARBITRARY_JOB_NAME_"id="logs.cleanup" cronExpression="0 15 10 ? * MON-FRI" scope="system" disabled="true">
    <maxFileAgeDays>_MAX_AGE_OF_FILE_IN_DAYS_</maxFileAgeDays>
    <filePatterns>
        <filePattern>_FOLDER_|_PATTERN_</filePattern>
        ... <filePattern> ...
    </filePatterns>
</job>                        
                    

  • cronExpression= Lets you schedule an automatic cleanup of old log files.

    If the cronExpression="" field is left empty and/or disabled= set to "true", log cleanups will need to be triggered manually.

    (Via the Scheduler.)

  • Cron Expression Example: "0 15 01 ? * SAT" values would schedule the log cleanup every Saturday at 1:15 am.)

    (Recommendation: Larger enterprise organizations should also consider using an external central monitoring application for saving and archiving logs.)

  • _FOLDER_ is where to find log files

  • _PATTERN_ is a file name prefix regular expression

  • _FOLDER_ and _PATTERN_ are concatenated with | (pipe)

File name prefix is matched against all files in the folder, those matching the same prefix are treated together, From this set, all files older than _MAX_AGE_OF_FILE_IN_DAYS_ are removed with the exception of the newest one which is always kept.

Example file pattern #1: C:/Polarion/data/logs/main|log4j-[^2]*2

Job result:

  • C:/Polarion/data/logs/main/log4j-20090525-1057-23.log (will be kept)

  • C:/Polarion/data/logs/main/log4j-20090523-0457-87.log (will be deleted if older than specified number of days)

  • C:/Polarion/data/logs/main/log4j-20090525-1057-23.log.2009-12 (will be deleted if older than specified number of days)

  • C:/Polarion/data/logs/main/log4j-startup-20090525-1057-23.log (will be kept)

  • C:/Polarion/data/logs/main/log4j-startup-20090525-1057-23.log.2009-12 (will be deleted if older than specified number of days)

Example file pattern #2: C:/Polarion/data/logs/apache|.*\.log

Job result:

  • C:/Polarion/data/logs/apache/access.log.2009-05-25 (will be kept)

  • C:/Polarion/data/logs/apache/access.log.2009-05-20 (will be deleted if older than specified number of days)

  • C:/Polarion/data/logs/apache/error.log.2009-05-20 (will be kept)

See also: Administrator's Guide: System Maintenance: Configuring the Scheduler.

Maintaining Subversion (SVN)

This section provides guidance for administrators on maintaining and updating the Subversion component of the Polarion system to ensure optimal performance. The information here is mainly about repository format and protocol. Once you have these in place, see Advanced Administration: Optimizing Subversion.

Use the Latest Repository Format

Use latest repository format with default configuration for best performance. To migrate the SVN repository to a new format:

  1. Dump repository via command: svnadmin dump -M 1024 repository_path > dump_file.out

    • The in-memory cache (-M) option was introduced only in SVN 1.9.

    • This operation may take hours and you need to make sure that all revisions will be dumped, either by taking your SVN offline, or doing incremental dump and load when switching the repository.

  2. Create new repository in new storage format via command svnadmin create repo_path.

    • By default this creates new repository storage in newest format with default (and recommended) settings

    • It is advisable to secure access to repository via the configuration in repo_path/conf/svnserve.conf.

    • Ensure that there are the same permissions and owners set for the new repository as for the old one.

  3. Load the old repository contents from the dump to the new repository via command: svnadmin load -M 1024 repo_path < dump_file.out

    • The in-memory cache (-M) option was introduced only in SVN 1.9.

    • This operation may take days for large repositories with hundreds of thousands of revisions, so make sure to utilize the in-memory cache and fast storage (SSD) for this operation.

    • Doing incremental dump and load when switching the repository can help you to limit the downtime.

    • Pack the repository after import.

Pack the Repository

To be sure that caches are optimally utilized, your should pack the repository regularly. Packing weekly is a good interval for many installations.

To pack the repository, execute via crond: svnadmin pack repository_path.