DESCRIPTION

Shiras - A small subspecies of Moose found in the western United States (of America).

This is one of many loggers you can choose from in CPAN. The ultimate goal of this package is to add name-space control to any of your programs outputs that you want name-space control of. As the package stands today there are three relevant name-spaces. First, the file name-space, file name-space is the name-space that we apply to specific files (modules or scripts). The file name-space in this package is treated as flat (no heirarchy) and is managed using source code filters . File name-space filtering is therefore done at compile time with no run time changes available. The second name-space is a run time caller name-space that can be adjusted as the program operates. Caller name-space is applied to the source of the output. The caller namespace also allows for urgency levels to be assigend to each source of information. The caller namespace is hierarchical which allows filtering to be applied lower in the hierarchy and remain in force farther out in the branch. Caller name-space and urgency can be changed during run-time. Finally, there is a destination name-space. Not all sources will wish to call the same destination. Destination name-space is flat and less flexible but still somewhat editable at run time. Caller name-space, caller urgency levels, and desination name-space are all stiched together using permissions. Permissions can also be changed at run-time. To sort of stich these concepts together mentally I have used terminology associated with the old land line telephone system. Caller name-space is managed through a telephone class. Permissions are managed through a switchboard with switchboard operators. And destinations are called reports . This last term does not follow the terminology of the old land lines since communication through this package is one direction. Reports cannot send messages back on the same connection that they use to receive information.

All in all this can create a complex name-space landscape. For this package all name-spaces in the run environment are shared and caution should be used to manage uniqueness. I would encourage starting simple and working out if you don't have a lot of logging experience. This package is most related in concept to Log::Dispatch.

Acknowledgement

Differentiation

Why choose this Logger over one of the many other options? Here are some implementation decisions that I made that may or may not help that decision. Many if not all of these elements exist in other loggers. I don't think they all exist together in any other logger.

Buffer behavior

This package has a destination buffer in the switchboard (default off) for each report name. This allows for some messages to be discarded after they were collected based on branches in the code. A use case for this is when you are recursively parsing some logic but only want to log the actions in the path that yielded results. This is different than a print buffer that always goes to the output but the send is just delayed.

A wrapper class for messages

Log::Shiras::Telephone is it's own class and can be used to customize how messages are sent as well as allowing more flexibility in the format of sent messages.

A dedicated test module for testing logged messages that will capture messages at the switchboard level rather than requiring the implementation of the final report destination to test output. Specifically, implementation of Telephone code can be tested without also implementing Report code. This is done through a hook built into the Switchboard . The test methods include several ways of checking for output existence. Testing report implementation should be done traditionally.

Headers

The 'Report' class in this package for CSV files Log::Shiras::Report::CSVFile only adds the header to a file when it is new. If the file connection is dropped and then reconnected the header will not be added again if the file is not empty. It will also manage (or at least warn) on header drift for the first added row.

Custom formatting

I wanted to be able to use method calls and code references when formatting 'Report' output. The Log::Shiras::Report::MetaMessage Role for the 'Report' class does just that. This varies from Log::Log4perl's 'PatternLayout' as it operates on an array ref or hashref rather than a string. There may be a string formatter in the future since I half wrote one but I talked myself out of it in favor of an array ref manipulation scheme.

This package is Moose based. You probably already have an opinion on Moose so this may tip you one way or the other.

Multiple output paths

Allowing more than one destination using the same logging software in a script space is helpful. This means you can write your output to multiple sources without wiring up the connection or finishing the destination definition until later. See also Log::Dispatch.

Source filtering

Excessive outputs for troubleshooting or outputs that are only used in rare circumstances will overburden code. Having a source filter will allow the code to remain in source control (no retyping and deleting print statements) while still not burdening run time operations generally (unless you need the outputs). See also Smart::Comments and Log::Log4perl::Resurrector

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.