Poirot

Poirot is a set of tools and libraries for log collection and analysis developed by InSTEDD. Poirot includes loggers for multiple platforms, which post log entries to a log receiver that indexes them in an ElasticSearch backend, which can then be queried and navigated in a web frontend.

Activities

Poirot log entries can be grouped in activities. An activity is a set of log entries grouped by a certain criteria, such as being related to the same task or to the same web request. Activities can be hierarchical, and Poirot tracks the spawning of different activities across different threads, processes or even applications. This can be used for linking a background process activity with the web request that triggered it, or for complex interactions between processes in Erlang OTP applications.

Metadata

Both log entries and activities can be enriched with arbitrary metadata. For example, a web request can be indexed with all the query parameters sent by the client, allowing for easy lookup of a request based on any of its parameters; or a modification to a sensitive resource in the application can be logged with detailed information on the user who altered it, thus using Poirot as an audit trail as well. Poirot indexes all metadata by default, and relies con the power of ElasticSearch queries to provide easy search functionality.

Storage

All data is stored in ElasticSearch indices. Poirot automatically creates one index per day, allowing for easy rotation of indices by making use of ElasticSearch snapshots. Each log entry is indexed with common fields such as @message, @pid, @level, @source, @timestamp and @activity; while applications keep track of a @description, @pid, @source, @start and @end, as well as any other metadata set by the client applications.

Libraries

Poirot libraries provide loggers or visualisation tools, currently for Rails and Erlang applications.

Rails

Poirot Rails is a gem that configures an additional logger that pushes log entries via ZeroMQ to a target receiver for indexing, which can be easily configured. The ZMQ protocol is very lightweight, and though it cannot guarantee delivery of all log entries to the receiver, it introduces hardly any performance penalty to the overall application.

This gem also provides useful methods for managing activities and manually adding metadata, and injects Rack middleware to automatically wrap all web requests in an activity. If you are using BERT for communicating your Rails app with an Erlang application, this library also includes a PoirotRails::BertService wrapper to the BERT service that automatically links activities spawned in Erlang processes with the Rails action that triggered them.

Erlang

Poirot Elang doubles as a logger and a receiver. This means that it can be used within a larger Erlang application as an additional lager logger to push log entries to a Poirot receiver, or as a standalone process that receives log entries from Poirot Rails or Erlang loggers via ZeroMQ and indexes them in ElasticSearch.

It can also be configured to act as both a logger and a receiver within the same application, in which case log entries are pushed to the receiver Erlang process as standard Erlang messages, and not via ZMQ.

As in the Poirot Rails library, the Erlang library also provides methods for easily spawning new activities and enriching them with arbitrary metadata.

Go Receiver

Poirot Receiver, written in Go, is a version of the receiver that listens for log entries pushed via ZMQ and indexes them in ElasticSearch. It has been deprecated in favour of the Poirot Erlang receiver.

Frontend

Poirot web frontend is a Rails application that provides easy querying of both log entries and activities, and a detailed visualisation of all the entries involved in an activity, as well as the interaction between the processes across which the activity was spanned.

Hercule

Hercule is a gem that provides models for log entries and activities, as well as useful methods for querying them over the ElasticSearch backend. It is used in the Poirot web frontend, but it can also be included in any Rails app that intends to provide a custom visualisation of the indexed Poirot information.

Deployment

Poirot cookbook is a Chef cookbook that includes recipes for deploying both the Erlang Receiver as a standalone application and the web frontend as a regular Rails app behind an Apache web server.