litemetric guide

The Litemetric guide

Litemetric, a part of Litestack, is a low overhead, simple and generic telemetry tool that collects runtime data about Ruby and Rails applications.

Litemetric, as other components in Litestack is built on top of SQLite. It uses the embedded database engine to store and query telemetry data. As a result, Litemetric is a very low maintenance system. There is no need to setup/maintain/monitor any service aside from the application that integrates Litemetric.

Litemetric follows a simplistic approach where it tries to Nprovide easy enough APIs to cover most of the needed cases for event acquisition and measurement. It does not attempt to be an elaborate performance monitoring system. Still, it can be sufficient for many application needs, zero administrative overhead is a plus!.

Litestack components (e.g. Litejob, Litecache, Litecable) can optionally use Litemetric to report on usage and performance.

Features & Roadmap

• Capture single/multishot events
• Measure single/multishot events
• Snapshot information capturing
• In memory aggregation
• Background aggregator
• Background garabage collector
• Thread safety
• Async/Fiber Scheduler integration
• Graceful shutdown
• Fork resilience
• Polyphony integration
• Web reporting interface

How to use Litemetric?

For any class for which you need to collect metrics just include the Litemetric::Measurable module. Then we can set a unique identifier for the class by overriding the #metrics_identifier method.

Capturing and measuring events can then happen whenever required in the object methods.

# note that we only need to require litestack
# you could still do require 'litestack/litemetric'
class ImportantClass
  include Litemetric::Measurable

  # override the default identifier
  def metrics_identifier
    self.class.name
  end

  # the captured action will only be counted
  # the database will have a count of times the event was captured
  def simple
    # do something
    capture("simple")
  end

  # the measured action will also capture the runtime of the action
  # the database will have a count of times the event was measured and the total time measured
  def complex
    measure("complex") do
      # do something
    end
  end

Events can optionally have keys, to be able to differentiate them, here is an example that uses both event and key names when reporting a metrics:

class Ticker
  def change(symbol, value)
    capture("change", symbol, value)
  end
end

This will results in each symbol being unique in the metrics database, such that it can be reported on alone or in aggregation with other symbols under the same "change" action.

Sometimes an action needs to be report on multiple keys at the same time. Like for example when you need to report job insertion rate for each named queue and for all the queues at once. Litemetric provides a simple way to achieve this

  # capture multiple events in one shot
  def enqueue(queue_name, job)
    # do the action
    capture("enqueue", ["all", queue_name])
  end

  # also with measurement
  def perform(queue_name, job)
    measure(perform, ["all", queue_name]) do
      # do the action
    end
  end  

The above results in two entries being captured/measured, one for the specific queue and one that aggregates over all queues.

Configuring Litemetric

Litemetric looks for a litemetric.yml file in its working directory, the syntax and defaults for the file are as follows:

The db path should preferably be outside of your application folder, in order to prevent accidental overrides during deployment

Enabling metric collection for Litejob & Litecache

In their respective configuration files, you need to add this directive:

 metrics: true # default is false

Viewing metrics

TODO