Overview

Configuration of Chucho can be handled in two different ways: automatically or not-at-all. With automatic configuration, Chucho will go out and try to find the configuration file and make sense of it the first time a logger is requested. If this appeals to you, then you can tell Chucho what the name of your configuration file is using the chucho::configuration::set_file_name() function. If you don't want configuration to happen at all, then you must establish all the log settings yourself using the Chucho API.

Chucho's search for the configuration uses the following sequence:

If chucho::configuration::get_environment_variable() is not empty, then check the environment variable for the name of a valid configuration file. If chucho::configuration::set_environment_variable() has not been called, then the default value is CHUCHO_CONFIG. If the variable's value is the name of a valid configuration file, then we're done.
Check for a configuration file named by chucho::configuration::get_file_name(). The default file name is ./chucho.yaml. If chucho::configuration::get_file_name() is empty, then file configuration is disabled. If the named file is a valid configuration file, then we're done.
If chucho::configuration::set_fallback() has been called, then try to load the fallback configuration. If this configuration can be loaded, then we're done.
If chucho::configuration::allow_default() is true, which is the default, then load the default configuration. The default configuration sets one writer on the root logger that writes to stdout. Its formatter uses the pattern "%d{%H:%M:%S.%q} %-5p %.36c - %m%n".

So, a basic usage of Chucho might entail the following. You have a program like this.

#include <chucho/log.hpp>

int main()
{
    std::shared_ptr<chucho::logger> lgr = chucho::logger::get("my-log");
    CHUCHO_INFO_STR(lgr, "Hello, World!");
    return EXIT_SUCCESS;
}

And you have a file in the same directory as that program called chucho.yaml.

- chucho::logger:
    - name: my-log
    - chucho::cout_writer:
        - chucho::pattern_formatter:
            - pattern: '%p %c %m%n' # Quotes are needed to avoid YAML eating the % as directive indicators

When you execute the program, you will see.

INFO my-log Hello, World!

Configuration File Formats

Chucho supports three configuration file formats: YAML, config file, and log4cplus config file. By default only YAML is enabled in the build, but any or none of the three formats can be turned on.

Please refer to the Configuration Reference for information about which keys are supported in both YAML files and Chucho config files. Although the keys and types will be used differently depending on the format, the values are the same between the two formats.

YAML

It is a requirement that YAML Chucho configuration files are encoded with UTF-8.

Chucho configuration files can be in YAML format. Here is a simple example, which shows the default configuration that is used in the absence of a configuration file and only if chucho::configuration::allow_default() is true. Note that the name of the "root logger" is an empty piece of text.

- chucho::logger:
    - name: ''
    - chucho::cout_writer:
        - chucho::pattern_formatter:
            - pattern: '%d{%H:%M:%S.%q} %-5p %.36c - %m%n'

Chucho's interpretation of the YAML file is very generous. You may freely use sequences or mappings, but sequences are preferred, since using mappings alone can lead to unexpected behavior when more than one object of the same name is involved, as in the case of chucho::logger.

Variable Resolution

Variable resolution in the configuration file is performed. Variable references are indicated with "${<name>}" and "$ENV{<name>}". Non-environment variables must have already been declared in the configuration file using the top-level "variables" mapping. Here is an example.

- variables:
    MY_WRITER_TYPE: cout

- chucho::logger:
    - name: '$ENV{MY_LOG_NAME}' # Quotes are needed to avoid YAML eating the { and } as flow mapping
    - 'chucho::${MY_WRITER_TYPE}_writer':
        - chucho::pattern_formatter:
            - pattern: '%m%n'

You may place as many "variables" mappings as you wish, but just bear in mind that if you don't make the top-level collection a sequence, then only the last "variables" mapping encountered will be retained. This is a YAML feature, not a Chucho limitation. You are also free to use YAML's anchors-and-aliases mechanism for reuse of YAML-defined objects.

Config File

In order for Chucho to be able to read config file format files, it must be built with the CONFIG_FILE_CONFIG=ON parameter in CMake. The config file format used by Chucho is very similar to many other configuration file formats: any line that has some non-whitespace token followed by an equals sign is considered as a key-value pair. Here is a simple example

chucho.logger = my-log
chucho.logger.my-log.writer = stdout
chucho.writer.stdout = chucho::cout_writer
chucho.writer.stdout.formatter = pat
chucho.formatter.pat = chucho::pattern_formatter
chucho.formatter.pat.pattern = %p %c %m%n

One important difference between Java properties files and the Chucho config file format is that keys do not have to be unique in Chucho files. You may place as many instances of chucho.logger, or any other key, as you wish.

In addition to the keys that appear in the Configuration Reference, there are some special value that are used in Chucho config files to indicate types. In the above example, the key chucho.writer.stdout.formatter is used to name the formatter that will be used with the chucho::cout_writer. For writers, the types that can be specified include:

file_roll_trigger
file_roller
filter
formatter
writer

Each of these is used to name an instance of a type that is defined separately as in the example above. The type file_roller also can accept a named instance of a type:

file_compressor

Log4cplus Config File

Chucho can be built with the ability to read log4cplus configuration files by passing LOG4CPLUS_CONFIG=ON on the CMake command line. Support for log4cplus files is intended to aid in migration. So, if you already have code reading log4cplus configuration files, you may painlessly switch to Chucho without having to rewrite the configurations.

User-defined Types

User-defined types may appear in the configuration file. In order to create a type that you can configure, you have to do a few things. First, the type that will appear in the configuration file must inherit from chucho::configurable. If you are creating a custom writer, for example, it will already inherit from chucho::writer, so it will be set to be configurable already. Next, you must create two accompanying types to go along with your new configurable: a memento and a factory, which are inherited from chucho::memento and chucho::configurable_factory respectively.

The factory does two things: it creates the memento and it creates the configurable. The job of the memento is to build up information about the object as the configuration is read. Then, the factory uses the information in the memento to create the actual object when its section of the configuration file is done being read. Please refer to the existing Chucho mementos and factories for examples of how this is actually done.

If you are creating a custom writer, please have your factory inherit from chucho::writer_factory and your memento inherit from chucho::writer_memento. The writer_memento already has code for handling the formatter and the filters, as does the factory.

Finally, at run time, you must call chucho::configurator::add_configurable_factory() before configuration occurs. This makes your classes available to the configuration mechanism.

Please don't give your configurable a name that is already in use. The names of all predefined Chucho configurables begin with the prefix "chucho::". Thank you.