SYNOPSIS¶ ↑

pencil: graphite dashboarding frontend

pencil is a monitoring frontend for graphite. It runs a webserver that dishes out pretty graphite urls in hopefully interesting and intuitive layouts.

Some features are:

• Implicit collection of host and cluster data

  pencil picks these up from graphite without you having to explicitly define them. You need only supply the metrics; see SETUP for configuration details.

• Relative and absolute timespecs with auto-refresh

  Timeslices are measured in terms of a (possibly relative) starting time and a duration. Timespecs are parsed using the chronic and chronic_duration gems.

• permalinks

  Turn a relative timeslice (such as the last 8 hours) into an absolute one for placing in bug reports and all sorts of other useful things.

• Lots of navigation UI for bouncing around the different views

INSTALL¶ ↑

Eventually it should just be:

gem install pencil

…but it isn’t yet.

Dependencies are:

• rack

• sinatra

• json

• chronic

• chronic_duration

• (fixme versions)

SETUP¶ ↑

You should have a working graphite installation. Your metrics need to be composed of three pieces:

• “%m”, METRIC (the common part of each graphite path)

• “%c”, CLUSTER (cluster name, varies with query)

• “%h”, HOST (host name, varies with query)

The :metric_format string is specified in the configuration file (see below), and defaults to %m.%c.%h“.

You need to set up some YAML configuration files in order for pencil to work. Pencil searches the current directory (or, with -d DIR, DIR) for YAML files to load.

The important top-level configuration keys are:

• :config: general config options

• :graphs: see below

• :dashboards: see below

See examples/ for an example configuration directory. Here’s examples/pencil.yml, which contains general configuration options:

:config :

:graphite_url : URL # graphite URL
:url_opts :
  :width : 1000
  :height : 400
  :fontSize : 15
  :start : "8 hours ago"  # in chronic timespec format
  :template : "noc"
  :yMin : 0
  :margin : 5
  :thickness : 2

:refresh_rate : 60        # how often to refresh the view
:host_sort : "numeric"    # add this if you want to sort hosts numerically
:quantum : 30             # map requests to 30 second intervals
:date_format : "%X %x"    # strftime
:metric_format : "%m.%c.%h" #%m metric, %c cluster, %h host

A graph is a name, title, collection of targets, and some other options. It looks like (in YAML):

graph_name:             # name pencil references this graph by
  title: "graph_title"  # title displayed on graph
  targets:              # list of graphite targets
    metric.1:
      :key : key         # key displayed on the legend for this metric
      :color : color     # color on the graph for this metric
    metric.2:
      :key : key
      :color : color
    [...]
  stack: true           # whether to stack or not
  hosts: ["hosts1*", "test*_web", "hosts2*"] # filter on hosts

fixme A target is a metric or list of metrics and associated graphite options.

Similarly, a dashboard is a name, title, collection of graphs, and some other options. It looks like (in YAML):

dash_name:
  title: dash_title
  graphs:
    - graph1:
      hosts: ["sync*_web"] # additional hosts filter specific to this graph
      other_opt: val       # possibly other options in the future
    - graph2:
    [...]
  hosts: ["filter1*", "*filter2"]

complex metrics and dashboard graph-level options¶ ↑

FIXME document

RUNNING THE SERVER¶ ↑

Once you’ve set up the configs, you should be able to just run

pencil

and get something up on localhost:9292

From there you should be able to click around and see various interesting collections of graphs.

With no options, pencil looks for ./pencil.yml as the default config file.

You can bind to a specific port with -p PORT and specify a configuration directory with -d DIR. Other rack-related options will be added at some point in the future.