To install analogger:
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.
To start an Analogger instance, first create a configuration file:
- service: bigapp
- service: newsletter_sender
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:
logger = Swiftcdore::Analogger::Client.new('smallapp1','127.0.0.1','6766')
logger.log('info','This is a log message.')
--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.
daemonizesetting in the configuration file.
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:
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).
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.
Specifies the address that the Analogger will bind to listen for client connections.
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: 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.
This configuration option specifies a filename to use as a PID file.
Specifies the port to bind to listen for client connections.
- service: c
- service: d
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.
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.
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.
This is the destination for the logging messages. It can be either a file path or STDOUT/STDERR.
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:
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?
The log file format is currently a fixed format:
TODO in the next version is to permit a configurable format for the log files.