flexi_config

Rust crate to provide a configuration file for flexi_logger

lib.rs:

This crate allows programs to configure flexi_logger from a configuration file. To do this you would first create the configuration file. This can be done dynamically by reading the the Cargo.toml. The following code shows creating a log.toml file from the Cargo.toml file:

use flexi_config::FlexiConfig;

// Read the Cargo.toml file for the project
let mut config = FlexiConfig::from_cargo_file("Cargo.toml").unwrap();

// Change the default directory to "logs" for the log files
config.disk_dir = Some(String::from("logs"));

// Create a config file named log.toml
config.to_toml_file("log.toml").unwrap();

Then when your program runs for real, you would load the configuration file and initialize flexi_logger with it. The following code is an example of doing that:

use flexi_config::{FlexiConfig, Target};

// Load the log.toml configuration file
let mut config = FlexiConfig::from_toml_file("log.toml").unwrap();

// Force the logging to a file instead of stderr (ignoring the config file settings).
// Then applies the configuration to flexi_logger.
config.target(Target::Disk).apply();

Configuration File

If you want to modify the configuration, this can either be done programatically by call calling the various methods and accessing the fields of the structure. Or you could hand edit the config file.

The configuration file is broken into 3 sections, [common], [disk], and [depends].

[common]

This section handles the general settings for configuring flexi_logger.

application

This value shouldn't be changed. This must match the internal name for the application which is the "name" property defined in the Cargo.toml file for the application.

disk_format & stderr_format

These settings define the format of the log messages when logging to disk or stderr. There are three predefined formats, these formats are actually defined by flexi_logger.

• "default" - This will use the flexi_logger::default_format function to format the log message. More information can be found here.
• "detailed" - This will use the flexi_logger::detailed_format function to format the log message. More information can be found here.
• "opt" - This will use the flexi_logger::opt_format function to format the log message. More information can be found here.

In addition you can define a custom format for the log messages. The custom format is defined however you want with special control codes inserted between '{' and '}' characters. The following codes are supported:

• f - Inserts the name of the source file that generated the log message.
• p - Inserts the priority (error, warning, info, debug, trace) as a single lower case character. 'e' for error, 'w' for warning, 'i' for info, 'd' for debug, and 't' for trace.
• P - Same as p, but uses uppercase characters.
• pp - Inserts the priority (error, warning, info, debug, trace) as a 5 character word in lower case. 'error' for error, 'warn' for warning, 'info' for info, 'debug' for debug, and 'trace' for trace. 'warn' and 'info' will have a space appended so they are 5 characters.
• PP - Same as pp, but uses uppercase characters.
• l - Inserts the line number of the log message in the source file.
• m - Inserts the module the file belongs to.
• c - Inserts the crate the file belongs to.
• t - Inserts the current time.
• e - Inserts the event or the actual log message.

So a custom format could be like: "{PP} | {c} | {f}:{l} | {e}" which would output the priority followed by the crate then the file with line number, and finally the log message. If you want to output an curly bracked you would need to escape it with a backslash, like "\{ {e} \}".

Additionally when displaying 'f', 'l', 'm', 'c', or 'e' you can specify a width to perform left or right justification or truncation.

element :=  '{' type:[[align]width[trim]] '}'
align := '<' | '>'
width := integer
trim := '-' | ''

If you want to right justify the filename to 20 characters you would specify "{f:>20}". If the filename (with path) is shorter than 20 characters then spaces will be inserted before the name until the length is 20 characters. If you want to ensure the length doesn't go over 20 characters then you can add the trim.

"{c:>20-}" would output the crate, if the length is less than 20 characters then spaces will be prepended, if the length is longer then the last 20 characters of the crate name will be displayed. When trim is enabled if the element is right aligned the beginning of the value is trimmed, if it is left aligned the end of the string is trimmed.

Trim can also be applied without justifying so you could define: "{e:64-}" which would display up 64 characters of the log message then drop any remaining characters.

To output the time, you must specify it should be displayed. Inside the '{' and '}' characters you would add a colon (:) followed by the time format, i.e. "{t:<time format>}". The time format has it's own special codes:

• %b - Inserts the name of the month as 3 characters in lower case, i.e. jan, feb, mar.
• %B - Same as '%b' but uses uppercase characters.
• %d - Inserts the day of the month as two characters, so from 01 to 31.
• %f - Inserts the fractial seconds (milliseconds) as 3 digits, so from 000 to 999.
• %H - Inserts the hour of day in 24 hour format from 00 to 23.
• %I - Inserts the hour of the day in 12 hour format from 01 to 12.
• %m - Inserts the month in numeric format with 2 characters, so from 01 to 12.
• %M - Inserts the minutes in the hour as 2 digits, from 0 to 59.
• %p - Inserts 'am' or 'pm' based on the current time.
• %P - Same as %p but uses uppercase characters.
• %S - Inserts the seconds as 2 digits, so from 00 to 59.
• %y - Inserts the last 2 digits of the year, so from 00 to 99.
• %Y - Inserts the full 4 digits of the year.
• %% - Inserts a percent (%) sign.

You would use "{t:%d/%m/%Y %H:%M:%S.%f}" to display the time as day/month/year hour:minute/second.milliseconds.

Putting this all together the following format string would basically reproduce flexi_logger's detailed format:

[{t:%Y-%m-%d %H:%M:%S.%f}] {PP} [{m:32}] {f:32}:{l:>4}: {e}

priority

This defines the lowest priority message to log. Valid values for this are:

• trace - The lowest level log message.
• debug - Still low level but not as low as trace.
• info - Provides informational log messages, higher than trace and debug.
• warn - Warns of potential issues, this is the second highest log message.
• error - Highest level priority, reports error situations.

Target

Identifies where to log the messages to. This only has two values "stderr" or "disk".

[disk]

This section defines some settings that are only used when logging to disk.

dir

Identifies a directory to write the log files to. This value can also be false if you want the files to be created in the current directory.

dup_err

Flexi_logger can duplicate any "error" messages to both disk and stdout. If you like the "error" log messages also written to stdout, set this to "true".

dup_info

Flexi_logger can duplicate any "info" messages to both disk and stdout. If you like the "info" log messages also written to stdout, set this to "true".

extension

Provides the extension for the log files that are created. By default this is "log" but can be changed to suit your needs.

max_size

The default for this is "false" to indicate don't limit the log file sizes, just create a new file each day. If this is set, it specifies the number of megabytes the file can grow to before a new file should be created.

name_suffix

The default for this is "false". If you would like to add a custom suffix to the file name it can be specified with this parameter. This maps to the discriminant field of flexi_logger's LogConfig structure.

timestamp

This value controls if the timestamp is added to the file name when the file is created.

[depends]

This section defines the log priorities for any dependant crates for your application. If your application depends both on the "rand" and "time" crates, you could add:

[depends]
rand = "warn"
time = "trace"

To enable warning messages and higher from "rand" and enable all log messages from "time". The priorities are defined the same way as in the [common] section, so you have:

• trace - The lowest level log message.
• debug - Still low level but not as low as trace.
• info - Provides informational information, higher than trace and debug.
• warn - Warns of potential issues, this is the second highest log message.
• error - Highest level priority, reports error situations.