Home Benchmarks Documentation Download
Swiftcore Analogger v. 0.5 Documentation
Installation

To install analogger:

ruby setup.rb

The analogger executable will be installed into the ruby installation's bindir, along with server and client libraries into the site_lib. The rdoc documentation will also be generated.

ruby setup.rb --help

to see a full list of options.

After installation, the test suite can be ran with:

ruby setup.rb test

Analogger depends on EventMachine. Analogger (and EventMachine) can be installed as a gem via gem install analogger.

Quickstart

To start an Analogger instance, first create a configuration file:

port: 6766
host: 127.0.0.1
default_log: /var/log/weblogs/default
daemonize: true
syncinterval: 60
logs:
  - service: bigapp
    logfile: /var/log/bigapp
    cull: true
  - service:
  - smallapp1
  - smallapp2
    logfile: /var/log/smallapps
    cull: true
  - service: newsletter_sender
    logfile: /var/log/newsletter.log
    cull: false

Then start the analogger:

/usr/bin/env analogger -c config_file

To use the client library to connect to an Analogger instance and send logging messages to it:

require 'swiftcore/Analogger/Client'
logger = Swiftcdore::Analogger::Client.new('smallapp1','127.0.0.1','6766')
logger.log('info','This is a log message.')

Analogger Command Line Options
-c, --config CONFFILE
Use this option to specify the configuration file that the Analogger will use.
-p, --port [PORT]
This option can be used to specify the port to listen on for client connections. It will override whatever is specified in the configuration file.
-h, --host [HOST]
Like --port, this option can be used to specify the hostname/IP address to bind to to listen for client connections. It will override whatever is specified in the configuration file.
-k, --key [KEY]
An Analogger process can be given a secret key which must be sent by a client in order to authenticate a client connection. Normaly this comes from the configuration file, but it can be overridden with this command line option.
-i, --interval [INTERVAL]
When the Analogger receives logging messages, it stuffs them into an in-memory queue. Then at regular intervals this queue is flushed. This parameter overrides the frequency at which the queue is flushed.
-s, --syncinterval [INTERVAL]
When data is written to a log file, the OS may buffer that data for performance reasons. Sometimes (especially when debugging), one wants to see the buffered data flushed to disk more quicky that the OS is inclined to do it. So every INTERVAL seconds, Analogger will go through all of it's log destinations and flush them, if the destination supports it.
-d, --default [PATH]
Logs with specify a logging service that is not defined in the configuration file will be sent to the default destination. Unless specified in the configuration file or on the command line, the default destination is STDOUT.
-x, --daemonize
The Analogger can background itself, if wanted. This parameter overrides the daemonize setting in the configuration file.
-w, --writepid [FILENAME]
This tells the Analogger to write it's PID to a file. If the filename isn't given, it will write to analogger.pid.
--help
Display this information.
Analogger Configuration

Analogger requires a configuation file to tell it what address/port to listen for logging clients, and where to send messages that it receives. The configuration file uses a YAML format. For the purposes of Analogger configuration, what this means is that key/value pairs are placed one per line, with a : between the key and the value, and lists of items are created by leading off a list item with - , one per line.

The following items can be specified in an Analogger configuration file:

daemonize
daemonize: true

If this is set to true, the Analogger will attempt to put itself into the background. This currently only works on platforms where fork() is supported (i.e. not on win32 platforms).

default_log
default_log: /var/log/analogs

When a logging message is sent to the Analogger, the logging service of the message is part of the message package. If the specified service is not given a specific logging destination (see logs below), then the message will be sent to the default_log. Unless overridden in the configuration file, those messages go to STDOUT.

host
host: 127.0.0.1

Specifies the address that the Analogger will bind to listen for client connections.

key
key: zv9845pl!qpy$

For security purposes, an Analogger process can be given an access key or arbitrary length. Any client that wishes to deliver logs to this Analogger is required to provide a matching key upon first connection to the analogger. If it does not, then it's connection will be sumarily dropped without accepting any logging messages.

levels
levels: debug, general, fault, fatal

or

levels:
- debug
- general
- fault
- fatal

Analogger assumes a default set of logging severity levels that correspond to those defined by the Logger class in the Ruby standard distribution. These are:

debug, info, error, warn, fatal

The default set of severity levels can be overridden by specifying a levels configuration item.

pidfile
pidfile: /var/run/analogger.pid

This configuration option specifies a filename to use as a PID file.

port
port: 6676

Specifies the port to bind to listen for client connections.

logs
logs:
  - service:
  - a
  - b
    logfile: log/a.log
    cull: true
    levels: a,b,c,d
  - service: c
    logfile: log/c.log
    cull: true
  - service: d
    logfile: log/d.log
    cull: false
cull
cull: false

If multiple sequential logs with identical severity levels and message bodies are sent to Analogger for a given logging service, and cull is set to true, then only the first message will be inserted into the logfile. Following that message with be a message indicating how many times the first message was repeated. i.e.

2007/03/27 09:58:16|analogger.swiftcore.org|info|Last message repeated 2073 times

If it is set to false then each separate message will be inserted into the log file. This defaults to true if left unspecified.

levels

Accepted logging levels can be defined for each logging service. Messages which are not one of the defined logging levels are silently discarded. If levels are not defined for a logging service, the default set of levels is used. Refer to the documentation above for specific information on the syntax used to specify a list of accepted logging levels.

service
service: chuckie_bob

Or

service:
- chukie_bob
- gillroy_jones

This is the name of the logging service being defined. This is the name a logging client will use to send a log to the logging destination. Multiple service names can be given, as in the example above, if multiple different logging services are to share the same set of configurations. Any logging message sent to a service name that is not recognized will be delivered to the default destination.

logfile
logfile: /var/log/webapps/chuckie_bob_fund.log

This is the destination for the logging messages. It can be either a file path or STDOUT/STDERR.

Analogger Client Library

The Swiftcore Analogger package includes a client library, Swiftcore::Analogger::Client, provides a simple interface for managing a connection and sending messages to an Analogger instance. It's usage is simple:

require 'swiftcore/Analogger/Client'
logger = Swiftcore::Analogger::Client.new('walrus','127.0.0.1','12345','i am the access key')
logger.log('info','W.A.L.R.U.S. initialization complete')
logger.close unless logger.closed?

What A Logfile Looks Like

The log file format is currently a fixed format:

timestamp|service|level|message

TODO in the next version is to permit a configurable format for the log files.