/ 
Sparrow-0.0.24
River stage zero No dependents
/ Sparrow

NAME

Sparrow

![Build Status](https://travis-ci.org/melezhik/sparrow.svg)

SYNOPSIS

Sparrow - outthentic plugins manager. Manages outthentic family suites.

CAVEAT

The project is still in very alpha stage. Things might change. But you can start play with it :-)

Install

$ sudo yum install git
$ sudo yum install curl # skip this if you are not going to use private sparrow plugins
$ cpanm Sparrow

Glossary

Outthentic DSL

Outthentic is a word combined from two parts - `out' and `authentic', meaning that a program prints something into stdout and and someone proves program "authenticity" (correctness) by matching output for some rules defined in terms of Outthentic DSL - is a language to verify, analyze unstructured text output.

Follow Outthentic DSL to for details.

Outthentic suites

Outthentic suites are small scenarios based on Outthentic DSL to provide solutions for various testing, monitoring, reporting tasks from checking available disk space to ensuring that your web server is healthy.

There are 2 type of outthentic suites - swat and generic. Read further.

Sparrow plugins

Sparrow plugins are shareable outthentic suites distributed via outthentic suites repository - SparrowHub. Term plugins refers to the idea of different outthentic suites could be pluggable and so get used on single machine via a unified interface of sparrow console client. It is very close to the conception of CPAN modules in Perl or ruby gems in Ruby.

SparrowHub

SparrowHub is a central repository of sparrow plugins.

Sparrow tool

sparrow is a console client to search, install, setup and finally run various sparrow plugins. Think about it as of cpan client for CPAN modules or gem client for ruby gems.

Two types of sparrow plugins

There are tow types of outthentic suites or sparrow plugins:

  • Swat test suites

  • Generic suites

Swat test suites

Are those based on swat web application testing framework. Swat is in turn based on Outthentic DSL. Swat test suites are dedicated to web application testing.

Generic suites

Are those based on outthentic - generic purposes testing / monitoring framework. Outthentic framework is in turn based in Outthentic DSL.

Generic suites unlike swat test suites is generic purposes suites for various tasks, like monitoring processes in process list or investigating log entries.

Sparrow basic entities

Basically user deal with 3 type of entities:

Plugins

A sparrow plugins which you search, install, configure and run. As already told, usually plugin is a small testing, monitoring, reporting suite to solve a specific issue. For example check available disk space or ensure that service is running. There are a plenty of plugins at SparrowHub.

Checkpoints

Checkpoint is configurable sparrow plugin. Some plugins does not require configuration and could be run as is, but many ones require some piece of input data. For example hostname of application being checked or supplemental parameters to adjust plugin logic. Thus, checkpoint is a container for:

  • plugin

  • plugin configuration

Plugin configuration is just a text file in one of 2 formats:

  • .ini style format

  • YAML format

Plugin configuration will be explain latter.

Projects

Projects are logic groups of sparrow checkpoints. It's convenient to split a whole list of checkpoint to different logical groups. Like one for system checks - disk available space or RAM status, other for web servers status, so on.

API

Now having a knowledges about basic sparrow entities let's dive into sparrow API provided by sparrow console client.

Projects API

Sparrow project is a logical group of sparrow checkpoints. To create a project use sparrow project create command:

sparrow project create $project_name

Command examples:

# system level checks
$ sparrow project create system

# web servers checks
$ sparrow project create web-servers

To get project information say this:

sparrow project show $project_name

For example:

$ sparrow project show system

To get all projects list say this:

sparrow project list

To remove project data say this:

sparrow project remove $project_name

For example:

$ sparrow project web-servers remove

Note - this command will remove all checkpoints related to project as well!

Search plugins API

Sparrow plugin is a shareable outthentic suite.

One could install sparrow plugin and then run related outthentic scenarios, see check action for details.

To search available plugins use sparrow plg search command:

sparrow plg search $pattern

For example:

# list all available plugins
$ sparrow plg search 
  
# find foo-* plugins
$ sparrow plg search foo

Search pattern should be perl regular expression. Examples:

  • .* # find any plugin

  • nginx # find nginx plugins

  • mysql- # find mysql plugins

Sparrow index API

Sparrow index is cached data used by sparrow to search plugins.

Index consists of two parts:

  • private plugins index , see SPL file section for details

  • public plugins index, PUBLIC PLUGINS section for details

There are two basic command to work with index:

  • sparrow index summary

This command will show timestamps and file locations for public and private index files.

sparrow index update

This command will fetch fresh index from SparrowHub and update local cached index.

This is very similar to what cpan index reload command does.

You need sparrow index update to get know about updates, changes of SparrowHub repository. For example when someone release new version of plugin.

See public plugins section for details on sparrow public plugins and SparrowHub.

Installing sparrow plugins

sparrow plg install $plugin_name

For example:

$ sparrow plg search  nginx        # to get know available nginx* plugins
$ sparrow plg install nginx-check  # to download and install a chosen plugin
$ sparrow plg install swat-mongodb-http --version 0.3.7 # install specific version

Check sparrow-plugins section to know more about sparrow plugins.

To see installed plugin list say this:

sparrow plg list

To get installed plugin information say this:

sparrow plg show $plugin_name

To remove installed plugin use sparrow plg remove command:

sparrow plg remove $plugin_name

For example:

$ sparrow plg remove df-check

Checkpoints API

To create a checkpoint use sparrow check add command:

sparrow check add $project_name $checkpoint_name

Checkpoints are parts of projects, so to create a checkpoint you always have to point a project.

Command examples:

$ sparrow check add web-servers nginx
$ sparrow check add system disk

Setup checkpoints

By setting checkpoint you:

  • bind checkpoint to sparrow plugin

  • (optionally) set hostname parameter for sparrow plugin

sparrow check set command is used to set checkpoint:

sparrow check set $project_name $checkpoint_name $plugin_name [$hostname]

Hostname is optional parameter to set base url or hostname of a web service or application being tested.

Command examples:

# bind nginx checkpoint to swat-nginx plugin
sparrow check set webservers nginx swat-nginx  

# bind nginx checkpoint to swat-nginx plugin, explicitly sets hostname to 127.0.0.1
sparrow check set webservers nginx swat-nginx 127.0.0.1

# the same as above but for remote nginx server, hostname 192.168.0.1
sparrow check set webservers nginx-remote swat-nginx  192.168.0.1

# bind mysql-server to outth-mysql plugin and sets mysql server address
sparrow check set db-servers mysql-server outth-mysql 127.0.0.1:3306

# bind mongo checkpoint to swat-mongodb-http plugin and sets mongodb http API URL
sparrow check set db-servers mongo swat-mongodb-http http://my.server:28017/mongoAPI

Running suites

There are two ways to run outthentic suites:

First one is to run suite via checkpoint interface:

sparrow check run $project_name $check_name [ -- runtime-parameters ]

For example:

$ sparrow check run system disk

Second way is simply run tests via plugin interface, in this case you do not need a checkpoint at all to run a suite, because you run it as is. The back side of this approach you rely on default plugin configuration and can't define your own one:

sparrow plg run $plugin_name

$ sparrow plg run df-check # this suite will run with default values for disk.threshold parameter

  • Choose checkpoint interface when you want to add some specific settings for outthentic suite.

  • Choose plugin interface when you have no host specific settings for suite and default settings are just enough for you. Notice that many sparrow plugins still require a specific configuration and can't be run this way.

  • Only public plugins could be run using plugin interface.

Setting runtime parameters

It is possible to pass whatever runtime parameters when invoke plugin run via checkpoint interface.

$ sparrow check run system disk -- --param disk.threshold=60

Runtime parameters override default parameters values set in checkpoint configurations, see configuring checkpoints later.

Running suites with cron

When running suite under cron it is handy only have an output if something goes wrong, f.e. test suite failed or something else goes bad. Use --cron flag to enable this behavior:

sparrow check run $project_name $check_name --cron

Running checkpoint with --cron flag suppress a normal output and only emit something in case of failures.

Example:

$ sparrow check system disk --cron # pleas keep quite if disk space is ok

Configuring checkpoints

Checkpoint configuration is a configuration data consumed by plugin binded to checkpoint. One have to consult plugin documentation ( for public plugins - this is SparrowHub site ) to get know the structure of configuration data to feed.

Sparrow support two configuration formats:

  • .ini

  • YAML

.Ini style format is default format for checkpoint configuration.

Use check ini command to set checkpoint configuration:

sparrow check ini $project_name $checkpoint_name

For example:

$ export EDITOR=nano

$ sparrow check ini system disk

    [disk]
    # disk used threshold in %
    threshold = 80

Having this sparrow will save plugin configuration in the file related to checkpoint and will use it during checkpoint run:

$ sparrow check run system disk # the value of disk.threshold is 80

User also could copy existed configuration from file using check load_ini command:

sparrow check load_ini $project_name $checkpoint_name /path/to/ini/file

For example:

$ sparrow check load_ini system disk /etc/plugins/disk.ini

To get checkpoint configuration use sparrow check show command:

sparrow check show $project_name $checkpoint_name

For example:

$ sparrow check show webservers nginx

Alternative way to configure sparrow checkpoint is to load configuration from yaml file during checkpoint run:

$ cat disk.yml

---
disk
  threshold: 80

$ sparrow check run system disk --yaml disk.yml

While sparrow check ini/load_ini command saves checkpoint configuration and makes it persistent, sparrow check run --yaml command applies checkpoint configuration only for suite run and could be treated as runtime configuration.

For common usage, when user runs checkpoints manually first approach is more convenient, while second one is a way automatic, when checkpoints configurations are kept as yaml files and maintained out of sparrow scope ( f.e. by other configuration management tools ) and thus further applied during checkpoint run.

More information on outthentic suites configurations could be found here:

Removing checkpoints

Use this command to remove checkpoint data from project container:

sparrow check remove $project_name $checkpoint_name

Examples:

# remove checkpoint nginx from project web-servers
$ sparrow check remove web-servers nginx

Sparrow plugins

Sparrow plugins are shareable outthentic suites installed from remote sources.

There are two type of sparrow plugins:

  • public plugins are provided by SparrowHub community plugin repository and considered as public access.

  • private plugins are provided by internal or external git repositories and not necessary considered as public access.

Both public and private plugins are installed with help of sparrow client:

sparrow plg install plugin_name

Public plugins

The public plugins features:

  • they are kept in a central place called SparrowHub - community plugins repository.

  • they are versioned so you may install various version of a one plugin.

Private plugins

Private plugins are ones created by you and not supposed to be accessed publicly.

The private plugins features:

  • they are kept in arbitrary remote git repositories ( public or private ones )

  • they are not versioned, a simple `git clone/pull' command is executed to install/update a plugin

  • private plugins should be listed at sparrow plugin list file (SPL file)

SPL file

Sparrow plugin list is represented by text file placed at `\~/sparrow.list'

SPL file should contains lines in the following format:

$plugin_name $git_repo_url

Where:

  • git_repo_url

Is a remote git repository URL

  • plugin_name

A name of your sparrow plugin, could be arbitrary name but see restriction notice concerning public plugin names.

Example entries:

swat-yars   https://github.com/melezhik/swat-yars.git
metacpan    https://github.com/CPAN-API/metacpan-monitoring.git

Once you add a proper entries into SPL file you may list and install a private plugins:

$ sparrow plg show    swat-yars
$ sparrow plg install swat-yars

Create sparrow plugin

Here is a brief description of the process:

Swat test suites

To get know to create swat tests please follow swat project documentation - https://github.com/melezhik/swat.

A simplest swat test to check that web service returns `200 OK' when receive `GET /' request will be:

echo 200 OK > get.txt

create a cpanfile

As sparrow relies on carton to handle perl dependencies you need to create a valid cpanfile in the plugin root directory.

The minimal dependency you have to declare is swat perl module:

$ cat cpanfile

require 'swat';

Of course you may also add other dependencies your plugin might need:

$ cat cpanfile

require 'HTML::Entities'

create sparrow.json file

Sparrow.json file describes plugin's meta information required for plugin gets uploaded to SparrowHub.

In case of private plugin you may skip this step.

Create sparrow.json file and place it in plugin root directory:

{
    "version": "0.1.1",
    "name": "my-cool-plugin",
    "engine": "swat", 
    "description" : "this is a great plugin!",
    "url" : "http://...."
}

This is the list of obligatory parameters you have to set:

  • version - perl version string.

A detailed information concerning version syntax could be find here - https://metacpan.org/pod/distribution/version/lib/version.pm

  • name - plugin name.

Only symbols `a-zA-Z1-9_-.' are allowable in plugin name

This the list of optional parameters you may set as well:

  • engine

Defines framework for suite. Default value is `swat'. Other possible value is 'generic', see generic suites section

  • url - an http URL for the site where one could find a detailed plugin information ( docs, source code, issues ... )

  • description - a short description of your plugin

Generic suites

Creation of generic suites is very similar to a swat test suites, but you'd better read outthentic framework documentation to understand the difference.

Once your suite is ready add the same metadata as with swat test suite:

  • cpanfile

  • sparrow.json

Cpanfile should declare at least a dependency on Outthentic perl module:

$ cat cpanfile

require 'Outthentic';

Sparrow.json file does not differ from the one described at swat test suite section, except for `engine' field value:

{
    "engine": "generic"
}

Publishing sparrow plugins

Private plugin

  • All you need is to keep a plugin source code in the remote git repository.

  • Plugin root directory should be repository root directory.

  • Once a plugin is placed at git remote repository you need to add a proper entry into SPL file, see SPL FILE section how to do this.

Public plugin

To publish you plugin into SparrowHub you need:

  • Get registered at SparrowHub

Go to https://sparrowhub.org

  • Get rest api token

Login into your account. Go on "Profile" page, then on "My Token" page and then hit "Regenerate Token" link.

Once your get you token, setup a sparrowhub credentials on the machine where your are going upload plugin from:

$ cat ~/sparrowhub.json

{
    "user"  : "melezhik",
    "token" : "ADB4F4DC-9F3B-11E5-B394-D4E152C9AB83"
}

  • Upload plugin

    • Check if you have sparrowhub credentials setup correctly ( previous step ) on your machine

    • Install sparrow client on your machine

    • Then go to directory where your plugin source code at and say `sparrow plg upload'. That's it

For example:

$ cd plugin_root_directory
$ sparrow plg upload

Another way to supply sparrow with valid SparrowHub credentials - use sph_user and sph_token environment variables. Probably useful in automation scripts:

$ sph_user=melezhik sph_token=ADB4F4DC-9F3B-11E5-B394-D4E152C9AB83 sparrow plg upload

AUTHOR

Aleksei Melezhik

Home page

https://github.com/melezhik/sparrow

Copyright

Copyright 2015 Alexey Melezhik.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See also

  • Outthentic - Generic testing, reporting, monitoring framework consuming consuming Outthentic::DSL.

  • Swat - Web testing framework consuming Outthentic::DSL.

  • Outthentic::DSL - Outthentic::DSL specification.

Thanks

To God as the One Who inspires me to do my job!