9.24.3.8. trepctl heartbeat Command

Inserts a heartbeat into the replication stream, which can be used to identify replication points.

trepctl heartbeat [ -name ] [ -tz s ]

The heartbeat system is a way of inserting an identifiable event into the THL that is independent of the data being replicated. This can be useful when performing different operations on the data where specific checkpoints must be identified.

To insert a standard heartbeat:

shell> trepctl heartbeat

When performing specific operations, the heartbeat can be given an name:

shell> trepctl heartbeat -name dataload

Heartbeats insert a transaction into the THL using the transaction metadata and can be used to identify whether replication is operating between replicator hosts by checking that the sequence number has been replicated to the Replica. Because a new transaction is inserted, the sequence number is increased, and this can be used to identify if transactions are being replicated to the Replica without requiring changes to the database. To check replication using the heartbeat:

  1. Check the current transaction sequence number on the Primary:

    shell> trepctl status
    Processing status command...
    NAME                     VALUE
    ----                     -----
    appliedLastEventId     : mysql-bin.000009:0000000000008998;0
    appliedLastSeqno       : 3630
    ...
  2. Insert a heartbeat event:

    shell> trepctl heartbeat
  3. Check the sequence number again:

    shell> trepctl status
    Processing status command...
    NAME                     VALUE
    ----                     -----
    appliedLastEventId     : mysql-bin.000009:0000000000009310;0
    appliedLastSeqno       : 3631
  4. Check that the sequence number on the Replica matches:

    shell> trepctl status
    Processing status command...
    NAME                     VALUE
    ----                     -----
    appliedLastEventId     : mysql-bin.000009:0000000000009310;0
    appliedLastSeqno       : 3631

Heartbeats are given implied names, but can be created with explicit names that can be tracked during specific events and operations.

For example, when loading a specific set of data, the information may be loaded and then a backup executed on the Replica before enabling standard replication. This can be achieved by configuring the Replica to go offline when a specific heartbeat event is seen, loading the data on the Primary, inserting the heartbeat when the load has finished, and then performing the Replica backup:

  1. On the Replica:

    Replica shell> trepctl offline-deferred -at-heartbeat dataload

    The trepctl offline-deferred configures the Replica to continue in the online state until the specified event, in this case the heartbeat, is received. The deferred state can be checked by looking at the status output, and the offlineRequests field:

    Processing status command...
    NAME                     VALUE
    ----                     -----
    appliedLastEventId     : mysql-bin.000009:0000000000008271;0
    appliedLastSeqno       : 3627
    appliedLatency         : 0.704
    ...
    offlineRequests        : Offline at heartbeat event: dataload
  2. On the Primary:

    Primary shell> mysql newdb < newdb.load
  3. Once the data load has completed, insert the heartbeat on the Primary:

    Primary shell> trepctl heartbeat -name dataload

    The heartbeat will appear in the transaction history log after the data has been loaded and will identify the end of the load.

  4. When the heartbeat is received, the Replica will go into the offline state. Now a backup can be created with all of the loaded data replicated from the Primary. Because the Replica is in the offline state, no further data or changes will be recorded on the Replica

This method of identifying specific events and points within the transaction history log can be used for a variety of different purposes where the point within the replication stream without relying on the arbitrary event or sequence number.

9.24.3.8.1. trepctl heartbeat Time Zone Handling

When the Replicator inserts a heartbeart there is an associated timezone. The default uses the Replicator host's timezone.

The -tz option to the trepctl heartbeat command may be used to force the use of a specific timezone.

For example, use GMT as the timezone when inserting a heartbeat:

shell> trepctl heartbeat -tz NONE

Use the Replicator host's timezone to insert the heartbeat:

shell> trepctl heartbeat -tz HOST

Use the given timezone to insert the heartbeat:

shell> trepctl heartbeat -tz {valid timezone id}

If the MySQL server timezone is different from the host timezone (which is strongly not recommended), then -tz {valid timezone id} should be used instead where {valid timezone id} should be the same as the MySQL server timezone.

9.24.3.8.2. trepctl heartbeat Internal Implementation

Internally, the heartbeat system operates through a tag added to the metadata of the THL entry and through a dedicated heartbeat table within the schema created for the replicator service. The table contains the sequence number, event ID, timestamp and heartbeat name. The heartbeat information is written into a special record within the transaction history log. A sample THL entry can be seen in the output below:

SEQ# = 3629 / FRAG# = 0 (last frag)
- TIME = 2013-07-19 12:14:57.0
- EPOCH# = 3614
- EVENTID = mysql-bin.000009:0000000000008681;0
- SOURCEID = host1
- METADATA = [mysql_server_id=1687011;dbms_type=mysql;is_metadata=true;service=alpha;
     shard=tungsten_alpha;heartbeat=dataload]
- TYPE = com.continuent.tungsten.replicator.event.ReplDBMSEvent
- OPTIONS = [##charset = UTF-8, autocommit = 1, sql_auto_is_null = 0,
    foreign_key_checks = 1, unique_checks = 1, sql_mode = 'IGNORE_SPACE', 
    character_set_client = 33, collation_connection = 33, collation_server = 8]
- SCHEMA = tungsten_alpha
- SQL(0) = UPDATE tungsten_alpha.heartbeat SET source_tstamp= '2013-07-19 12:14:57', 
  salt= 9, name= 'dataload'  WHERE id= 1

During replication, Replicas identify the heartbeat and record this information into their own heartbeat table. Because the heartbeat is recorded into the transaction history log, the specific sequence number of the transaction, and the event itself can be easily identified.