From 207e8acaf1350153aa84bf477ca786c5ccb2de46 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Wed, 10 Dec 2025 14:47:26 +0100 Subject: [PATCH] Preliminary documentation of the log file --- Makefile.am | 16 ++- snapraid.1 | 3 +- snapraid.d | 3 +- snapraid.txt | 3 +- snapraid_log.1 | 283 +++++++++++++++++++++++++++++++++++++++++++++++ snapraid_log.d | 197 +++++++++++++++++++++++++++++++++ snapraid_log.txt | 204 ++++++++++++++++++++++++++++++++++ 7 files changed, 705 insertions(+), 4 deletions(-) create mode 100644 snapraid_log.1 create mode 100644 snapraid_log.d create mode 100644 snapraid_log.txt diff --git a/Makefile.am b/Makefile.am index 8a9f87b4..523155a5 100644 --- a/Makefile.am +++ b/Makefile.am @@ -125,6 +125,7 @@ EXTRA_DIST = \ autogen.sh autover.sh \ README AUTHORS HISTORY INSTALL COPYING TODO CHECK INSTALL.windows \ snapraid.d snapraid.1 snapraid.txt \ + snapraid_log.d snapraid_log.1 snapraid_log.txt \ test/test-par1.conf \ test/test-par2.conf \ test/test-par3.conf \ @@ -146,7 +147,7 @@ EXTRA_DIST = \ raid/test/speedtest.c \ raid/test/invtest.c -man_MANS = snapraid.1 +man_MANS = snapraid.1 snapraid_log.1 clean-local: rm -f valgrind.log callgrind.log cachegrind.log @@ -160,6 +161,7 @@ clean-local: maintainer-clean-local: rm -f snapraid.1 snapraid.txt + rm -f snapraid_log.1 snapraid_log.txt # Automatic testing @@ -1020,6 +1022,18 @@ snapraid.html : snapraid.d snapraid.hh : snapraid.d advd2 frame < $(srcdir)/$< > $@ + +snapraid_log.1 : snapraid_log.d + advd2 man < $(srcdir)/$< > $@ + +snapraid_log.txt : snapraid_log.d + advd2 txt < $(srcdir)/$< | todos > $@ + +snapraid_log.html : snapraid_log.d + advd2 html < $(srcdir)/$< > $@ + +snapraid_log.hh : snapraid_log.d + advd2 frame < $(srcdir)/$< > $@ endif # Windows distribution diff --git a/snapraid.1 b/snapraid.1 index 1d183d57..e091ac80 100644 --- a/snapraid.1 +++ b/snapraid.1 @@ -1217,6 +1217,7 @@ the \'%\' character, e.g., result\-%%D.log. To use \'>>\', you must enclose the name in quotes, e.g., \[dq]>>result.log\[dq]. To output the log to standard output or standard error, you can use \[dq]>&1\[dq] and \[dq]>&2\[dq], respectively. +See the snapraid_log.txt file or man page for log tag descriptions. .TP .B \-L, \-\-error\-limit NUMBER Sets a new error limit before stopping execution. @@ -1884,4 +1885,4 @@ in UTF\-8 format. .SH COPYRIGHT This file is Copyright (C) 2025 Andrea Mazzoleni .SH SEE ALSO -rsync(1) +snapraid_log(1), rsync(1) diff --git a/snapraid.d b/snapraid.d index 6f28b80a..9e7da993 100644 --- a/snapraid.d +++ b/snapraid.d @@ -939,6 +939,7 @@ Options enclose the name in quotes, e.g., ">>result.log". To output the log to standard output or standard error, you can use ">&1" and ">&2", respectively. + See the snapraid_log.txt file or man page for log tag descriptions. -L, --error-limit NUMBER Sets a new error limit before stopping execution. @@ -1449,4 +1450,4 @@ Copyright This file is Copyright (C) 2025 Andrea Mazzoleni See Also - rsync(1) + snapraid_log(1), rsync(1) diff --git a/snapraid.txt b/snapraid.txt index ebf5a51b..a1da72ca 100644 --- a/snapraid.txt +++ b/snapraid.txt @@ -998,6 +998,7 @@ SnapRAID provides the following options: enclose the name in quotes, e.g., ">>result.log". To output the log to standard output or standard error, you can use ">&1" and ">&2", respectively. + See the snapraid_log.txt file or man page for log tag descriptions. -L, --error-limit NUMBER Sets a new error limit before stopping execution. @@ -1563,4 +1564,4 @@ This file is Copyright (C) 2025 Andrea Mazzoleni 13 SEE ALSO =========== -rsync(1) +snapraid_log(1), rsync(1) diff --git a/snapraid_log.1 b/snapraid_log.1 new file mode 100644 index 00000000..32bf56a9 --- /dev/null +++ b/snapraid_log.1 @@ -0,0 +1,283 @@ +.TH "SnapRAID Log Format" 1 +.SH NAME +snapraid_log \- SnapRAID Log Format +.SH DESCRIPTION +This document describes the structured log tags output by SnapRAID, +which are designed to be used by tools monitoring the SnapRAID +processing state. The tags provide information in an easy\-to\-parse +format, ideal for automation and integration. +.PP +To capture these structured log tags, you must use the \`\-\-log\` option +with SnapRAID. +.PP +You can direct the output to a specific file, or force the output to +the standard output or standard error using the special arguments +\`>&1\` or \`>&2\`. Note that these arguments often need to be quoted on +the command line to prevent the shell from interpreting them. +.PP +Example: +.PP +.RS 4 +snapraid status \-\-log \[dq]>&2\[dq] +.PD 0 +.PD +.RE +.PP +The output tags strictly adhere to the following format: +.PP +NAME:VALUE:VALUE:VALUE... +.PD 0 +.PD +.TP +.B NAME +This is the primary tag identifier, always a lowercase string +without spaces (e.g., \`summary\`, \`block\`, \`info_time\`). +.TP +.B VALUE +Following the \`NAME\`, these can be additional sub\-identifiers, +descriptive names (like a disk name), or numeric/string data +values. They are separated by a colon \`:\`. +.TP +.B +Each tag is terminated by an end\-of\-line character. +.PP +This document provides a summary of the tags generated by SnapRAID. +For the most detailed and up\-to\-date information regarding the meaning +and context of the values, it is recommended to check the source +code\'s \`log_tag()\` statements. +.SH STATUS +This section describe the tags output with the \`status\` command. +.PP +All tags start with a prefix indicating the context, typically \`summary:\` +for overall statistics or a disk/block context. +.SS General Summary Tags +These tags provide general information about the array configuration and overall state. +.TP +.B summary:block_size: +The size of a block in bytes. +.TP +.B summary:parity_block_count: +The total number of blocks allocated for all parity levels. +.TP +.B summary:parity_block_total:: +Total blocks available for a specific parity level. +.TP +.B summary:parity_block_free:: +Free blocks available for a specific parity level. +.TP +.B summary:parity_block_free_min: +The minimum number of free blocks across all parity levels. +.TP +.B summary:file_count: +Total number of files in the array. +.TP +.B summary:file_block_count: +Total number of data blocks used by files. +.TP +.B summary:fragmented_file_count: +Total number of fragmented files. +.TP +.B summary:excess_fragment_count: +Total number of excess fragments (one less than the total fragments). +.TP +.B summary:zerosubsecond_file_count: +Total number of files with a zero sub\-second timestamp. +.TP +.B summary:file_size: +Total size of all files in bytes. +.TP +.B summary:parity_size: +Total size of allocated parity blocks in bytes. +.TP +.B summary:parity_size_max: +Maximum possible parity size (allocated + min free) in bytes. +.TP +.B summary:hash: +The current hash algorithm in use. +.TP +.B summary:prev_hash: +The previous hash algorithm used. +.TP +.B summary:best_hash: +The best hash algorithm for optimal performance. +.TP +.B summary:total_wasted: +Total wasted space (space on data disks exceeding parity capacity) in bytes. +.TP +.B summary:total_used: +Total used space by data files in bytes. +.TP +.B summary:total_free: +Total free space (usable by data) in bytes. +.TP +.B summary:total_use_percent: +Overall array use percentage. +.TP +.B summary:has_unsynced: +Count of blocks that are unsynced (need a sync). +.TP +.B summary:has_unscrubbed: +Count of blocks that are unscrubbed (just synced). +.TP +.B summary:has_rehash: +Count of blocks needing a rehash. +.TP +.B summary:has_bad::: +Count of bad blocks, along with the first and last bad block index. +.TP +.B summary:scrub_oldest_days: +Days ago the oldest block was last scrubbed. +.TP +.B summary:scrub_median_days: +Days ago the median block was last scrubbed. +.TP +.B summary:scrub_newest_days: +Days ago the newest block was last scrubbed. +.SS Per\-Disk Tags +These tags provide statistics for individual data disks. \`\` +is the disk name. +.TP +.B summary:disk_file_count:: +Number of files on the disk. +.TP +.B summary:disk_block_count:: +Number of blocks used by files on the disk. +.TP +.B summary:disk_fragmented_file_count:: +Number of fragmented files on the disk. +.TP +.B summary:disk_excess_fragment_count:: +Number of excess fragments on the disk. +.TP +.B summary:disk_zerosubsecond_file_count:: +Number of files with zero sub\-second timestamp on the disk. +.TP +.B summary:disk_file_size:: +Total size of files on the disk in bytes. +.TP +.B summary:disk_block_allocated:: +Highest block index used on the disk + 1. +.TP +.B summary:disk_block_total:: +Total blocks on the disk (physical size). +.TP +.B summary:disk_block_free:: +Free blocks on the disk. +.TP +.B summary:disk_block_max_by_space:: +Total blocks by disk space (used + free blocks). +.TP +.B summary:disk_block_max_by_parity:: +Total blocks limited by parity space (parity size + min parity free blocks). +.TP +.B summary:disk_block_max:: +Maximum usable blocks (minimum of \`..._by_space\` and \`..._by_parity\`). +.TP +.B summary:disk_space_wasted:: +Wasted space on the disk in bytes (positive if disk is larger than usable parity space). +.TP +.B summary:disk_used:: +Used space on the disk in bytes. +.TP +.B summary:disk_free:: +Free usable space on the disk in bytes. +.TP +.B summary:disk_use_percent:: +Disk use percentage relative to \`disk_block_max\`. +.SS File Timestamp Tags +These tags list files with zero sub\-second timestamps. +.TP +.B zerosubsecond:: +Lists files that have a zero sub\-second timestamp. +Up to 50 are logged per disk. +.SS Block Information Tags +These tags are generated when the GUI option is enabled (\`state\->opt.gui\`). +.TP +.B block_count: +The total number of blocks in the array. +.TP +.B block::