[−][src]Crate file_rotate
Write output to a file and rotate the files when limits have been exceeded.
Rotating by Lines
We can rotate log files by using the amount of lines as a limit.
use file_rotate::{FileRotate, RotationMode}; use std::{fs, io::Write}; fn main() { // Create a directory to store our logs, this is not strictly needed but shows how we can // arbitrary paths. fs::create_dir("my-log-directory-lines"); // Create a new log writer. The first argument is anything resembling a path. The // basename is used for naming the log files. // // Here we choose to limit logs by 10 lines, and have at most 2 rotated log files. This // makes the total amount of log files 4, since the original file is present as well as // file 0. let mut log = FileRotate::new("my-log-directory-lines/my-log-file", RotationMode::Lines(3), 2); // Write a bunch of lines writeln![log, "Line 1: Hello World!"]; for idx in 2..11 { writeln![log, "Line {}", idx]; } assert_eq!["Line 10\n", fs::read_to_string("my-log-directory-lines/my-log-file").unwrap()]; assert_eq!["Line 1: Hello World!\nLine 2\nLine 3\n", fs::read_to_string("my-log-directory-lines/my-log-file.0").unwrap()]; assert_eq!["Line 4\nLine 5\nLine 6\n", fs::read_to_string("my-log-directory-lines/my-log-file.1").unwrap()]; assert_eq!["Line 7\nLine 8\nLine 9\n", fs::read_to_string("my-log-directory-lines/my-log-file.2").unwrap()]; fs::remove_dir_all("my-log-directory-lines"); }
Rotating by Bytes
Another method of rotation is by bytes instead of lines.
use file_rotate::{FileRotate, RotationMode}; use std::{fs, io::Write}; fn main() { fs::create_dir("my-log-directory-bytes"); let mut log = FileRotate::new("my-log-directory-bytes/my-log-file", RotationMode::Bytes(5), 2); writeln![log, "Test file"]; assert_eq!["Test ", fs::read_to_string("my-log-directory-bytes/my-log-file.0").unwrap()]; assert_eq!["file\n", fs::read_to_string("my-log-directory-bytes/my-log-file").unwrap()]; fs::remove_dir_all("my-log-directory-bytes"); }
Rotation Method
The rotation method used is to always write to the base path, and then move the file to a new location when the limit is exceeded. The moving occurs in the sequence 0, 1, 2, n, 0, 1, 2...
Here's an example with 1 byte limits:
use file_rotate::{FileRotate, RotationMode}; use std::{fs, io::Write}; fn main() { fs::create_dir("my-log-directory-small"); let mut log = FileRotate::new("my-log-directory-small/my-log-file", RotationMode::Bytes(1), 3); write![log, "A"]; assert_eq!["A", fs::read_to_string("my-log-directory-small/my-log-file").unwrap()]; write![log, "B"]; assert_eq!["A", fs::read_to_string("my-log-directory-small/my-log-file.0").unwrap()]; assert_eq!["B", fs::read_to_string("my-log-directory-small/my-log-file").unwrap()]; write![log, "C"]; assert_eq!["A", fs::read_to_string("my-log-directory-small/my-log-file.0").unwrap()]; assert_eq!["B", fs::read_to_string("my-log-directory-small/my-log-file.1").unwrap()]; assert_eq!["C", fs::read_to_string("my-log-directory-small/my-log-file").unwrap()]; write![log, "D"]; assert_eq!["A", fs::read_to_string("my-log-directory-small/my-log-file.0").unwrap()]; assert_eq!["B", fs::read_to_string("my-log-directory-small/my-log-file.1").unwrap()]; assert_eq!["C", fs::read_to_string("my-log-directory-small/my-log-file.2").unwrap()]; assert_eq!["D", fs::read_to_string("my-log-directory-small/my-log-file").unwrap()]; write![log, "E"]; assert_eq!["A", fs::read_to_string("my-log-directory-small/my-log-file.0").unwrap()]; assert_eq!["B", fs::read_to_string("my-log-directory-small/my-log-file.1").unwrap()]; assert_eq!["C", fs::read_to_string("my-log-directory-small/my-log-file.2").unwrap()]; assert_eq!["D", fs::read_to_string("my-log-directory-small/my-log-file.3").unwrap()]; assert_eq!["E", fs::read_to_string("my-log-directory-small/my-log-file").unwrap()]; // Here we overwrite the 0 file since we're out of log files, restarting the sequencing write![log, "F"]; assert_eq!["E", fs::read_to_string("my-log-directory-small/my-log-file.0").unwrap()]; assert_eq!["B", fs::read_to_string("my-log-directory-small/my-log-file.1").unwrap()]; assert_eq!["C", fs::read_to_string("my-log-directory-small/my-log-file.2").unwrap()]; assert_eq!["D", fs::read_to_string("my-log-directory-small/my-log-file.3").unwrap()]; assert_eq!["F", fs::read_to_string("my-log-directory-small/my-log-file").unwrap()]; fs::remove_dir_all("my-log-directory-small"); }
Filesystem Errors
If the directory containing the logs is deleted or somehow made unaccessible then the rotator will simply continue operating without fault. When a rotation occurs, it attempts to open a file in the directory. If it can, it will just continue logging. If it can't then the written date is sent to the void.
This logger never panics.
Structs
FileRotate | The main writer used for rotating logs |
Enums
RotationMode | Condition on which a file is rotated |