{
    "mode": "perldoc",
    "parameter": "Log::Log4perl::Filter",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Log%3A%3ALog4perl%3A%3AFilter/json",
    "generated": "2026-06-11T00:33:12Z",
    "synopsis": "use Log::Log4perl;\nLog::Log4perl->init(\\ <<'EOT');\nlog4perl.logger = INFO, Screen\nlog4perl.filter.MyFilter        = sub { /let this through/ }\nlog4perl.appender.Screen        = Log::Log4perl::Appender::Screen\nlog4perl.appender.Screen.Filter = MyFilter\nlog4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout\nEOT\n# Define a logger\nmy $logger = Log::Log4perl->getlogger(\"Some\");\n# Let this through\n$logger->info(\"Here's the info, let this through!\");\n# Suppress this\n$logger->info(\"Here's the info, suppress this!\");\n#################################################################\n# StringMatch Filter:\n#################################################################\nlog4perl.filter.M1               = Log::Log4perl::Filter::StringMatch\nlog4perl.filter.M1.StringToMatch = let this through\nlog4perl.filter.M1.AcceptOnMatch = true\n#################################################################\n# LevelMatch Filter:\n#################################################################\nlog4perl.filter.M1               = Log::Log4perl::Filter::LevelMatch\nlog4perl.filter.M1.LevelToMatch  = INFO\nlog4perl.filter.M1.AcceptOnMatch = true",
    "sections": {
        "NAME": {
            "content": "Log::Log4perl::Filter - Log4perl Custom Filter Base Class\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Log::Log4perl;\n\nLog::Log4perl->init(\\ <<'EOT');\nlog4perl.logger = INFO, Screen\nlog4perl.filter.MyFilter        = sub { /let this through/ }\nlog4perl.appender.Screen        = Log::Log4perl::Appender::Screen\nlog4perl.appender.Screen.Filter = MyFilter\nlog4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout\nEOT\n\n# Define a logger\nmy $logger = Log::Log4perl->getlogger(\"Some\");\n\n# Let this through\n$logger->info(\"Here's the info, let this through!\");\n\n# Suppress this\n$logger->info(\"Here's the info, suppress this!\");\n\n#################################################################\n# StringMatch Filter:\n#################################################################\nlog4perl.filter.M1               = Log::Log4perl::Filter::StringMatch\nlog4perl.filter.M1.StringToMatch = let this through\nlog4perl.filter.M1.AcceptOnMatch = true\n\n#################################################################\n# LevelMatch Filter:\n#################################################################\nlog4perl.filter.M1               = Log::Log4perl::Filter::LevelMatch\nlog4perl.filter.M1.LevelToMatch  = INFO\nlog4perl.filter.M1.AcceptOnMatch = true\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Log4perl allows the use of customized filters in its appenders to control the output of\nmessages. These filters might grep for certain text chunks in a message, verify that its\npriority matches or exceeds a certain level or that this is the 10th time the same message has\nbeen submitted -- and come to a log/no log decision based upon these circumstantial facts.\n\nFilters have names and can be specified in two different ways in the Log4perl configuration\nfile: As subroutines or as filter classes. Here's a simple filter named \"MyFilter\" which just\nverifies that the oncoming message matches the regular expression \"/let this through/i\":\n\nlog4perl.filter.MyFilter        = sub { /let this through/i }\n\nIt exploits the fact that when the subroutine defined above is called on a message, Perl's\nspecial $ variable will be set to the message text (prerendered, i.e. concatenated but not\nlayouted) to be logged. The subroutine is expected to return a true value if it wants the\nmessage to be logged or a false value if doesn't.\n\nAlso, Log::Log4perl will pass a hash to the subroutine, containing all key/value pairs that it\nwould pass to the corresponding appender, as specified in Log::Log4perl::Appender. Here's an\nexample of a filter checking the priority of the oncoming message:\n\nlog4perl.filter.MyFilter        = sub {    \\\nmy %p = @;                           \\\nif($p{log4plevel} eq \"WARN\" or       \\\n$p{log4plevel} eq \"INFO\") {       \\\nreturn 1;                         \\\n}                                     \\\nreturn 0;                             \\\n}\n\nIf the message priority equals \"WARN\" or \"INFO\", it returns a true value, causing the message to\nbe logged.\n",
            "subsections": [
                {
                    "name": "Predefined Filters",
                    "content": "For common tasks like verifying that the message priority matches a certain priority, there's\nalready a set of predefined filters available. To perform an exact level match, it's much\ncleaner to use Log4perl's \"LevelMatch\" filter instead:\n\nlog4perl.filter.M1               = Log::Log4perl::Filter::LevelMatch\nlog4perl.filter.M1.LevelToMatch  = INFO\nlog4perl.filter.M1.AcceptOnMatch = true\n\nThis will let the message through if its priority is INFO and suppress it otherwise. The\nstatement can be negated by saying\n\nlog4perl.filter.M1.AcceptOnMatch = false\n\ninstead. This way, the message will be logged if its priority is anything but INFO.\n\nOn a similar note, Log4perl's \"StringMatch\" filter will check the oncoming message for strings\nor regular expressions:\n\nlog4perl.filter.M1               = Log::Log4perl::Filter::StringMatch\nlog4perl.filter.M1.StringToMatch = bl.. bl..\nlog4perl.filter.M1.AcceptOnMatch = true\n\nThis will open the gate for messages like \"blah blah\" because the regular expression in the\n\"StringToMatch\" matches them. Again, the setting of \"AcceptOnMatch\" determines if the filter is\ndefined in a positive or negative way.\n\nAll class filter entries in the configuration file have to adhere to the following rule: Only\nafter a filter has been defined by name and class/subroutine, its attribute values can be\nassigned, just like the \"true\" value above gets assigned to the \"AcceptOnMatch\" attribute\n*after* the filter \"M1\" has been defined.\n"
                },
                {
                    "name": "Attaching a filter to an appender",
                    "content": "Attaching a filter to an appender is as easy as assigning its name to the appender's \"Filter\"\nattribute:\n\nlog4perl.appender.MyAppender.Filter = MyFilter\n\nThis will cause \"Log::Log4perl\" to call the filter subroutine/method every time a message is\nsupposed to be passed to the appender. Depending on the filter's return value, \"Log::Log4perl\"\nwill either continue as planned or withdraw immediately.\n"
                },
                {
                    "name": "Combining filters with Log::Log4perl::Filter::Boolean",
                    "content": "Sometimes, it's useful to combine the output of various filters to arrive at a log/no log\ndecision. While Log4j, Log4perl's mother ship, has chosen to implement this feature as a filter\nchain, similar to Linux' IP chains, Log4perl tries a different approach.\n\nTypically, filter results will not need to be bumped along chains but combined in a programmatic\nmanner using boolean logic. \"Log if this filter says 'yes' and that filter says 'no'\" is a\nfairly common requirement, but hard to implement as a chain.\n\n\"Log::Log4perl::Filter::Boolean\" is a specially predefined custom filter for Log4perl. It\ncombines the results of other custom filters in arbitrary ways, using boolean expressions:\n\nlog4perl.logger = WARN, AppWarn, AppError\n\nlog4perl.filter.Match1       = sub { /let this through/ }\nlog4perl.filter.Match2       = sub { /and that, too/ }\nlog4perl.filter.MyBoolean       = Log::Log4perl::Filter::Boolean\nlog4perl.filter.MyBoolean.logic = Match1 || Match2\n\nlog4perl.appender.Screen        = Log::Log4perl::Appender::Screen\nlog4perl.appender.Screen.Filter = MyBoolean\nlog4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout\n\n\"Log::Log4perl::Filter::Boolean\"'s boolean expressions allow for combining different appenders\nby name using AND (&& or &), OR (|| or |) and NOT (!) as logical expressions. Also, parentheses\ncan be used for defining precedences. Operator precedence follows standard Perl conventions.\nHere's a bunch of examples:\n\nMatch1 && !Match2            # Match1 and not Match2\n!(Match1 || Match2)          # Neither Match1 nor Match2\n(Match1 && Match2) || Match3 # Both Match1 and Match2 or Match3\n"
                },
                {
                    "name": "Writing your own filter classes",
                    "content": "If none of Log::Log4perl's predefined filter classes fits your needs, you can easily roll your\nown: Just define a new class, derive it from the baseclass \"Log::Log4perl::Filter\", and define\nits \"new\" and \"ok\" methods like this:\n\npackage Log::Log4perl::Filter::MyFilter;\n\nuse base Log::Log4perl::Filter;\n\nsub new {\nmy ($class, %options) = @;\n\nmy $self = { %options,\n};\n\nbless $self, $class;\n\nreturn $self;\n}\n\nsub ok {\nmy ($self, %p) = @;\n\n# ... decide and return 1 or 0\n}\n\n1;\n\nLog4perl will call the ok() method to determine if the filter should let the message pass or\nnot. A true return value indicates the message will be logged by the appender, a false value\nblocks it.\n\nValues you've defined for its attributes in Log4perl's configuration file, will be received\nthrough its \"new\" method:\n\nlog4perl.filter.MyFilter       = Log::Log4perl::Filter::MyFilter\nlog4perl.filter.MyFilter.color = red\n\nwill cause \"Log::Log4perl::Filter::MyFilter\"'s constructor to be called like this:\n\nLog::Log4perl::Filter::MyFilter->new( name  => \"MyFilter\",\ncolor => \"red\" );\n\nThe custom filter class should use this to set the object's attributes, to have them available\nlater to base log/nolog decisions on it.\n\n\"ok()\" is the filter's method to tell if it agrees or disagrees with logging the message. It\nwill be called by Log::Log4perl whenever it needs the filter to decide. A false value returned\nby \"ok()\" will block messages, a true value will let them through.\n\nA Practical Example: Level Matching\nSee Log::Log4perl::FAQ for this.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "Log::Log4perl::Filter::LevelMatch, Log::Log4perl::Filter::LevelRange,\nLog::Log4perl::Filter::StringRange, Log::Log4perl::Filter::Boolean\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess <cpan@goess.org>.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Please contribute patches to the project on Github:\n\nhttp://github.com/mschilli/log4perl\n\nSend bug reports or requests for enhancements to the authors via our\n\nMAILING LIST (questions, bug reports, suggestions/patches): log4perl-devel@lists.sourceforge.net\n\nAuthors (please contact them via the list above, not directly): Mike Schilli\n<m@perlmeister.com>, Kevin Goess <cpan@goess.org>\n\nContributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens Berthold, Jeremy Bopp,\nHutton Davidson, Chris R. Donnelly, Matisse Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon,\nCarl Franks, Dennis Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David Hull,\nRobert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter, Brett Rann, Peter Rabbitson, Erik\nSelberg, Aaron Straup Cope, Lars Thegler, David Viner, Mac Yang.\n",
            "subsections": []
        }
    },
    "summary": "Log::Log4perl::Filter - Log4perl Custom Filter Base Class",
    "flags": [],
    "examples": [],
    "see_also": []
}