/ 
Log-Handler-0.38_13
River stage two • 30 direct dependents • 42 total dependents
/ Log::Handler::Config

NAME

Log::Handler::Config - The main config loader.

SYNOPSIS

use Log::Handler;

my $log = Log::Handler->new();

$log->config(
    filename => 'file.conf',
    plugin   => 'YAML',
    section  => 'section-name',
);

Or

use Log::Handler;
use Log::Handler::Config;

my $conf = Log::Handler::Config->config(
    filename => 'file.conf',
    plugin   => 'YAML',
    section  => 'section-name',
);

my $log = Log::Handler->new();

while ( my ($type, $config) = each %$conf ) {
    $log->add($type => $config);
}

DESCRIPTION

This module makes it possible to load the configuration from a file.

METHODS

config()

With this method it's possible to load the configuration for your outputs.

The following options are valid:

filename

The configuration file.

plugin

With this option you can set the plugin you want to use. There are 3 plugins available at the moment:

Config::General
Config::Properties
YAML

If the option is not set then the file extension is used to determine the configuration style:

Config::General     -   cfg, conf 
Config::Properties  -   props, jcfg, jconf
YAML                -   yml, yaml

Examples:

# use file.conf and YAML

$log->config(
    filename => 'file.conf',
    plugin   => 'YAML'
);

# automatically use YAML

$log->config(
    filename => 'file.yaml'
);

# automatically use Config::General

$log->config(
    filename => 'file.conf'
);

If the extension is not defined then Config::General is used by default.

section

If your configuration is placed in file where you configure your complete program you can push your output configuration into a sub section:

<output>
    <file>
        <mylog>
            filename = file.log
            minlevel = 0
            maxlevel = 7
        </mylog>
    </file>
</output>

<Another_Script_Config>
    foo = bar
</Another_Script_Config>

Now your configuration is placed in the output section. You can load this section with

$log->config(
    filename => 'file.conf',
    section  => 'output',
);

# or if you load the configuration yourself to $config

$log->config(
    config  => $config,
    section => 'output',
);

# or just

$log->config( config => $config->{output} );
config

With this option you can pass a configuration that you loaded already but it must have the correct hash structure! Take a look to the examples!

PLUGINS

Config::General     -  inspired by the well known apache config format
Config::Properties  -  Java-style property files
YAML                -  optimized for human readability

EXAMPLES

Config structure

For each output object it must exist a own section. Here a example as hash:

my %config = (

    # the configuration for a file

    file => {
        foo => {
            filename => 'file1.log',
            maxlevel => 'info',
            minlevel => 'warn',
        },
        bar => {
            filename => 'file2.log',
            maxlevel => 'error',
            minlevel => 'emergency',
        }
    }

    # the configuration for email

    email => {
        foo =>
            host     => 'foo.example',
            from     => 'me@me.example',
            to       => 'you@foo.example',
            maxlevel => 'error',
            minlevel => 'emergency',
        },

        # and_so_on ...
    }
);

You can store your configuration to a file and loads it. There are different config plugins available.

A default section

If your configuration contains a default section then this parameters are used for all other sections. Example:

my %config = (
    # the configuration for a file
    file => {
        default => {
            mode     => 'append',
        },
        foo => {
            filename => 'file1.log',
            maxlevel => 'info',
            minlevel => 'warn',
        },
        bar => {
            filename => 'file2.log',
            maxlevel => 'error',
            minlevel => 'emergency',
        },
        baz => {
            filename => 'file3.log',
            maxlevel => 'debug',
            minlevel => 'debug',
            mode     => 'trunc',
        },
    },
    # the configuration for dbi
    dbi => {
        ...
    }
);

The option mode is set to append for the log file file1.log and file2.log. The configuration for file3.log will be set to trunc.

Examples for the config plugins

Config::General

<file>
    <mylog>
        fileopen = 1
        reopen = 1
        permissions = 0640
        maxlevel = info
        mode = append
        timeformat = %b %d %H:%M:%S
        debug_mode = 2
        filename = example.log
        minlevel = warn
        prefix = '%T %H[%P] [%L] %S: '
        newline = 1
    </mylog>
</file>

YAML

---
file:
  mylog:
    debug_mode: 2
    filename: example.log
    fileopen: 1
    maxlevel: info
    minlevel: warn
    mode: append
    newline: 1
    permissions: 0640
    prefix: '%T %H[%P] [%L] %S: '
    reopen: 1
    timeformat: '%b %d %H:%M:%S'

Config::Properties

file.mylog.reopen = 1
file.mylog.fileopen = 1
file.mylog.maxlevel = info
file.mylog.permissions = 0640
file.mylog.mode = append
file.mylog.timeformat = %b %d %H:%M:%S
file.mylog.debug_mode = 2
file.mylog.minlevel = warn
file.mylog.filename = example.log
file.mylog.newline = 1
file.mylog.prefix = '%T %H[%P] [%L] %S: '

Load the config from a certain section

The config (Config::General)

<output>
    <file>
        <default>
            newline     = 1
            permissions = 0640
            timeformat  = %b %d %H:%M:%S
            fileopen    = 1
            reopen      = 1
            mode        = append
            prefix      = "%T %H[%P] [%L] %S: "
            debug_mode  = 2
        </default>

        <common>
            filename    = example.log
            maxlevel    = info
            minlevel    = warn
        </common>

        <error>
            filename    = example-error.log
            maxlevel    = warn
            minlevel    = emergency
        </error>

        <debug>
            filename    = example-debug.log
            maxlevel    = debug
            minlevel    = debug
        </debug>
    </file>
</output>

Load the config

$log->config(
    filename => 'file.conf',
    section  => 'output',
);

Simple configuration without a certain section

The config (Config::General)

<file>
    <default>
        newline     = 1
        permissions = 0640
        timeformat  = %b %d %H:%M:%S
        fileopen    = 1
        reopen      = 1
        mode        = append
        prefix      = "%T %H[%P] [%L] %S: "
        debug_mode  = 2
    </default>

    <common>
        filename    = example.log
        maxlevel    = info
        minlevel    = warn
    </common>

    <error>
        filename    = example-error.log
        maxlevel    = warn
        minlevel    = emergency
    </error>

    <debug>
        filename    = example-debug.log
        maxlevel    = debug
        minlevel    = debug
    </debug>
</file>

Load the config

$log->config( filename => 'file.conf' );

The config as hash

$log->config(
    config => {
        file => {
            default => {
                newline     => 1,
                permissions => '0640',
                timeformat  => '%b %d %H:%M:%S',
                fileopen    => 1,
                reopen      => 1,
                mode        => 'append
                prefix      => '%T %H[%P] [%L] %S: ',
                debug_mode  => 2,
            },
            common => {
                filename    => 'example.log',
                maxlevel    => 'info',
                minlevel    => 'warn',
            },
            error => {
                filename    => 'example-error.log',
                maxlevel    => 'warn',
                minlevel    => 'emergency',
            },
            debug => {
                filename    => 'example-debug.log',
                maxlevel    => 'debug',
                minlevel    => 'debug',
            },
        }
    }
);

Configuration for different outputs

<output>
    <file>
        <default>
            newline     = 1
            permissions = 0640
            timeformat  = %b %d %H:%M:%S
            fileopen    = 1
            reopen      = 1
            mode        = append
            prefix      = "%T %H[%P] [%L] %S: "
            debug_mode  = 2
        </default>

        <common>
            filename    = example.log
            maxlevel    = info
            minlevel    = warn
        </common>

        <error>
            filename    = example-error.log
            maxlevel    = warn
            minlevel    = emergency
        </error>
    </file>

    <email>
        <default>
            timeout     = 60
            debug       = 0
            subject     = My subject
            buffer      = 100
            interval    = 300
            prefix      = "%T %H[%P] [%L] %S: "
            debug_mode  = 2
        </default>

        <admin>
            host        = foo.example
            from        = me@me.example
            to          = you@foo.example
            maxlevel    = error
            minlevel    = emergency
        </admin>

        <op>
            host        = bar.example
            from        = me@me.example
            to          = you@bar.example
            maxlevel    = warn
            minlevel    = emergency
        </op>
    </email>
</output>

PREREQUISITES

Carp
Params::Validate
UNIVERSAL::require

EXPORTS

No exports.

REPORT BUGS

Please report all bugs to <jschulz.cpan(at)bloonix.de>.

AUTHOR

Jonny Schulz <jschulz.cpan(at)bloonix.de>.

QUESTIONS

Do you have any questions or ideas?

MAIL: <jschulz.cpan(at)bloonix.de>

If you send me a mail then add Log::Handler into the subject.

TODO

* Log::Handler::Output::DBI
* Log::Handler::Output::Socket

COPYRIGHT

Copyright (C) 2007 by Jonny Schulz. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.