/ 
Agent-TCLI-0.031
River stage one • 1 direct dependent • 1 total dependent
/ Agent::TCLI::Package::Tail

NAME

Agent::TCLI::Package::Tail - A Tail command

SYNOPSIS

# Within a test script

use Agent::TCLI::Package::Tail;

# set the list of packages
my @packages = (
	Agent::TCLI::Package::Tail->new({
		'verbose'		=> \$verbose,
		'do_verbose'	=> sub { diag( @_ ) },
	}),
);

DESCRIPTION

This module provides a package of commands for the TCLI environment. Currently one must use the TCLI environment (or browse the source) to see documentation for the commands it supports within the TCLI Agent.

Agent::TCLI::Package::Tail provides commands to set up filtered tails of files. Tails can be established as a watch which will report on every match, or as a test which supports use in a functional testing activity with discrete matching and reporting characteristics. It supports regex matching of the lines.

It should support more complex testing where POE Filters deliver objects that can be queryied in an OK test, but that has not been tested and is likely buggy. An example of this use would be to have a POE Filter deliver Snort Alert objects which could then be queried if their source addresess was in a range.

INTERFACE

This module must be loaded into a Agent::TCLI::Control by an Agent::TCLI::Transport in order for a user to interface with it.

ATTRIBUTES

These attrbiutes are generally internal and are probably only useful to someone trying to enhance the functionality of this Package module. It would be unusual to set any of these attributes on creation of the package for an Agent. That doesn't mean you can't.

files

A hash of the 'files' being tailed. files will only contain hash values.

line_cache

An array for holding the last few lines to enable lookbacks line_cache will only contain Array values.

test_queue

A queue of all the tests waiting to be activated by triggers test_queue will only contain Array values.

active

A hash keyed on num of all the tests currently active. active will only contain hash values.

ordered

The default setting for ordered test processing. ordered should only contain boolean values.

interval

The default interval setting interval should only contain integer values.

line_max_cache

Maximum size of the line cache, in lines. line_max_cache will only contain numeric values.

line_hold_time

Time to hold lines in the cache, in seconds. line_hold_time will only contain numeric values.

test_max_lines

Default setting for how many lines a test will observe before failing. Defaults to zero (unlimited). test_max_lines will only contain numeric values.

test_match_times

Default setting for how many times a test should match. Default is 1. test_match_times will only contain numeric values.

test_ttl

The default time to live for a test before failing. The default is 0, no expiration. test_ttl will only contain numeric values.

test_verbose

The default test verbose setting. test_verbose will only contain numeric values.

test_feedback

The default feedback setting for new tests. test_feedback will only contain Numeric values.

line_count

A running count of all the lines seen. line_count will only contain numeric values.

test_count

A running count of the tests that have arrived in the queue. test_count will only contain numeric values.

activated_count

A running count of the tests that have been activated. test_count will only contain numeric values.

tests_complete

A running count of the number of tests that have completed. tests_complete will only contain numeric values.

METHODS

Most of these methods are for internal use within the TCLI system and may be of interest only to developers trying to enhance this module.

Append <input>, <wheel_id>

This POE Event handler receives the tail events and creates the line objects to insert into the line_cache. It typically accepts events from POE::Wheel::FollowTail. It may also be called directly from another POE Session, in which case only the input to be logged should be provided. It will insert the sending POE Session as the line->source if no wheel_id is provided.

Activate

This POE event handler activates tests in the queue by registering an event with SimpleLog and creating an event handler. This whole process is currently ineffecient and will hopefully get redone sometime.

Check

The POE event handler is what does the actual test/watch on the line objects.

Complete

This POE event handler handles the response when a test/watch is complete.

FileReset

This POE event handler should do something when a tailed file is reset, but it doesn't. Ideas are welcome.

Log

This POE event handler is used to introduce line objects from sources other than the POE::Wheel::FollowTail.

PruneLineCache

This POE event handler periodically runs to check for lines that have been in the cache too long and removes them.

SetFollowTailWheel

This POE event handler sets up the POE::Wheel::FollowTail to send events to our Append handler for each new File. I suppose at some point I ought to write the corresponding DeleteFollowTailWheel.

Wally

This POE event handler doesn't do anything, because sometimes we must have a state that doesn't respond to work requests. For one never knows when we just throw some event out there if someone else might pick it up by _default and do something with it. This way we KNOW it won't get done.

test

This POE event handler executes the test/watch commands. It is called by the Control and takes a Request as an argument.

clear

This POE event handler executes the clear command. It is called by the Control and takes a Request as an argument.

file

This POE event handler executes the file commands. It is called by the Control and takes a Request as an argument.

settings

This POE event handler executes the set commands.

show

This POE event handler executes the show commands. It is called by the Control and takes a Request as an argument.

log

This POE event handler executes the log commands. It is called by the Control and takes a Request as an argument.

_shutdown

This POE event handler is used to initiate a shutdown of the Package.

_start

This POE event handler is called when POE starts up a Package. The _start method is :Cumulative within OIO.

INHERITED METHODS

This module is an Object::InsideOut object that inherits from Agent::TCLI::Package::Base. It inherits methods from both. Please refer to their documentation for more details.

AUTHOR

Eric Hacker <hacker at cpan.org>

BUGS

Currently there is no separation between users running tests, which means it could be very ugly to have multiple users try to run tests on one TCLI Agent.

Test scripts not thorough enough.

Probably many others.

LICENSE

Copyright (c) 2007, Alcatel Lucent, All rights resevred.

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