NAME

Devel::Events - Extensible instrumentation framework.

SYNOPSIS

        use Devel::Events::Generator::Foo;
        use Devel::Events::Handler::Bar;
        use Devel::Events::Filter::Blort;

        my $h = Devel::Events::Generator->new(
                handler => Devel::Event::Filter->new(
                        handler => Devel::Events::Handler::Bar->new(),
                ),
        );

DESCRIPTION

Devel::Events is an event generation, filtering and analaysis framework for instrumenting and auditing perl code.

Devel::Events::Generator object fire events, which can be mangled by Devel::Event::Filter objects. Eventually any number of Devel::Event::Handler objects can receive a given event, and perform analysis based on it.

For example Devel::Event::Handler::ObjectTracker can be used to detect leaks.

COMPONENT OVERVIEW

There are two main types of components - generators and handlers.

Filters are special types of handlers that always delegate to another handler.

The multiplex handler may be used to delegate to any number of handlers.

Using these basic components complex chains of handlers can be built to properly analyze the events you are interested in.

Generators

Devel::Events::Generator::Objects

Generate object_bless and object_destroy events by overriding CORE::GLOBAL::bless and tracking every object using Variable::Magic.

Devel::Events::Generator::SubTrace

Uses the perl debugger hook to generate enter_sub and leave_sub events.

Devel::Events::Generator::LineTrace

Fires an executing_line event for every line using the perl debugger hook.

Handlers

Devel::Events::Handler::Multiplex

Repeat events to multiple handlers.

Devel::Events::Handler::Callback

Make a handler object out of a callback.

Devel::Events::Handler::Log::Memory

Log all events to an array.

Provides filtering and slicing methods to ease analysis.

Devel::Events::Handler::ObjectTracker

Handles object_bless and object_destroy events (as generated by Devel::Events::Generator::Objects) to track the lifetime of objects. When objects lifetimes extend beyond the scope they're supposed to be destroyed in leaks can be detected.}

Filters

Devel::Events::Filter::Stamp

Add various stamp data (time, process ID, thread ID if threads are loaded) to events.

Devel::Events::Filter::Stringify

Stringify (by default using "StrVal" in overload, to avoid side effects) all event data to avoid leaking.

Devel::Events::Filter::Size

Add size reports to events using Devel::Size

Devel::Events::Filter::RemoveFields

Remove certain fields from events.

Devel::Events::Filter::Warn

Runs warn "@event" before delegating to the sub handler. Useful for debugging handler chains.

EVENT STRUCTURE

All events are passed as lists.

The default components will generate lists containing a single string which is the event name, and then a list of key/value pairs. Duplicate keys are allowed and their values will be preserved by the default filters, for example.

The idea is that hashifying is easy when desired, but that other structures can easily be supported as well.

Default values should be prepended to the list of key/value pairs so that when assigned to a hash the values that succeed them will get be the ones ending up in the hash.

AUTHOR

Yuval Kogman <nothingmuch@woobling.org>

COPYRIGHT & LICENSE

        Copyright (c) 2007 Yuval Kogman. All rights reserved
        This program is free software; you can redistribute it and/or modify it
        under the terms of the MIT license or the same terms as Perl itself.