View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Jon Schutz > File-Tail-Scribe-0.13 >


Annotate this POD


Open  0
View/Report Bugs

NAME ^ - Tail files and send to a Scribe logging system.

                    [ --daemon ]
                    [ --dirs DIR1 [DIR2 ...] ]
                    [ --excluded-dir XDIR1 [XDIR2 ...] ]
                    [ --excluded-re REGEXP1 [REGEXP2 ...] ]
                    [ --filter=REGEXP ]
                    [ --follow-symlinks ]
                    [ --no-init ]
                    [ --state-file-name=FILE ]
                    [ --sleep-interval=SECS ]
                    [ --port=PORT ] [ --host=HOST ]
                    [ --level=LEVEL ] [ --category=CATEGORY ]

DESCRIPTION ^ monitors files in a given directory (or set of directories), such as Apache log files in /var/log/httpd, and as the log files are written to, takes the changes and sends them to a running instance of the Scribe logging system.



Run in the background.

--dirs DIR1 [DIR2 ...]

The list of directories in which to monitor files for changes. Defaults to /var/log/httpd.

--excluded-dir XDIR1 [XDIR2 ...]

A list of directories to exclude from monitoring. These must be full filesystem paths. Defaults to empty (no exclusions).

--excluded-re REGEXP1 [REGEXP2 ...]

A list of exclude regular expressions; any directory paths that match will be excluded from monitoring. Defaults to empty (no exclusions).


A file filter regular expression; only filenames that match will be monitored. Defaults to '[._]log$' (files ending in .log or _log). Set to '.*' to include all files.


If set, follow symbolic links in the filesystem.


If set, any existing state file will be ignored, and only changes from the current file state will be sent. Without --no-init, on the first run (before any state file is created), any existing content in the monitored files will be sent as well as changes (which could be a large amount of data if you have big files).


Name of file in which to store state between runs. Defaults to '.tailtoscribe' in the working directory.


Where a kernel-based file change notification system is not available, this specifies the number of seconds between scans for file changes.

To minimise CPU usage, installing Linux::Inotify2 is highly recommended.

Scribe Options

--host, --port

Host and port of Scribe server. Defaults to localhost, port 1463.


Default Scribe logging category. Defaults to 'httpd'.


Default log level. Defaults to 'info'. May be set to any valid Log::Dispatch level (debug, info, notice, warning, error, critical, alert, emergency).

--retry-plan-a=MODE, --retry-plan-b=MODE, --retry-buffer-size=SIZE, --retry-count=COUNT, --retry-delay=DELAY

See Log::Dispatch::Scribe for full description of these options.


Write process ID to file FILE. will use this file to check if an instance is already running, and refuse to start if the PID in this file corresponds to another process. Checks are skipped if no pidfile is given.

--debug, --debug=FILE

Enable debugging to standard error or to file.


Specify the location of the configuration file (an included perl script). Defaults to /etc/tail_to_scribe.conf. A typical configuration file might look like this:

  # Set my arg values
  my %localargs = (
      dirs => [ '/var/log/httpd' ],
      filter => 'access[._]log$',
      'exclude-dir' => [ '/var/log/httpd/fastcgi' ],
      'state-file-name' => '/var/log/httpd/.tailtoscribe',

  # Copy into args to override defaults
  $args{$_} = $localargs{$_} for keys %localargs;

  1; # Must return a true value

In addition to all of the options available on the command line, a custom message filter may also be included, e.g.

  $msg_filter = sub {
    my ($self, $filename, $line) = @_;

    return ('info', 'httpd', "$filename\t$line");

See "msg_filter" in File::Tail::Scribe for more details on the msg_filter.


HUP signal causes to restart. TERM/QUIT/INT cause it to save state and exit.



Jon Schutz, <jon at>


Please report any bugs or feature requests to bug-file-tail-scribe at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc File::Tail::Scribe

You can also look for information at:



Copyright 2010 Jon Schutz, all rights reserved.

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

syntax highlighting: