Journal files

The current journal is the running transaction log that keeps track of all the Helix Core Server database modifications since the previous checkpoint or journal. Journal file rotation is an incremental metadata backup, and the checkpoint is a full metadata backup.

Tip

Journals can grow to be quite large. Frequent journal rotation reduces the size of each journal file. You might consider daily journal rotation and weekly checkpoints.

To restore the server database to the most recent point in time, you need:

The most recent checkpoint.
Any journal files created since that checkpoint.
The journal file that was active at the time the server was stopped.

For example, suppose it is Wednesday and you have:

The weekly checkpoint file that you create before your users start work on Monday.
The daily journal files for Monday and Tuesday.
The currently running journal file of Wednesday.

If a disk crash occurs on Wednesday that corrupts the server database, you can restore the server database by using Monday's checkpoint file, the rotated journal files for Monday and Tuesday, and Wednesday's journal file.

Journal file names

The journal file grows until it is rotated by a checkpoint or a journal rotation command, such as p4 admin journal. If the current journal is extremely large, a checkpoint is needed.

Every checkpoint, including your first checkpoint, starts a new journal file and renames the old journal file. We call this "journal rotation".

Rotated journals are in the P4ROOT directory and named journal.n, where

journal. represents the value of the journalPrefix configurable with the suffix .jnl.
n is the incrementing journal number

For example, if the journalPrefix is /p4/1/logs/master, the first three rotated journals are stored as

/p4/1/logs/master.jnl.1

/p4/1/logs/master.jnl.2

/p4/1/logs/master.jnl.3

For an example of making a checkpoint and rotated journal file, see the steps in the Backup procedure topic.

Note

On Windows Server 2016 and newer, journal rotation can be performed using an atomic rename instead of a copy and truncate operation. To enable this feature, see the filesys.atomic.rename configurable in Helix Core Command-Line (P4) Reference.

Location of the journal

Journaling is automatically enabled on all Windows and Linux platforms. By default, the current journal filename is journal, and the file resides in the P4ROOT directory. However, if a failure corrupts that root directory, your journal file will be inaccessible.

Warning

To reduce risk, make sure that the journal file and the Helix Server root are located on different file systems, ideally on different physical drives.

To change the name and location of the journal, do one of the following:

specify the name and path of the journal file in the environment variable P4JOURNAL
include the -J filename option when starting p4d and make sure that subsequent checkpoints use the same file, or the journal will not be properly renamed

Tip

To restore your database, you only need to keep the most recent journal file accessible. Consider also archiving old journals with old checkpoints. This makes it possible to restore to an older checkpoint.

Whether you use P4JOURNAL or the -J journalfile option to p4d, the journal filename can be provided either as an absolute path, or as a path relative to the server root.

Example Specify journal files

Starting the service with:

$ p4d -r $P4ROOT -p 1666 -J /usr/local/perforce/journalfile
Perforce Server starting...

requires that you either checkpoint with:

$ p4d -r $P4ROOT -J /usr/local/perforce/journalfile -jc
Checkpointing to checkpoint.19...
Saving journal to journal.18...
Truncating /usr/local/perforce/journalfile...

or set P4JOURNAL to /usr/local/perforce/journalfile and use the following command:

$ p4d -r $P4ROOT -jc
Checkpointing to checkpoint.19...
MD5(checkpoint.19)=48769A82387B04987568309823E784C9
Rotating /usr/local/perforce/journalfile to journal.18

Important

Make sure your P4JOURNAL environment variable (or command-line specification) matches the setting used when you started the Perforce service. Otherwise the journal is neither saved nor truncated.

Checkpoint and journal history

You can use the p4 journals command to display the history of checkpoint and journal activity for the server. This history includes information about the following events:

the server takes a checkpoint
journal rotation
journal replay
checkpoint scheduling.

For detailed information about command output and options, see the description of the p4 journals command in the Helix Core Command-Line (P4) Reference.

Verify journal integrity

You can verify the integrity of a checkpoint using the p4d -jv command.

Automate maintenance work after journal rotation

See Triggering on journal rotation.

Disable journaling

To disable journaling, stop the service, remove the existing journal file (if it exists), set the environment variable P4JOURNAL to off, and restart p4d without the -J option.