Inspect Aria Transaction Log Pages Safely with aria_dump_log

You will finish with a controlled way to read raw pages from a MariaDB Aria log file, limit the amount read, and distinguish inspection from recovery. The examples use aria_dump_log Ver 1.1 from the installed mariadb-server package, version 10.11.14-0ubuntu0.24.04.1.

Allow about fifteen minutes. You need shell access, a readable copy of an Aria log file, and enough permission to read the directory containing it. This guide does not stop MariaDB, delete log files, apply recovery, or edit an option file. Those actions can affect service availability or data integrity.

1. Check the installed utility

Start with read-only checks. You do not need sudo for these commands:

$ command -v aria_dump_log
/usr/bin/aria_dump_log
$ aria_dump_log --version
aria_dump_log Ver 1.1 for debian-linux-gnu on x86_64
$ dpkg-query -W -f='${Package} ${Version}\n' mariadb-server
mariadb-server 1:10.11.14-0ubuntu0.24.04.1

The program is a low-level page dumper. Its own help distinguishes it from aria_read_log, which is the tool for displaying and applying logical log records. Do not swap the commands because their names look similar.

Checkpoint: confirm the syntax your machine provides:

$ aria_dump_log --help | sed -n '1,35p'
Dump the raw content of aria log pages.
...
Usage: aria_dump_log OPTIONS aria_log_file

2. Identify a log file without changing the server

MariaDB documents aria_log_control as the small control file and aria_log.* as the files containing Aria operations. Their location follows the configured Aria log directory, which is commonly the server data directory. Check the actual directory in your deployment rather than assuming /var/lib/mysql:

$ mariadb -NBe "SHOW VARIABLES LIKE 'aria_log_dir_path'"
aria_log_dir_path	/var/lib/mysql

If you cannot connect to the server, inspect the service configuration and data-directory permissions through your normal administrative process. Do not guess from a similarly named test file. The input must be the log file you intend to examine, not aria_log_control.

Reading a live log while MariaDB is writing it can produce a moving or incomplete view. For an incident record, obtain a consistent copy through your backup or maintenance procedure. A simple shell copy is only suitable when you already know the file is no longer changing and you have permission to read it:

$ install -m 600 /var/lib/mysql/aria_log.00000001 /tmp/aria_log.00000001.copy
$ test -r /tmp/aria_log.00000001.copy && echo readable
readable

The install command creates a new copy and leaves the source alone. Remove the temporary copy after your investigation with rm -- /tmp/aria_log.00000001.copy only when you no longer need it. That removal is irreversible, so do not put it into a script that runs before you have saved the evidence you need.

3. Dump a small, explicit range

Use -f or --file to name the input. Begin with an offset of zero and a small page count so that terminal output remains manageable:

$ aria_dump_log --no-defaults \
    --file=/tmp/aria_log.00000001.copy \
    --offset=0 \
    --pages=4
<raw page output from the selected Aria log>

The output is raw page-oriented diagnostic data, not a SQL dump. Exact lines depend on the file and the installed build. A successful exit status tells you the read completed; it does not tell you that the log belongs to the server you expected.

--offset selects where reading starts, and --pages limits how many pages are read. The manpage does not define a portable unit for the offset, so use values supplied by the diagnostic procedure or the tool's surrounding documentation. Do not invent an offset by copying a byte position from an unrelated log format.

Checkpoint: capture the status separately if a script needs to make a decision:

$ aria_dump_log --no-defaults --file=/tmp/aria_log.00000001.copy --offset=0 --pages=1 > /tmp/aria-page.txt
$ status=$?
$ printf 'aria_dump_log status: %s\n' "$status"
aria_dump_log status: 0

The sample status is what a readable, valid input should produce. If your file is truncated, from another build, or not an Aria log, treat the diagnostic output as a failure until you have established why.

4. Prevent option-file surprises

By default, aria_dump_log reads options from /etc/my.cnf, /etc/mysql/my.cnf and ~/.my.cnf, in that order, using the [aria_dump_log] group. A local option file can therefore change the file, offset, page count or unit-test mode without appearing in the command you copied.

Use --no-defaults as the first argument for a reproducible inspection. The command below safely demonstrates the effective argument list without opening a log:

$ aria_dump_log --no-defaults --print-defaults
aria_dump_log would have been started with the following arguments:

An empty list is expected when no defaults are being read. If you need a project-specific configuration, use --defaults-file=/path/to/aria-dump.cnf as the first argument and review that file before running. Do not use a writable, untrusted configuration path: option files can redirect the read and can make a diagnostic command behave differently from its appearance.

5. Use unit-test mode only for unit-test logs

The -U or --unit-test option selects a record table for logs created by unit tests. It is not a general compatibility switch and is not a way to repair a production log:

$ aria_dump_log --no-defaults --unit-test --file=/path/to/unit-test-aria.log --pages=1
<raw diagnostic output, if the file is a compatible unit-test log>

Leave -U out for an ordinary server Aria log. If the output becomes nonsensical, first verify the source file and option mode rather than trying several flags at random.

6. Separate inspection from recovery

aria_dump_log reads and reports pages. It does not apply transactions to tables. If you need logical record display or recovery, stop and use the documented aria_read_log workflow with a backup and an explicit maintenance plan. In particular, never replace a damaged log, delete aria_log.*, or run a recovery option just because a dump looks unfamiliar. Those changes can remove evidence or alter tables.

A missing-file error is usually a path, permission or retention problem. Recheck the exact path without escalating privileges:

$ ls -l -- /tmp/aria_log.00000001.copy
$ test -r /tmp/aria_log.00000001.copy && echo readable || echo not-readable
readable

For comparison, the installed utility returns a non-zero status when the input does not exist:

$ aria_dump_log --no-defaults --file=/tmp/does-not-exist --pages=1
aria_dump_log: File '/tmp/does-not-exist' not found
aria_dump_log: FAILED
$ echo $?
1

Do not "fix" that result by granting broad permissions to the data directory. Ask the database administrator for a controlled copy, or run the read as the account that already owns the MariaDB data.