* heliosx_logger_hires_search: more polish, deactivated debugging

messages by default.
* Makefile.PL: added parent as a prereq because it was left off
earlier.
* Updated and filled in a lot of missing documentation in README,
README.md, HiRes.pm, and heliosx_logger_hires_search.
* "Renamed HeliosX-Logger-HiRes.t" to "1.t".

MANIFEST

@@ -9,4 +9,4 @@ README
 sql/heliosx_logger_hires_mysql.sql
 sql/heliosx_logger_hires_oracle.sql
 sql/heliosx_logger_hires_sqlite.sql
-t/HeliosX-Logger-HiRes.t
+t/1.t

Makefile.PL

@@ -11,6 +11,7 @@ my %eumm_params = (
                           'Helios'      => 2.80,
                           'Time::HiRes' => 1.86,
                           'Time::Piece' => 1.12,
+                          'parent'      => 0.221,
                          }, 
     EXE_FILES         => ['heliosx_logger_hires_search'],
     INST_SCRIPT       => 'bin',

README

@@ -1,9 +1,9 @@
 HeliosX-Logger-HiRes version 0.10
 =================================
 
-HeliosX::Logger::HiRes is a Helios::Logger logging class that provides logging
-with high-resolution timestamp precision with a more normalized database
-structure.
+HeliosX::Logger::HiRes is a Helios::Logger logging class that provides
+logging with high-resolution timestamp precision with a more
+normalized database structure.
 
 INSTALLATION
 
@@ -14,12 +14,20 @@ To install this module type the following:
    make test
    make install
 
+This module requires schema modifications to your Helios collective
+database.  Data description language (DDL) describing these
+modifications are detailed in files in the sql/ directory.  Find the
+.sql file appropriate to your RDBMS and modify it as necessary for
+your environment, and run the SQL to create the database structures.
+
 DEPENDENCIES
 
 This module requires these other modules and libraries:
 
   Helios 2.8x
+  Time::HiRes 1.86
   Time::Piece 1.12
+  parent 0.221
 
 COPYRIGHT AND LICENSE
 

README.md

@@ -1,33 +1,39 @@
 HeliosX-Logger-HiRes version 0.10
 =================================
-
 HeliosX::Logger::HiRes is a Helios::Logger logging class that provides logging
 with high-resolution timestamp precision with a more normalized database
 structure.
 
 INSTALLATION
-
+------------
 To install this module type the following:
 
-   perl Makefile.PL
-   make
-   make test
-   make install
+    perl Makefile.PL
+    make
+    make test
+    make install
 
-DEPENDENCIES
+This module requires schema modifications to your Helios collective database.
+Data description language (DDL) describing these modifications are detailed in
+files in the `sql/` directory.  Find the `.sql` file appropriate to your RDBMS
+and modify it as necessary for your environment, and run the SQL to create the
+database structures.
 
+DEPENDENCIES
+------------
 This module requires these other modules and libraries:
 
-  Helios 2.8x
-  Time::Piece 1.12
+* Helios 2.80 or later
+* Time::HiRes 1.86 or later
+* Time::Piece 1.12 or later
+* parent 0.221 or later
 
 COPYRIGHT AND LICENSE
-
+---------------------
 Copyright (C) 2015 by Logical Helion, LLC.
 
 This library is free software; you can redistribute it and/or 
 modify it under the terms of the Artistic License 2.0.  See the 
 included LICENSE file for details.
 
 This software comes with no warranty of any kind.
-

heliosx_logger_hires_search

@@ -6,7 +6,6 @@ use warnings;
 use Getopt::Long;
 use Time::Local;
 use Time::Piece;
-use Data::Dumper; #[]
 
 use Helios::ObjectDriver;
 use Helios::LogEntry::Levels ':all';
@@ -33,25 +32,28 @@ our ($OPT_START_DATE, $OPT_END_DATE, $OPT_HOSTNAME, $OPT_PID, $OPT_JOBID,
     $OPT_SORT, $OPT_TAIL, $OPT_FOLLOW);
 our ($OPT_HELP, $OPT_VERSION, $OPT_DEBUG);
 
-our $DEBUG_MODE  = 1;
+our $DEBUG_MODE  = 0;
 our $FOLLOW_MODE = 0;
 our $TAIL_MODE   = 0;
 our $LAST_LOGID  = 0;
 
 GetOptions(
     "start-date=s"    => \$OPT_START_DATE,
     "end-date=s"      => \$OPT_END_DATE,
+
     "hostname=s"      => \$OPT_HOSTNAME,
     "pid=i"           => \$OPT_PID,
     "jobid=s"         => \$OPT_JOBID,
     "jobtype=s"       => \$OPT_JOBTYPE,
     "service=s"       => \$OPT_SERVICE,
     "message=s"       => \$OPT_MESSAGE,
     "priority=s"      => \$OPT_PRIORITY,
+
     "n|lines|limit=i" => \$OPT_LIMIT,
     "sort=s"          => \$OPT_SORT,
     "tail"            => \$OPT_TAIL,
     "follow"          => \$OPT_FOLLOW,
+
     "help"            => \$OPT_HELP,
     "version"         => \$OPT_VERSION,
     "debug"           => \$OPT_DEBUG,
@@ -174,7 +176,10 @@ if ($FOLLOW_MODE) {
 
 #[] t
 if ($DEBUG_MODE) {
-    print Dumper(\%search_opts);
+    print "SEARCH OPTIONS:\n";
+    foreach my $opt (sort keys %search_opts) {
+        print $opt,' => ',$search_opts{opt},"\n";
+    }
 }
 
 
@@ -190,13 +195,13 @@ eval {
     }
 
     foreach ( @logs ) {
-#        print Dumper($_);        
         my $tp = localtime $_->log_time;
         my ($sec, $fract) = split(/\./, $_->log_time);
         my $date = $tp->ymd.' '.$tp->hms.'.'.$fract;
         my $jobinfo = $_->jobid ? ' [Jobid '.$_->jobid.']' : '';
         $LAST_LOGID = $_->logid;
-        print $_->logid,' [',$date,'] ',$_->host,' ',$_->service,'[',$_->pid,']: ',$LOG_PRIORITIES[$_->priority],$jobinfo,' ',$_->message,"\n";
+        print $_->logid.' ' if $DEBUG_MODE; #[]t
+        print '[',$date,'] ',$_->host,' ',$_->service,'[',$_->pid,']: ',$LOG_PRIORITIES[$_->priority],$jobinfo,' ',$_->message,"\n";
     }
 
     1;
@@ -215,13 +220,13 @@ if ($FOLLOW_MODE) {
                 { sort => 'log_time', direction => 'ascend' }
             );    
             foreach ( @logs ) {
-            #        print Dumper($_);        
                 my $tp = localtime $_->log_time;
                 my ($sec, $fract) = split(/\./, $_->log_time);
                 my $date = $tp->ymd.' '.$tp->hms.'.'.$fract;
                 my $jobinfo = $_->jobid ? ' [Jobid '.$_->jobid.']' : '';
                 $LAST_LOGID = $_->logid;
-                print $_->logid,' [',$date,'] ',$_->host,' ',$_->service,'[',$_->pid,']: ',$LOG_PRIORITIES[$_->priority],$jobinfo,' ',$_->message,"\n";
+                print $_->logid.' ' if $DEBUG_MODE; #[]t
+                print '[',$date,'] ',$_->host,' ',$_->service,'[',$_->pid,']: ',$LOG_PRIORITIES[$_->priority],$jobinfo,' ',$_->message,"\n";
             }
             1;
         } or do {
@@ -268,20 +273,20 @@ heliosx_logger_hires_search - search the Helios high resolution log
 
 The heliosx_logger_hires_search command can be used to display log messages
 matching specified criteria in the enhanced Helios log provided by
-HeliosX::Logger::HiRes.  It provides a much more convenient way of accessing
+L<HeliosX::Logger::HiRes>.  It provides a much more convenient way of accessing
 log messages than using SQL queries from a database client like SQL*Plus or
 sqlite3.
 
 =head1 RUN OPTIONS
 
-=head2 start-date="YYYY-MM-DDTHH24:MI:SS"
+=head2 --start-date="YYYY-MM-DDTHH24:MI:SS"
 
-=head2 end-date="YYYY-MM-DDTHH24:MI:SS"
+=head2 --end-date="YYYY-MM-DDTHH24:MI:SS"
 
 Specify a date range of log messages to display.  Dates should be in ISO8601
 format.  If only --start-date is specified, log messages will be displayed from
 that date forward until there are no more log messages.  If only --end-date is
-specified, log messages will be displayed from the the earliest through the
+specified, log messages will be displayed from the earliest through the
 end date specified.
 
 Normally, heliosx_logger_hires_search displays a maximum number of log

lib/HeliosX/Logger/HiRes.pm

@@ -12,7 +12,7 @@ use Helios::LogEntry::Levels ':all';
 use Helios::Error::LoggingError;
 use HeliosX::Logger::HiRes::LogEntry;
 
-our $VERSION = '0.10_0000';
+our $VERSION = '0.10_0001';
 
 =head1 NAME
 
@@ -44,8 +44,58 @@ view and search for log messages at the command line.
 
 =head1 CONFIGURATION
 
-#[] missing
+HeliosX::Logger::HiRes must be added to your service using the B<loggers>
+directive either using the B<helios_config_set> command or in B<helios.ini>.
 
+Additionally, as HeliosX::Logger::HiRes is largely intended to replace the
+Helios internal logger, once you are sure it is working properly in your
+installation you should turn off the Helios default logger using the
+B<internal_logger=off> option.
+
+See the L<Helios::Configuration> page for complete information about the
+B<loggers> and B<internal_logger> directives.
+
+HeliosX::Logger::HiRes itself can be configured using the options below:
+
+=over 4
+
+=item * log_priority_threshold
+
+Unlike L<HeliosX::Logger::Syslog> and L<HeliosX::Logger::Log4perl>,
+HeliosX::Logger::HiRes supports the Helios internal logger's
+B<log_priority_threshold> option to limit the messages actually being logged
+to a certain level.  Unlike the others, HeliosX::Logger::HiRes is intended to
+replace rather than augment the Helios internal logger, so most users running
+HeliosX::Logger::HiRes will most likely turn off the Helios internal
+logger.  Rather than create confusion with a separate threshold option,
+HeliosX::Logger::HiRes honors the internal logger's built-in
+B<log_priority_threshold> option.
+
+The B<log_priority_threshold> value should be an integer matching one of the
+Helios logging priorities in L<Helios::LogEntry::Levels>:
+
+ Priority Name    Integer Value
+ LOG_EMERG        0
+ LOG_ALERT        1
+ LOG_CRIT         2
+ LOG_ERR          3
+ LOG_WARNING      4
+ LOG_NOTICE       5
+ LOG_INFO         6
+ LOG_DEBUG        7
+
+Examples:
+
+ # in helios.ini
+ # for all services on this host, log everything but debug messages
+ [global]
+ log_priority_threshold=6
+
+ # at the command line, set all instances of MyService
+ # to only log warnings and worse
+ helios_config_set -s MyService -H="*" -p log_priority_threshold -v 4
+ 
+=back
 
 =head1 IMPLEMENTED METHODS
 
@@ -59,18 +109,34 @@ sub init { }
 
 =head2 logMsg($job, $priority, $message)
 
-#[] description
+The logMsg() method takes a job, priority, and log message and savesthe message
+to the high-resolution log table in the Helios collective database.
+
+The job parameter should be a Helios::Job object.  If the job value is
+undefined, no jobid is saved with the message.
+
+If the priority parameter is undefined, logMsg() defaults the message's
+priority to 6 (LOG_INFO).
 
 =cut
 
 sub logMsg {
     my $self = shift;
+    unless (scalar @_ == 3) { Helios::Error::LoggingError->throw(__PACKAGE__."->logMsg() ERROR:  logMsg() requires 3 arguments:  \$job, \$priority, \$message."); }    
     my ($job, $priority, $message) = @_;
 
+    # deal with the log priority & threshold (if set)
+    $priority = defined($priority) ? $priority : LOG_INFO;
+    my $threshold = defined($self->getConfig()->{log_priority_threshold}) ? $self->getConfig()->{log_priority_threshold} : LOG_DEBUG;
+    if ($priority > $threshold) {
+        return 1;
+    }
+
     my $success = 0;
     my $retries = 0;
     my $err;
 
+    # deal with jobid & jobtypeid
     my $jobid = defined($job) ? $job->getJobid() : undef;
     my $jobtypeid = defined($job) ? $job->getJobtypeid() : undef;
 
@@ -85,7 +151,7 @@ sub logMsg {
                 jobid     => $jobid,
                 jobtypeid => $jobtypeid,
                 service   => $self->getService(),
-                priority  => defined($priority) ? $priority : LOG_INFO,
+                priority  => $priority,
                 message   => $message,
             );
             $drvr->insert($obj);