snapraid/snapraid_log.1

.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...<EOL>
.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 <EOL>
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:<uint>
The size of a block in bytes.
.TP
.B summary:parity_block_count:<uint>
The total number of blocks allocated for all parity levels.
.TP
.B summary:parity_block_total:<name>:<uint>
Total blocks available for a specific parity level.
.TP
.B summary:parity_block_free:<name>:<uint>
Free blocks available for a specific parity level.
.TP
.B summary:parity_block_free_min:<uint>
The minimum number of free blocks across all parity levels.
.TP
.B summary:file_count:<uint>
Total number of files in the array.
.TP
.B summary:file_block_count:<uint64>
Total number of data blocks used by files.
.TP
.B summary:fragmented_file_count:<uint>
Total number of fragmented files.
.TP
.B summary:excess_fragment_count:<uint>
Total number of excess fragments (one less than the total fragments).
.TP
.B summary:zerosubsecond_file_count:<uint>
Total number of files with a zero sub\-second timestamp.
.TP
.B summary:file_size:<uint64>
Total size of all files in bytes.
.TP
.B summary:parity_size:<uint64>
Total size of allocated parity blocks in bytes.
.TP
.B summary:parity_size_max:<uint64>
Maximum possible parity size (allocated + min free) in bytes.
.TP
.B summary:hash:<name>
The current hash algorithm in use.
.TP
.B summary:prev_hash:<name>
The previous hash algorithm used.
.TP
.B summary:best_hash:<name>
The best hash algorithm for optimal performance.
.TP
.B summary:total_wasted:<uint64>
Total wasted space (space on data disks exceeding parity capacity) in bytes.
.TP
.B summary:total_used:<uint64>
Total used space by data files in bytes.
.TP
.B summary:total_free:<uint64>
Total free space (usable by data) in bytes.
.TP
.B summary:total_use_percent:<uint>
Overall array use percentage.
.TP
.B summary:has_unsynced:<uint>
Count of blocks that are unsynced (need a sync).
.TP
.B summary:has_unscrubbed:<uint>
Count of blocks that are unscrubbed (just synced).
.TP
.B summary:has_rehash:<uint>
Count of blocks needing a rehash.
.TP
.B summary:has_bad:<count>:<first>:<last>
Count of bad blocks, along with the first and last bad block index.
.TP
.B summary:scrub_oldest_days:<uint>
Days ago the oldest block was last scrubbed.
.TP
.B summary:scrub_median_days:<uint>
Days ago the median block was last scrubbed.
.TP
.B summary:scrub_newest_days:<uint>
Days ago the newest block was last scrubbed.
.SS Per\-Disk Tags 
These tags provide statistics for individual data disks. \`<name>\`
is the disk name.
.TP
.B summary:disk_file_count:<name>:<uint>
Number of files on the disk.
.TP
.B summary:disk_block_count:<name>:<uint>
Number of blocks used by files on the disk.
.TP
.B summary:disk_fragmented_file_count:<name>:<uint>
Number of fragmented files on the disk.
.TP
.B summary:disk_excess_fragment_count:<name>:<uint>
Number of excess fragments on the disk.
.TP
.B summary:disk_zerosubsecond_file_count:<name>:<uint>
Number of files with zero sub\-second timestamp on the disk.
.TP
.B summary:disk_file_size:<name>:<uint64>
Total size of files on the disk in bytes.
.TP
.B summary:disk_block_allocated:<name>:<uint>
Highest block index used on the disk + 1.
.TP
.B summary:disk_block_total:<name>:<uint>
Total blocks on the disk (physical size).
.TP
.B summary:disk_block_free:<name>:<uint>
Free blocks on the disk.
.TP
.B summary:disk_block_max_by_space:<name>:<uint>
Total blocks by disk space (used + free blocks).
.TP
.B summary:disk_block_max_by_parity:<name>:<uint>
Total blocks limited by parity space (parity size + min parity free blocks).
.TP
.B summary:disk_block_max:<name>:<uint>
Maximum usable blocks (minimum of \`..._by_space\` and \`..._by_parity\`).
.TP
.B summary:disk_space_wasted:<name>:<int64>
Wasted space on the disk in bytes (positive if disk is larger than usable parity space).
.TP
.B summary:disk_used:<name>:<uint64>
Used space on the disk in bytes.
.TP
.B summary:disk_free:<name>:<uint64>
Free usable space on the disk in bytes.
.TP
.B summary:disk_use_percent:<name>:<uint>
Disk use percentage relative to \`disk_block_max\`.
.SS File Timestamp Tags 
These tags list files with zero sub\-second timestamps.
.TP
.B zerosubsecond:<disk_name>:<file_path>
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:<uint>
The total number of blocks in the array.
.TP
.B block:<index>:<time>:<used>:<unsynced>:<bad>:<rehash>
Status of a specific block.
.RS 4
.PD 0
.HP 4
.I <index>
Block index.
.HP 4
.I <time>
Last scrub time (Unix timestamp).
.HP 4
.I <used>
\[dq]used\[dq] if the block contains data.
.HP 4
.I <unsynced>
\[dq]unsynced\[dq] if the block needs a sync.
.HP 4
.I <bad>
\[dq]bad\[dq] if the block has errors.
.HP 4
.I <rehash>
\[dq]rehash\[dq] if the block needs a rehash.
.PD
.RE
.TP
.B block_noinfo:<index>:<used>:<unsynced>
Status of an unused block (no info recorded).
.SS Scrub History Tags 
These tags provide details on the scrub/sync time distribution.
.TP
.B info_count:<uint>
Total number of info recorded about past scrub and sync
operations.
.TP
.B info_time:<time>:<count>:<status>
All the info records.
.RS 4
.PD 0
.HP 4
.I <time>
Unix timestamp of the scrub/sync.
.HP 4
.I <count>
Number of blocks processed at this timestamp.
.HP 4
.I <status>
\[dq]scrubbed\[dq] or \[dq]new\[dq] (for synced blocks).
.PD
.RE
.TP
.B scrub_graph_range:<max_columns>:<max_height>
Dimensions of the scrub history graph obtained from the
\`info_time\` records. This provides the boundary for the
precomputed graph data available in the \`scrub_graph_bar\` tags.
.RS 4
.PD 0
.HP 4
.I <max_columns>
The number of columns in the graph (constant
GRAPH_COLUMN).
.HP 4
.I <max_height>
The maximum height (peak count) of blocks found
in any column (the highest sum of scrubbed and new blocks).
.PD
.RE
.TP
.B scrub_graph_bar:<index>:<days_ago>:<scrubbed>:<new>
Data for a column of the scrub history graph.
.RS 4
.PD 0
.HP 4
.I <index>
Column index. From 0 to max_columns \- 1.
.HP 4
.I <days_ago>
Days ago for this column\'s time range.
.HP 4
.I <scrubbed>
Count of scrubbed blocks in that day.
.HP 4
.I <new>
Count of newly synced (unscrubbed) blocks in that day.
.PD
.RE