Recover Disk Space: Easy THL Clean-Up In Tungsten v7


Transaction History Log (THL) files are the core of Tungsten Replication, containing the actual MySQL write events that are replicated to the replicas.

These files can take up considerable amounts of disk space, making them of interest for housekeeping operations to limit the consumption and ultimately, the cost.

This blog post will walk you through THL management, along with the new command `tpm purge-thl` which helps automate the process when THL needs to be removed prior to the automatic rotation window.

The Brief

THL files are created on the write primary node by the Tungsten Replicator extractor reading the MySQL binary logs, then converting the extracted write events into the THL normalized format for consumption by the downstream Tungsten Replicator appliers.

By default, the log files are kept for 7 days.

If the disk space gets used up, existing THL files cannot be updated, and new THL files cannot be created, which would block replication.

Recognizing this fact, Tungsten provides easy ways to manage the growth of the THL files and associated disk space.

The Basics: Automated Log Retention

The first line of defense is the automatic deletion of THL after a set period of time, called the log retention period.

Configuring the THL Log Retention Period

To drop log files after a certain time period, set the tpm option `--thl-log-retention` to a time interval, defined as:


where the letters stand for Days, Hours, Minutes, or Seconds respectively.

For example, to rotate the THL files after five days instead of seven, use:


and for twelve hours, use:


Key Facts about THL Log Retention

Longer times retain the logs for a greater amount of time, increasing disk space usage while allowing access to the THL information for longer. Shorter logs reduce disk space usage while reducing the amount of log data available.

Please note that old THL files are only deleted when new data is written to the current files. If there has been no THL activity, the log files remain until new THL information is written.

How Long Should THL Logs Be Retained?

It is advised to keep the THL files for at least as long as you keep your MySQL binary log files.

If the THL log retention time is set to lower than the MySQL binary log expiry time, running `tpm install/update` will result in a warning like:

THL retention (5d) is set to less than the binary log expiry policy (10 days) (MySQLTHLBinlogsRetentionCheck)

Advanced: Manual THL Log File Management

In the event that disk space is filling up too quickly, it has always been possible to recover capacity by manually deleting THL files that are no longer needed.

“No longer needed” means the following things:

  • on a replica: all of the events in that THL file have been applied to the target database;
  • on the write primary: all of the events in that THL file have been applied to ALL of the downstream replica databases.

Prior to Version 7: The Long Way

Prior to version 7, a DBA would need to run the `trepctl status` command on each node (or the multi_trepctl command), and manually compare the applied sequence numbers to obtain the lowest one, then check in the THL files themselves for the exact file that contains the seqno, and then finally find the previous THL file in sequence just to be safe, then executing the thhl purge command with the appropriate parameters.

New Tool as of Version 7: tpm purge-thl

As of Tungsten Clustering v7.0.0, you may now recover disk space more easily with some help from the `tpm purge-thl` command.

The idea is to run the command on a replica, then execute the returned command on all nodes as the proper tungsten OS user. This will delete all THL files with events completely applied on all replicas.

To begin, simply execute the command on a replica:

shell> tpm purge-thl
/opt/continuent/tungsten/tungsten-replicator/bin/thl -service emea purge -high 71202

Please avoid running the tool on the write primary! If you run the command on a write primary, you will see a warning like this:

shell> tpm purge-thl
>>> WARNING: This script is running on a Primary node!

Be extra careful to ensure ALL downstream Replicas
have transferred and applied ALL needed THL
BEFORE running this purge-thl command.

/opt/continuent/tungsten/tungsten-replicator/bin/thl -service emea purge -high 71202


In this post we explored the details of THL log retention, including the new tool, `tpm purge-thl`, included with Tungsten version 7.0+.

For more information, please see our online documentation:

Smooth sailing!

About the Author

Eric M. Stone
COO and VP of Product Management

Eric is a veteran of fast-paced, large-scale enterprise environments with 35 years of Information Technology experience. With a focus on HA/DR, from building data centers and trading floors to world-wide deployments, Eric has architected, coded, deployed and administered systems for a wide variety of disparate customers, from Fortune 500 financial institutions to SMB’s.

Add new comment