SNAPRAID_LOG(1)

📦
version 14.9 · 2 versions
, in fedora 44, nixos 26.05, ubuntu stonking

🦋 NAME 🦋

Okay so bestie, welcome to SnapRAID Log Format(1) — the page that lives in the General Commands Manual section, and yes it's literally called snapraid_log. Say it with me: snapraid_log — SnapRAID Log Format. That's the whole name section, we ate. 💅

✨ DESCRIPTION ✨

So here's the vibe: this doc is all about the structured log tags that SnapRAID spits out. They're built for tools that wanna keep an eye on SnapRAID's processing state 👀. The tags give you info in a format that's easy to parse, which is chef's kiss for automation and integration. No cap.

To actually capture these structured log tags, you must use the --log option with SnapRAID. That's the price of admission, bestie.

You can point the output at a specific file, OR you can force it to standard output / standard error using the special arguments >&1 or >&2. Heads up though: those arguments usually need to be quoted on the command line so the shell doesn't get any funny ideas and interpret them itself. 🙈

Example time, look at this:

snapraid status --log ">&2"

The output tags strictly follow this format, no exceptions:

NAME:VALUE:VALUE:VALUE...<EOL>
  • NAME — this is the main tag identifier, always a lowercase string, never any spaces (think summary, block).
  • VALUE — after the NAME, these can be extra sub-identifiers, descriptive names (like a disk name), or numeric/string data values. They're separated by a colon :.
  • <EOL> — every tag is terminated by an end-of-line character. That's the goodbye kiss. 🫶

This document gives you a summary of the tags SnapRAID generates. But ngl, for the most detailed and most up-to-date info about what the values actually mean and the context around them, you should go check the source code's log_tag() statements. That's the real source of truth, fr fr.

🎀 Escaping, bestie 🎀

When a path gets output, it's always escaped using a backslash (\) as the escape character. Every time.

These are the characters that get escaped into sequences:

  • The colon is escaped to \d.
  • The newline is escaped to \n.
  • The carriage return is escaped to \r.
  • The backslash is escaped to \\.

👑 A couple more things 👑

Some tags only get output when you use the --gui or --gui-verbose option. They're giving extra verbose state and runtime progress that's really only useful for a GUI interface. Iykyk. 💅

Integer values are marked as uint when they're unsigned, and int when they're signed. But lowkey, for practical purposes you can just treat all of them as signed integers. And here's the thing: all integer values should be assumed to be 64 bits wide, regardless of that signed/unsigned marker. Don't forget it. Floating point values are marked as float. 🍓

🌸 CONFIGURATION TAGS 🌸

These tags report the memory usage and the global configuration. Let's go.

  • conf:file:<path> — the configuration file that got loaded (escaped).
  • conf:missing: — you're operating without a configuration file. Living on the edge, periodt.
  • blocksize:<bytes> — the configured block size in bytes (uint).
  • data:<disk_name>:<dir>:<uuid> — the data disks exactly as defined in the configuration file.
    • <disk_name> — the assigned name of the disk.
    • <dir> — the directory entry point of the disk.
    • <uuid> — the UUID of the filesystem containing the dir.
  • mode:<raidname> — the RAID mode in use. One of par1, par2, par3, par4, par5, par6 or parz. The number tells you the maximum number of simultaneous disk failures the array can withstand. That number is important, bestie, respect it. 🫡
  • <parity_level>[/<split_index>]:<path>:<uuid> — the parity files exactly as defined in the configuration file.
    • <parity_level>[/<split_index>] — one of parity, 2-parity. In case of split parity, the parity name is followed by /N to indicate the split index, where N starts from 0. And the /0 is always omitted.
    • <path> — the path (escaped).
    • <uuid> — the UUID of the filesystem containing the path.
  • fsinfo_data:<disk_name>:<size>:<free> — the filesystem information of the specified data disk.
    • <size> — the size of the data disk (uint).
    • <free_size> — the free size in the data disk (uint).
  • fsinfo_parity:<parity_level>:<size>:<free> — the filesystem information of the specified parity disk. In case of multiple splits, this is the sum of the sizes of all splits.
    • <size> — the size of the parity disk (uint).
    • <free_size> — the free size in the parity disk (uint).
  • fsinfo_data_split:<disk_name>:<size>:<free>:<type>:<label> — the filesystem information of the specified data disk.
    • <size> — the size of the data disk (uint).
    • <free_size> — the free size in the data disk (uint).
    • <type> — the filesystem type. A string like ext4, ntfs.
    • <label> — the label associated to the filesystem.
  • fsinfo_parity_split:<parity_level>[/<split_index>]:<size>:<free>:<type>:<label> — the filesystem information of the specified parity split.
    • <size> — the size of the parity disk (uint).
    • <free_size> — the free size in the parity disk (uint).
    • <type> — the filesystem type. A string like ext4, ntfs.
    • <label> — the label associated to the filesystem.
  • pool:<dir> — the configured dir to the pool mount point (escaped). This is the optional mount point for the pool feature. ✨
  • share:<dir> — the configured dir to the pool mount point (escaped). This is the optional mount point for the share feature. ✨
  • autosave:<bytes> — if the autosave feature is enabled, and after how many bytes (uint). This specifies the interval for content file saving. She saves herself automatically, iconic.
  • filter:<pattern> — all the active filters with their patterns. These patterns exclude specific files or directories from the SnapRAID array.
  • filter:nohidden: — if the no-hidden filter is enabled, meaning hidden files/directories (the ones starting with .) are excluded from the array. Sneaky little dotfiles, not today. 🙅

💜 CONTENT TAGS 💜

These tags report the information stored in the content file. Let's get into it.

  • content:<path> — the absolute path to a content file being used (escaped). Content files store the metadata (like file hashes and timestamps) for the array.
  • content_write:<path> — the absolute path to a content file being written (escaped). You'll see multiple writes as the content file is saved in multiple copies.
  • content_data:<disk_name>:<size>:<free_size> — the size of the data disk as stored in the content file.
    • <disk_name> — name of the data disk.
    • <size> — the size of the data disk (uint).
    • <free_size> — the free size in the data disk (uint).
  • content_parity:<parity_level>:<size>:<free_size> — the size of the parity disk as stored in the content file. In case of multiple splits, this is the sum of the sizes of all splits.
    • <parity_level> — name of the parity.
    • <size> — the total size of the parity disk (uint).
    • <free_size> — the free size in the parity disk (uint).
  • content_data_split:<disk_name>:<uuid> — the data disk info as stored in the content file.
    • <disk_name> — name of the data disk.
    • <uuid> — the UUID of the disk filesystem as stored in the content file.
  • content_parity_split:<parity_level>[/<split_index>]:<uuid>:<path>:<size> — the parity split info as stored in the content file.
    • <parity_level>[/<split_index>] — one of parity, 2-parity. In case of split parity, the parity name is followed by /N to indicate the split index, where N starts from 0. And again, the /0 is always omitted.
    • <uuid> — the UUID of the disk containing the path.
    • <path> — the path of the parity file (escaped).
    • <size> — the size of the parity file (uint).
  • content_info:<kind>:<counter> — the counters in the content file. The kind is one of the following:
    • file — the count of files.
    • hardlink — the counter of hardlinks.
    • symlink — the counter of symlinks.
    • dir_empty — the counter of empty directories.
    • block_bad — the counter of bad blocks. Bad blocks indicate data or parity corruption. 😭 Not a drill.
    • block_rehash — the counter of blocks needing a rehash, usually because of a hash algorithm change.
    • block_unscrubbed — the counter of blocks that are unscrubbed (just synced), meaning they have never been verified since their first sync.
    • block_unsynced — the counter of blocks that are unsynced (need a sync), meaning their parity data is out of date. She's behind, bestie.
    • block — the total counter of blocks.
  • bucket_count:<uint> — total number of info records listed with bucket.
  • bucket_block_count:<uint> — total number of info blocks listed with bucket. This is the sum of all the counters listed.
  • bucket:<time>:<count_scrubbed>:<count_new> — the info records.
    • <time> — Unix timestamp of the scrub/sync.
    • <count_scrubbed> — number of blocks scrubbed at this timestamp.
    • <count_new> — number of blocks that were synced at this timestamp and haven't been scrubbed yet.

🌈 DIAGNOSTICS TAGS 🌈

  • version:<version> — the version of SnapRAID run. 👑
  • unixtime:<time> — the current time in the unix format (uint), representing seconds since the epoch.
  • time:<YYYY-MM-DD HH:MM:SS> — the current time in human format. For the girlies who don't read epoch seconds.
  • command:<command> — the command run. One of sync, scrub, check, fix, status, ...
  • argv:<number>:<argument> — all the arguments of the executable command. The 0 one is the executable run.
  • memory:used:<bytes> — the total memory currently used by the application in bytes (uint).
  • memory:block:<bytes> — size of the internal snapraid_block structure in bytes (uint).
  • memory:extent:<bytes> — size of the internal snapraid_extent structure in bytes (uint).
  • memory:file:<bytes> — size of the internal snapraid_file structure in bytes (uint).
  • memory:link:<bytes> — size of the internal snapraid_link structure in bytes (uint).
  • memory:dir:<bytes> — size of the internal snapraid_dir structure in bytes (uint).
bestie this is only part 1 of 6, don't you dare close the tab, there's so much more coming 💖✨

🔍 SCAN TAGS 🔍

okay bestie, these tags are literally the receipts 💅 they report every detected difference between the filesystem and the content file, and they get output for every single discovered change. no skips, no cap. 👑

  • scan:equal:<disk_name>:<path> — a file, link, or directory is equal (unchanged). no action required for this item, it's just vibing ✨ only produced when the --gui-verbose option is used.
    • <disk_name> — name of the data disk.
    • <path> — path to the file/link relative to the disk mount (escaped).
  • scan:add:<disk_name>:<path> — a brand new file or link was found that is not in the content file. this item will be added to the array in a sync. new era unlocked 🎀
  • scan:remove:<disk_name>:<path> — a file or link has been removed from the filesystem since the last sync. gone, bestie 😭
  • scan:update:<disk_name>:<path> — a file or link has been updated (size, timestamp, or link target changed). this item will have its content data blocks re-hashed in a sync. it's giving glow-up ✨
  • scan:move:<disk_name>:<old_path>:<new_path> — a file was moved to a different directory on the same disk. this is an efficient operation that only updates the path metadata without rehashing blocks. lowkey the cheapest thing you can do 🫶
    • <old_path> — the old path to the file (escaped).
    • <new_path> — the new path to the file (escaped).
  • scan:copy:<disk_name>:<path>:<source_disk>:<source_path> — a new file was found to be a copy of a file on the same or any other disk. this is detected by matching the file name, size, and timestamp, and it's an efficient operation that avoids rehashing all blocks. iconic, no notes 💅
    • <source_disk> — the original file's disk.
    • <source_path> — the original file's location (escaped).
  • scan:relocate:<disk_name>:<path>:<source_disk>:<source_path> — like copy, but the original file has disappeared. the difference between move and relocate on the same disk is that move is only used if the inode remains the same. iykyk 🧚
  • scan:restore:<disk_name>:<path> — a file's inode has changed but not its directory, name, timestamp and size, which suggests the file may be restored from backup. the file won't be re-hashed in sync as its precomputed hash is assumed to be correct. trusting the process fr fr 🙈

these tags give you a final count of all the detected changes, the little summary moment at the end 🍓

  • summary:equal:<count> — total number of files and links whose metadata and data match the current parity (uint).
  • summary:added:<count> — total number of brand new files and links not present in the last sync (uint).
  • summary:removed:<count> — total number of files and links that existed in the last sync but are now missing (uint).
  • summary:updated:<count> — total number of existing files where the timestamp or size has changed (uint).
  • summary:moved:<count> — total number of files relocated to a new path or renamed but retaining the same inode (uint).
  • summary:copied:<count> — total number of new files created by copying an existing protected file to a new path (uint).
  • summary:relocated:<count> — total number of new files created by relocating an existing protected file to a new path (uint).
  • summary:restored:<count> — total number of new files matching a parity entry by name/time/size but with a new inode (uint).
  • summary:exit:<status> — logs the overall exit status of the command. the status is one of the following:
    • equal — indicates that no differences were found. the array is already synchronized. slay, nothing to do 🌈
    • diff — indicates that differences were found. the array needs a sync operation.
    • unsynced — the array has an interrupted sync. the array needs another sync operation. it's giving unfinished business 💀

⏱️ GENERAL PROGRESS AND EXECUTION TAGS ⏱️

these tags report the runtime processing of the commands sync, scrub, check and fix. only produced when the --gui option is used. main character energy, live updates, we're watching it happen 👑

  • run:begin:<blockbegin>:<blockend>:<count> — a tag indicating the start of the command execution. we're so back 🎀
    • <blockbegin> — starting block index (uint).
    • <blockend> — ending block index + 1 (uint).
    • <count> — number of blocks to process. it may be less than <blockend> - <blockbegin> + 1 if some blocks are going to be skipped (uint).
  • run:end — a zero-argument tag indicating the end of the command execution. that's a wrap 🫶
  • run:pos:<blockidx>:<blockdone>:<sizedone>:<perc>:<eta>:<speed_mbs>:<cpu>:<elapsed>:<temp>:<steady_temp> — detailed progress information during command execution. the full dossier, bestie 📋
    • <blockidx> — current block index position processed (uint).
    • <blockdone> — number of blocks processed (uint).
    • <sizedone> — current size processed (uint).
    • <perc> — completion percentage (uint).
    • <eta> — estimated time to completion in seconds. empty if not available (uint).
    • <speed_mbs> — data processing speed in MB/s. empty if not available (uint).
    • <cpu> — CPU usage percentage. empty if not available (uint).
    • <elapsed> — elapsed time in seconds (uint).
    • <temp> — current max temperature of the disks. empty if not available (uint).
    • <steady_temp> — expected steady temperature of the disks. empty if not available (uint).
  • sigint:<blockidx>:<msg> — a user interruption (e.g., Ctrl+C) was signaled. the process is gracefully aborting. you did that 😭 it's leaving politely.
    • <blockidx> — current block index position (uint).
    • <msg> — text message exactly as it's printed on screen.
  • msg:<level>:<msg> — messages printed to the screen. the general chatter 💬
    • <level> — one of fatal, fatal_hardware, error, error_hardware, expected, status, progress or verbose.
      • fatal, fatal_hardware — a fatal error occurred. program will abort after this message. the hardware one means that the problem was caused by a hardware failure, like an Input/Output error or a silent data error. this is the bad one, bestie, it's over 😭
      • error, error_hardware — a generic error condition that doesn't prevent the program to continue. the hardware one means that the problem was caused by a hardware failure, like an Input/Output error or a silent data error.
      • expected — an expected error condition. at present it happens only when using the -m option with files expected missing.
      • status — a status message, usually providing context or a summary.
      • progress — a progress message, often part of an ongoing operation.
      • verbose — a verbose informative message, only shown in verbose mode.
    • <msg> — text message exactly as it's printed on screen.

🔥 THERMAL TAGS 🔥

okay bestie, these tags come from the thermal monitoring functions — so whenever SnapRAID is out here processing, usually during stuff that touches the disks, you'll see these pop up. it's giving "my laptop is a space heater" energy fr fr 🥵

  • thermal:ambient:device:<hwmon_dir>:<name>:<temp_file>:<label>:<temp> — logs a temperature reading it found on the system using the Linux /sys/class/hwmon interface. heads up, this one is Linux-only. ✨
    • <hwmon_dir> — the hwmon directory name (like hwmon0).
    • <name> — the name of the hwmon device (like k10temp).
    • <temp_file> — the temperature file name (like temp1_input).
    • <label> — the label tied to that temperature sensor (like Tdie).
    • <temp> — the temperature reading in degrees Celsius.
  • thermal:ambient:candidate:<temp> — reports a temperature reading that's a candidate for the ambient temperature, used in the heating model calculation.
    • <temp> — the candidate temperature in degrees Celsius.
  • thermal:system:candidate:<temp> — logs a temperature reading from a connected disk that's being considered as a candidate for figuring out the ambient system temperature.
    • <temp> — the current temperature read from the disk (uint, degrees Celsius).
  • thermal:system:final:<temp> — logs the FINAL ambient system temperature it calculated. this value is the lowest valid temperature seen among all the candidates, so it represents the room temp. 💅
    • <temp> — the calculated ambient temperature in degrees Celsius.
  • thermal:current:<disk_name>[/<split_index>]:<device>:<temp> — logs the most recent temperature reading for a specific disk device.
    • <disk_name>[/<split_index>] — the configured name of the disk. for split parity, the parity name gets followed by /N to show the split index, where N starts from 0. and the /0 is always omitted. no cap.
    • <device> — the unique device ID (uint).
    • <temp> — the current temperature read from the disk in degrees Celsius.
  • thermal:highest:<temp> — logs the highest temperature seen among all the monitored disks in the current measurement cycle. this one is used for thermal throttling.
    • <temp> — the highest temperature observed in degrees Celsius.
  • thermal:heat:<disk_name>[/<split_index>]:<device>:<count>:<data_points> — logs the ENTIRE history of temperature data points collected so far for a specific disk, used for fitting the heating model. only monotone increasing temperatures make it into the history, so don't expect the dips. 🦋
    • <device> — the unique device ID (uint).
    • <count> — the total number of collected data points (uint).
    • <data_points> — a comma-separated list of temperature/time pairs. each pair is formatted as <temp>/<time_offset>.
    • <temp> — temperature reading in degrees Celsius.
    • <time_offset> — time offset from the start of the thermal monitoring (uint, seconds).
  • thermal:params:<disk_name>[/<split_index>]:<device>:<k_heat>:<t_ambient>:<t_steady>:<rmse>:<r_squared>:<max_error> — logs the estimated parameters for the exponential heating model (fit using least squares) plus the associated quality metrics for a specific disk. the model is:
T(t) = T_steady - (T_steady - T_0) e^(-kt)

where T_0 is the initial temperature.

  • <device> — the unique device ID (uint).
  • <k_heat> — the heating rate constant, k (float).
  • <t_ambient> — the ambient temperature, T_ambient (float).
  • <t_steady> — the estimated steady-state temperature, T_steady (float), which is the maximum expected temperature of the disk.
  • <rmse> — Root Mean Square Error of the fit (float).
  • <r_squared> — Coefficient of determination (R^2) of the fit (float).
  • <max_error> — Maximum absolute error of the fit (float).
  • thermal:spindown — indicates that the thermal alarm limit has been reached, and the process is initiating a disk spindown to begin the cooldown procedure. literally preventing overheating, we love a protective king. 🫶
  • thermal:cooldown:<sleep_time> — indicates how long the cooldown waiting period after spindown is.
    • <sleep_time> — the total time the system will wait for cooldown (uint, seconds).
  • thermal:spinup — indicates that the cooldown period is done and the disks are being spun back up to resume the operation. nap's over bestie, back to work. 😭

📋 COMMAND STATUS TAGS 📋

this section describes the tags output with the status command. so like, the vibes report of ur whole array. 💖

✨ Summary Tags ✨

these give general info about the array configuration and the overall state. the big picture, if u will.

  • summary:block_size:<uint> — the size of a block in bytes. this is the unit of parity protection.
  • summary:parity_block_count:<uint> — the total number of blocks allocated for ALL parity levels combined.
  • summary:parity_block_total:<name>:<uint> — total blocks available for a specific parity level (like parity, 2-parity).
  • summary:parity_block_free:<name>:<uint> — free blocks available for a specific parity level.
  • summary:parity_block_free_min:<uint> — the minimum number of free blocks across all parity levels. this determines the maximum size of data that can be added, so it's kind of a big deal. 👑
  • summary:file_count:<uint> — total number of files in the array.
  • summary:file_block_count:<uint> — total number of data blocks used by files.
  • summary:fragmented_file_count:<uint> — total number of fragmented files, meaning files whose blocks are NOT contiguous. messy. 💀
  • summary:excess_fragment_count:<uint> — total number of excess fragments (that's one less than the total fragments). it's a measure of data fragmentation overhead.
  • summary:zerosubsecond_file_count:<uint> — total number of files with a zero sub-second timestamp. this can happen on certain filesystems and may affect change detection. noted. 🍓
  • summary:file_size:<uint> — total size of all files in bytes.
  • summary:parity_size:<uint> — total size of allocated parity blocks in bytes.
  • summary:parity_size_max:<uint> — maximum possible parity size (allocated + min free) in bytes. this is the effective maximum protection size.
  • summary:hash:<name> — the current hash algorithm in use (like sha256).
  • summary:prev_hash:<name> — the previous hash algorithm used, if a rehash is in progress.
  • summary:best_hash:<name> — the best hash algorithm for optimal performance based on system capabilities. the algorithm that ate. ✨
  • summary:total_wasted:<uint> — total wasted space (space on data disks exceeding parity capacity) in bytes.
  • summary:total_used:<uint> — total used space by data files in bytes.
  • summary:total_free:<uint> — total free space (usable by data) in bytes, limited by parity capacity.
  • summary:total_use_percent:<uint> — overall array use percentage.
  • summary:scrub_oldest_days:<uint> — days ago the oldest block was last scrubbed.
  • summary:scrub_median_days:<uint> — days ago the median block was last scrubbed.
  • summary:scrub_newest_days:<uint> — days ago the newest block was last scrubbed.
  • summary:exit:<status> — logs the overall exit status of the command. the status is one of these:
    • ok — no issues. the array is fully synchronized and healthy. we love to see it. 💖
    • bad — the array has some blocks marked as bad. it needs a -e fix and and a -p bad scrub operation. (yeah the original says "and and", iconic typo, we respect it 🎀)
    • unsynced — the array has an interrupted sync. it needs another sync operation.

🖥️ Per-Disk Tags 🖥️

these give stats for individual data disks. <name> is the disk name. one disk at a time, main character energy only.

  • summary:disk_file_count:<name>:<uint> — number of files on the disk.
  • summary:disk_block_count:<name>:<uint> — number of blocks used by files on the disk.
  • summary:disk_fragmented_file_count:<name>:<uint> — number of fragmented files on the disk.
  • summary:disk_excess_fragment_count:<name>:<uint> — number of excess fragments on the disk.
  • summary:disk_zerosubsecond_file_count:<name>:<uint> — number of files with zero sub-second timestamp on the disk.
  • summary:disk_file_size:<name>:<uint> — total size of files on the disk in bytes.
  • summary:disk_block_allocated:<name>:<uint> — highest block index used on the disk + 1.
  • summary:disk_block_total:<name>:<uint> — total blocks on the disk (physical size).
  • summary:disk_block_free:<name>:<uint> — free blocks on the disk.
  • summary:disk_block_max_by_space:<name>:<uint> — total blocks by disk space (used + free blocks), representing the physical limit of the disk.
  • summary:disk_block_max_by_parity:<name>:<uint> — total blocks limited by parity space (parity size + min parity free blocks). this is the logical limit imposed by the parity files.
  • summary:disk_block_max:<name>:<uint> — maximum usable blocks (that's the minimum of ..._by_space and ..._by_parity).
  • summary:disk_space_wasted:<name>:<int> — wasted space on the disk in bytes (positive if the disk is larger than usable parity space).
  • summary:disk_used:<name>:<uint> — used space on the disk in bytes.
  • summary:disk_free:<name>:<uint> — free usable space on the disk in bytes, limited by disk_block_max.
  • summary:disk_use_percent:<name>:<uint> — disk use percentage relative to disk_block_max.

🕰️ File Timestamp Tags 🕰️

these list files with zero sub-second timestamps. the little weirdos.

  • zerosubsecond:<disk_name>:<file_path> — lists files that have a zero sub-second timestamp. up to 50 are logged per disk.

📈 Scrub Graph Tags 📈

these give u a simple graph's worth of data about past scrub and sync operations. data visualization but make it text. 🌈

  • scrub_graph_range:<max_columns>:<max_height> — the dimensions of the scrub history graph, obtained from the content_info:bucket records. this gives u the boundary for the precomputed graph data available in the scrub_graph_bar tags.
    • <max_columns> — the number of columns in the graph.
    • <max_height> — the maximum height (peak count) of blocks found in any column (the highest sum of scrubbed and new blocks).
  • scrub_graph_bar:<index>:<days_ago>:<scrubbed>:<new> — data for a single column of the scrub history graph. each column represents a time period.
    • <index> — column index. from 0 to max_columns - 1.
    • <days_ago> — days ago for this column´s time range.
    • <scrubbed> — count of scrubbed blocks in that day range.
    • <new> — count of newly synced (unscrubbed) blocks in that day range.

💅 COMMAND SYNC/SCRUB TAGS 💅

okay so these are the tags that only show up for the sync and scrub commands. also, bestie, the error tags can pop up here too, so keep an eye out. 👀

🎀 Summary Tags 🎀

these ones give you the lil stats recap at the very end of the command. the receipts, if you will. 💖

  • hash_summary:error_soft:<count> — logs the total count of file-related errors that made a block get skipped during the hashing phase. these are usually from files changing (going missing, or size/time changing) mid-sync. heads up: this only happens in sync. ✨
    • <count> — total number of file errors (uint).
  • summary:error_soft:<count> — logs the total count of file-related errors that came up during the whole process (think missing files, file attribute changes, that whole vibe). 😭
    • <count> — the total number of file errors encountered (uint).
  • summary:error_io:<count> — logs the total count of input/output errors hit on data or parity disks. not the vibe fr.
    • <count> — the total number of I/O errors encountered (uint).
  • summary:error_data:<count> — logs the total count of silent data errors (aka data blocks not matching their expected hash) that showed up during the sync process. 💀
    • <count> — the total number of silent data errors encountered (uint).
  • summary:exit:<status> — logs the overall exit status of the command. the status is one of these:
    • ok — no issues. the array is fully synchronized and healthy. periodt. 👑
    • warning — some files were skipped because they were probably intentionally modified. no hardware risk.
    • error — critical failure. this is giving serious issues like I/O failures or silent data corruption. requires immediate hardware or filesystem inspection, bestie, do not ignore this. 🚨

🌸 COMMAND CHECK/FIX TAGS 🌸

these are specific to the check and fix commands. for audit mode, it´s inteded check with the --audit-only option. (yes bestie, we're keeping that typo, it's canon now 💀). also the error tags are possible here too.

✨ Fixed/Recovered Tags ✨

these ones log successful repairs during fix operations. healing era. 🫶

  • fixed:<block_pos>:<disk_name>:<file_path>:<msg> — says a file got successfully fixed using parity data. slay.
    • <block_pos> — the block position being processed (uint).
    • <disk_name> — the name of the disk.
    • <file_path> — the file path relative to disk root (escaped).
    • <msg> — a descriptive message saying what kind of fix it was (e.g., Fixed size, Fixed data error at position...).
  • parity_fixed:<block_pos>:<parity>:<msg> — says corrupted parity data got successfully recomputed and written. iconic.
    • <block_pos> — the block position being processed (uint).
    • <parity> — the name of the parity level (e.g., parity, 2-parity).
    • <msg> — a descriptive message saying what kind of fix it was (e.g., Fixed data error).
  • empty_fixed:<disk_name>:<file_path>:<msg> — logs the successful recreation of a missing or corrupted empty file.
    • <disk_name> — the name of the disk.
    • <file_path> — the file path relative to disk root (escaped).
    • <msg> — a descriptive message saying what kind of fix it was (e.g., Fixed empty file).
  • hardlink_fixed:<disk_name>:<link_path>:<msg> — logs the successful recreation of a hard link during a fix operation.
    • <disk_name> — the name of the disk.
    • <link_path> — the hard link path relative to disk root (escaped).
    • <msg> — a descriptive message saying what kind of fix it was (e.g., Fixed hardlink error).
  • symlink_fixed:<disk_name>:<link_path>:<msg> — logs the successful recreation of a symbolic link during a fix operation.
    • <disk_name> — the name of the disk.
    • <link_path> — the symlink path relative to disk root (escaped).
    • <msg> — a descriptive message saying what kind of fix it was (e.g., Fixed symlink error).
  • dir_fixed:<disk_name>:<dir_path>:<msg> — logs the successful recreation of a missing directory during a fix operation.
    • <disk_name> — the name of the disk.
    • <dir_path> — the directory path relative to disk root (escaped).
    • <msg> — a descriptive message saying what kind of fix it was (e.g., Fixed dir error).

💀 Unrecoverable Error Tags 💀

these log errors that could NOT be recovered. sad girl hours. 😭

  • unrecoverable:<block_pos>:<disk_name>:<file_path>:<msg> — says a block error couldn't be fixed because of insufficient parity or other recovery limitations. rip.
    • <block_pos> — the block position being processed (uint).
    • <disk_name> — the name of the disk.
    • <file_path> — the file path relative to disk root (escaped).
    • <msg> — a descriptive message saying what the problem was (e.g., Unrecoverable error at position <file_pos>, Unrecoverable unsynced error at position <file_pos>).
  • collision:<disk_name>:<file_path>:<collision_path>:<msg> — logs that the modification time was NOT set on a recovered file, to avoid an inode collision with another file.
    • <disk_name> — the name of the disk.
    • <file_path> — the file path relative to disk root (escaped).
    • <collision_path> — the path of the colliding file (escaped).
    • <msg> — a descriptive message saying what the problem was (e.g., Not setting modification time to avoid inode collision).

🦋 File Status Tags 🦋

these log the final status of files after processing. the glow-up report, basically. ✨

  • status:unrecoverable:<disk_name>:<file_path> — says a file has unrecoverable errors and got renamed to .unrecoverable (fix) or just can't be recovered at all (check).
    • <disk_name> — the name of the disk.
    • <file_path> — the file path relative to disk root (escaped).
  • status:recovered:<disk_name>:<file_path> — logs that a file got successfully recovered during a fix operation. we love to see it. 💖
    • <disk_name> — the name of the disk.
    • <file_path> — the file path relative to disk root (escaped).
  • status:recoverable:<disk_name>:<file_path> — logs that a file has errors but could be recovered with a fix (check).
    • <disk_name> — the name of the disk.
    • <file_path> — the file path relative to disk root (escaped).
  • status:correct:<disk_name>:<file_path> — says a file passed all checks successfully (verbose). ate, no crumbs. 💅
    • <disk_name> — the name of the disk.
    • <file_path> — the file path relative to disk root (escaped).

💜 Summary Tags 💜

yep, another set of summary tags — these give you the stats recap at the end of the command.

  • summary:error_soft:<count> — logs the total count of file-related errors that came up during the process (e.g., missing files, file attribute changes).
    • <count> — the total number of file errors encountered (uint).
  • summary:error_io:<count> — logs the total count of input/output errors hit on data or parity disks.
    • <count> — the total number of I/O errors encountered (uint).
  • summary:error_data:<count> — logs the total count of silent data errors (data blocks not matching their expected hash) that showed up during the sync process.
    • <count> — the total number of silent data errors encountered (uint).
  • summary:error_recovered:<recovered_count> — logs the total number of errors successfully recovered (fix). 🎉
    • <recovered_count> — number of recovered errors (uint).
  • summary:error_recoverable:<recoverable_count> — logs the total number of errors that CAN be recovered (check).
    • <recoverable_count> — number of recoverable errors (uint).
  • summary:error_unrecoverable:<unrecoverable_count> — logs the total number of unrecoverable errors (fix/check).
    • <unrecoverable_count> — number of unrecoverable errors (uint).
  • summary:exit:<status> — logs the overall exit status of the command. the status is one of these:
    • ok — says the operation completed with no errors (audit).
    • warning — some files were different than expected, probably from intentional modification of the files. no hardware risk (audit).
    • error — critical failure. this is giving serious issues like I/O failures or silent data corruption. requires immediate hardware or filesystem inspection (audit). 🚨
    • recovered — says the operation completed with ALL errors successfully recovered (fix). 👑
    • recoverable — says errors were found but they're all recoverable (check).
    • unrecoverable — says unrecoverable errors were found (check/fix). 💀

🌈 COMMAND LIST TAGS 🌈

this section describes the tags that get output with the list command.

🍓 List Tags 🍓

these log the deets about individual files and links processed during the listing operation.

  • file:<disk_name>:<subpath>:<size>:<mtime_sec>:<mtime_nsec>:<inode> — logs the details for a regular file found on a disk.
    • <disk_name> — the configured name of the disk.
    • <subpath> — the path of the file relative to the disk´s root (escaped).
    • <size> — the size of the file in bytes (uint).
    • <mtime_sec> — the file´s modification time in seconds since the Epoch (int).
    • <mtime_nsec> — the file´s modification time nanosecond component (uint).
    • <inode> — the file´s inode number (uint).
  • link_<type>:<disk_name>:<subpath>:<linkto> — logs the details for a link found on a disk. the <type> component changes depending on what kind of link it is.
    • <type> — the type of link, one of: hardlink, symlink, symdir (symlink to a directory), junction (Windows-specific reparse point).
    • <disk_name> — the configured name of the disk (string).
    • <subpath> — the path of the link relative to the disk´s root (escaped).
    • <linkto> — the target path of the link (escaped).

⭐ Summary Tags ⭐

these log the final stats about the entire listing operation.

  • summary:file_count:<count> — logs the total number of regular files processed.
    • <count> — the total number of files (uint).
  • summary:file_size:<size> — logs the total size of all the regular files processed.
    • <size> — the cumulative size of all files (uint, bytes).
  • summary:link_count:<count> — logs the total number of links processed (hardlinks, symlinks, symdirs, junctions).
    • <count> — the total number of links (uint).
  • summary:exit:ok — says the listing operation completed successfully. quick note bestie: if a fatal error happens, the program will abort, and you won´t get this tag at all. 💔

🍓 COMMAND DUP TAGS 🍓

okay bestie, this whole section is the tag glow-up you get when you run the dup command. let's go 💖

Duplicate Tags ✨

these tags spill the tea about duplicate files that got caught, and then give you the lil recap of the whole dupe hunt. important: duplicates are decided by the content hash of the whole file. no cap. 💅

  • dup:<diskname1>:<file_path1>:<diskname2>:<file_path2>:<size>: dup — logs the deets on a pair of duplicate files that got found. the first file listed is the one that just got processed, and the second one is the previously processed file rockin' the exact same content hash.
    • <diskname1> — the configured name of the disk holding the freshly processed duplicate file.
    • <file_path1> — the path of that newly processed duplicate, relative to its disk's mount point (escaped).
    • <diskname2> — the configured name of the disk holding the previously processed file that's the dupe of <file_path1>.
    • <file_path2> — the path of that previously processed duplicate file, relative to its disk's mount point (escaped).
    • <size> — the size of the duplicate file in bytes (uint). this size corresponds to the file <file_path2>.

Summary Tags 🌸

the final word on the dupe-finding saga. periodt.

  • summary:dup_count:<count> — logs the total number of duplicate files found. a file counts as a duplicate if its hash matches a hash already seen. 👀
    • <count> — the total count of duplicate files (uint).
  • summary:dup_size:<size> — logs the total size of all the duplicate files found. it's the sum of the sizes of every file considered a duplicate.
    • <size> — the total size of duplicate files in gigabytes (uint).
  • summary:exit:<status> — logs the overall exit status of the command. status is one of these:
    • unique — means no duplicate files were found.
    • dup — means at least one duplicate file was found.

🫶 COMMAND POOL TAGS 🫶

this bit covers the tags that come out of the pool command.

  • summary:link_count:<count> — logs the total number of links created (symlinks, junctions).
    • <count> — the total number of links (uint).
  • summary:exit:ok — means the pool operation wrapped up successfully. 🎀 quick note tho: if a fatal error happens, the program just aborts, and you won't get this tag at all.

🌈 COMMAND REHASH TAGS 🌈

these are the tags you get from the rehash command.

Summary Tags 💜

the final recap of the rehash scheduling process.

  • summary:exit:<status> — logs the overall exit status of the command. status is one of these:
    • scheduled — a rehash operation got scheduled successfully ✨. the rehash will be performed incrementally in future sync or scrub commands.
    • already_in_progress — a rehash is already happening and can't be scheduled again. this makes the program exit with a fatal error. 😭
    • not_required — the current hash algorithm is already the best hash for the platform, so no rehash is needed. this also makes the program exit with a fatal error.

👑 COMMAND SMART AND PROBE TAGS 👑

this section is about the tags output by the smart and probe commands. the main difference between the two? probe doesn't spin up the disk, so it won't be able to get all the attributes if the disk is spun down. the smart command, on the other hand, will always get all the attributes — but with the risk of spinning up all the disks. pick your vibe wisely bestie 💀

heads up: a <disk_name> may be associated with more than one <device_file>, in case the logical disk uses more physical disks. when that happens, you'll see multiple <attr> and <smart> tags for the same <disk_name>, but with different <device_file>. the exception is the stat attribute, which is cumulative across all the devices that are part of the disk. 🦋

also, in case of split parity, the parity name is followed by /N to indicate the split index, where N starts from 0. and the /0 is always omitted. ✨

Attributes ⭐

tags that log specific disk identification and attribute values.

  • smart:<device_file>:<disk_name>[/<split_index>] — logs the start of the SMART report for a device.
    • <device_file> — the file path of the device (e.g., /dev/sdb).
    • <disk_name>[/<split_index>] — the configured name of the disk. in case of split parity, the parity name is followed by /N to indicate the split index, where N starts from 0. the /0 is always omitted.
  • attr:<device_file>:<disk_name>[/<split_index>]:serial:<serial_number> — logs the disk's serial number.
    • <serial_number> — the disk's serial number (escaped).
  • attr:<device_file>:<disk_name>[/<split_index>]:family:<family> — logs the disk's model family string.
    • <family> — the disk's model family identifier (escaped).
  • attr:<device_file>:<disk_name>[/<split_index>]:model:<model> — logs the disk's model string.
    • <model> — the disk's model identifier (escaped).
  • attr:<device_file>:<disk_name>[/<split_index>]:interface:<interface> — logs the disk's interface. something like USB, SATA, NVMe.
    • <interface> — the disk's interface (escaped).
  • attr:<device_file>:<disk_name>[/<split_index>]:afr:<afr>:<prob> — logs the estimated Annual Failure Rate (AFR) and the probability of at least one failure in the next year, all based on SMART attributes. the AFR is calculated using the SMART attributes (5, 187, 188, 197, 198).
    • <afr> — the computed Annual Failure Rate (the average number of failures you expect in a year) (float).
    • <prob> — the probability of at least one failure in the next year (float).
  • attr:<device_file>:<disk_name>[/<split_index>]:size:<size_bytes> — logs the size of the disk.
    • <size_bytes> — the disk size in bytes (uint).
  • attr:<device_file>:<disk_name>[/<split_index>]:error_protocol:<error_count> — counts command, transport, or controller-level errors reported by the device. these reflect failed I/O operations that weren't directly caused by media defects (so like interface, firmware, or power-related errors). this counter is cumulative and never resets to zero, even if the underlying error condition gets resolved. 💀
    • <error_count> — the total error count (uint).
  • attr:<device_file>:<disk_name>[/<split_index>]:error_medium:<error_count> — counts media-level errors where data couldn't be reliably read or written. these indicate actual storage surface or flash failures and may imply data loss. this counter is cumulative and never resets to zero, even if the underlying error condition gets resolved.
    • <error_count> — the total error count (uint).
  • attr:<device_file>:<disk_name>[/<split_index>]:wear_level:<percentage> — the wear level of the SSD/NVME, expressed as a percentage. a value of 0 means a brand new drive with zero wear, and 100 means the drive has hit or blown past its manufacturer-rated design life. this metric is a normalized unsigned integer, giving you one consistent health indicator across all sorts of SSD/NVME vendors and interface types by mapping all those chaotic hardware counters onto a single standardized scale. iconic tbh 🎀
    • <percentage> — wear level percentage (uint).
  • attr:<device_file>:<disk_name>[/<split_index>]:rotationrate:<rate> — logs the disk's rotation rate.
    • <rate> — the rotation rate. a value of 0 means a solid-state drive (SSD) or other non-rotating medium. a value of 1 means a rotational disk of unknown precise speed. values greater than 1 mean the rotational speed in RPM.
  • attr:<device_file>:<disk_name>[/<split_index>]:flags:<flags_decimal>:<flags_hex> — logs the SMART status flags from the smartctl utility. per the smartctl manpage, these flags are bit-mapped to flag specific issues like Command line did not parse, Device could not be opened, or SMART status check returned ´DISK FAILING´.
    • <flags_decimal> — the raw flags value (uint, decimal).
    • <flags_hex> — the raw flags value (uint, hexadecimal).
  • attr:<device_file>:<disk_name>[/<split_index>]:<id>:<raw_decimal>:<raw_hex>:<norm>:<worst>:<thresh>:<name>:<type>:<updated>:<when_failed> — logs the raw value of any assigned SMART attribute.
    • <id> — the SMART attribute ID (uint).
    • <raw_decimal> — the raw attribute value (uint, decimal).
    • <raw_hex> — the raw attribute value (uint, hexadecimal).
    • <norm> — the normalized value (uint).
    • <worst> — the worst value (uint).
    • <thresh> — the threshold value (uint).
    • <name> — name of the attribute.
    • <type> — type of the attribute: prefail or oldage.
    • <updated> — update method of the attribute: always or offline.
    • <when_failed> — if and when the attribute failed: never or past or now.
  • attr:<device_file>:<disk_name>[/<split_index>]:power:active — logs that the device was confirmed to be in an active power state after a status probe.
  • attr:<device_file>:<disk_name>[/<split_index>]:power:standby — logs that the device was confirmed to be in a standby/spun-down state.
  • attr:<device_file>:<disk_name>[/<split_index>]:power:up — logs a successful spin-up operation via direct O_DIRECT read.
  • attr:<device_file>:<disk_name>[/<split_index>]:power:down — logs a successful spin-down operation initiated via the smartctl command.
  • stat:<disk_name>:<access_number> — logs the total number of read and write accesses done on the disk. this is a cumulative value that includes all the devices and splits of the disk. compare this number at different times and you can detect if the disk was used during that window. 👀
    • <access_number> — total number of accesses (uint).

Summary 🌈

tags that log the overall failure probabilities for the whole array.

  • summary:array_failure:<array_afr>:<array_prob> — logs the total estimated failure rate for the entire array (the sum of the individual disk AFRs) plus the probability of at least one failure in the next year.
    • <array_afr> — the sum of AFRs of all disks in the array (the average number of failures you expect in a year) (float).
    • <array_prob> — the probability of at least one failure in the next year (float).

💾 DEVICE STATUS TAGS 💾

okay so these tags are literally the life story of hardware hangouts and external command runs with smartctl. they log the whole lifecycle, bestie. 🫶

  • device:<device_file>:<disk_name>[/<split_index>]:shell — logs a failure in the command shell execution environment. not the vibe. 💀
    • <device_file> — the system path to the device node.
    • <disk_name>[/<split_index>] — the configured name of the disk. if there's split parity, the parity name gets a /N after it to show the split index, where N starts from 0. the /0 is always omitted.
  • device:<device_file>:<disk_name>[/<split_index>]:error:<errno> — logs a low-level system error during direct file operations. this pops off when open(), read(), or close() calls fail during a spin-up attempt. 😭
    • <errno> — the standard integer error number provided by the OS.
  • device:<device_file>:<disk_name>[/<split_index>]:error:abort — logs that an external process (smartctl) failed to complete normally, like being terminated by a signal instead of exiting. rude. 🙈
  • device:<device_file>:<disk_name>[/<split_index>]:exit:<exit_code> — logs that the external command (smartctl) returned a non-zero exit code that wasn't explicitly recognized as a valid state.
    • <exit_code> — the integer exit status returned by the process (int).

🚨 ERROR TAGS 🚨

these tags report specific errors that happen on data disks during the commands that access files and parities. it's giving "something went wrong and we need to talk about it." 🔥

  • error[_io|_data]:<block>:<disk_name>:<file>:<msg> — logs file access errors (open, read, file changed) during the data disk read operation for parity calculation or verification.
    • _io — indicates a physical Input/Output error. the disk was unable to read or write a specific block, typically signaling a failing sector or cable issue. 💀
    • _data — indicates the data was read successfully but failed the checksum/hash verification. this signals silent corruption or an unsuccessful parity match. not slay.
    • <block> — the zero-based index of the block where the error occurred (uint).
    • <disk_name> — the name of the data disk.
    • <file> — the path (relative to the disk mount point) of the file containing the block (escaped).
    • <msg> — a descriptive message indicating the nature of the error (e.g., Open/Read/Write error, Data error at position <pos>, diff bits <diff>/<bits>).
  • parity_error[_io|_data]:<block>:<level>:<msg> — logs errors during parity disk read or write operations.
    • _io — indicates a physical Input/Output error. the disk was unable to read or write a specific block, typically signaling a failing sector or cable issue.
    • _data — indicates the data was read successfully but failed the checksum/hash verification. this signals silent corruption or an unsuccessful parity match.
    • <block> — the zero-based index of the block where the error occurred (uint).
    • <level> — the configuration name of the parity level (e.g., parity, 2-parity).
    • <msg> — a descriptive message indicating the nature of the error (e.g., Read/Write error, Data error, diff bits <diff>/<bits>).
  • hardlink_error[_io]:<disk_name>:<link_path>:<target_path>:<msg> — indicates an error when attempting to access a hard link. 💅
    • <disk_name> — the name of the disk.
    • <link_path> — the hard link path relative to disk root (escaped).
    • <target_path> — the target path of the hard link (escaped).
    • <msg> — a descriptive message indicating the nature of the error (e.g., Hardlink stat error, Hardlink error for not regular file, Hardlink to stat error, Hardlink-to error for not regular file, Hardlink mismatch for different inode).
  • symlink_error[_io]:<disk_name>:<link_path>:<msg> — indicates an error when attempting to access a symbolic link. 🦋
    • <disk_name> — the name of the disk.
    • <link_path> — the symlink path relative to disk root (escaped).
    • <msg> — a descriptive message indicating the nature of the error (e.g., Symlink read error, Symlink data error ´<actual>´ instead of ´<expected>´).
  • dir_error[_io]:<disk_name>:<dir_path>:<msg> — indicates an error when attempting to access a directory. 🎀
    • <disk_name> — the name of the disk.
    • <dir_path> — the directory path relative to disk root (escaped).
    • <msg> — a descriptive message indicating the nature of the error (e.g., Dir stat error, Dir error for not directory).
  • outofparity:<disk_name>:<file_path> — logs that a file´s blocks extend beyond the available parity space, indicating that the parity files are too small to protect all data. this happens when data requires more parity than is available on the parity disk(s) and is a critical warning. 🚨
    • <disk_name> — the name of the disk containing the file.
    • <file_path> — the file path relative to the disk root (escaped).
bestie, if you see outofparity, drop everything and fix your parity setup. no cap. 🙏

and that's a wrap on this section, bestie! you made it through all the tags like a total icon. 👑 this was SnapRAID Log Format(1) — source and version right there in the footer, dated whenever the manpage gods stamped it. stay logged, stay slay. 💖✨

📦 where this page comes from