A tool for detecting barely used code in production
Switch branches/tags
Nothing to show
Clone or download

README.rdoc

Scythe

DESCRIPTION:

Scythe is a light-weight tool for detecting dead and infrequently used code in production.

Scythe defines a set of functions (probes) that you can call from your application. When they are executed they record the time and date they were called.

A command line utility shows you how long it has been since each probe was called. You can use this information to make an informed decision about whether to attempt to delete code or do further analysis.

FEATURES/PROBLEMS:

  • Currently supports Java, Python 3.x and Ruby

SYNOPSIS:

To use Scythe, place calls in your code of the following form

scythe_probe("probe_name")

probe_name should be a unique string consisting of alphanumerics and underscores. When this call is made in your code the time and date of the call will be recorded. Code for probes in all supported languages is in the probe directory.

Scythe becomes aware of these probes when you call it at the console with the gather option (-g) and a directory path:

scythe -g .

Scythe will recursively iterate over all source files in the specified directory and record the addition of any probe calls. Ideally, scythe -g should be run as part of your build.

To see how long it has been since individual probes have been called run scythe with the -s option. Scythe will produce a list of all probes along with the number of days since they've been called.

By default, -s produces its report in days. You can use hours and secs as options as well to get more precise output:

scythe -s secs

If you want to delete a probe, pass its name to Scythe with the -d option:

scythe -d <probe_name>

Scythe returns an error code of 0 on success and 1 on all other errors.

PROBE CALLS:

For simplicity of implementation only two forms are supported for probe calls: the name scythe_probe followed by an identifier ([A-Za-z0-9_]+) in double quotes, or scythe_probe followed by an open paren, identifier in double quotes, and a close paren.

This pattern works for all of the languages Scythe currently supports. Handling single quote strings and other string forms for languages that support them would complicate processing.

FUTURE DIRECTIONS:

  • Support for other languages (Javascript, C, C# etc)

  • Record number of calls and stack traces

  • statsd support

INSTALL

No bundler or gems. Clone the repository:

git clone https://github.com/michaelfeathers/scythe.git

Add scythe/lib to your path

export PATH=$PATH:<directory where scythe is installed>/scythe/lib

Set an environment variable named SCYTHE_PROBE_DIR to a location where the scythe probe history information will reside. This environment variable will be used by the scythe_probe calls.

export SCYTHE_PROBE_DIR=<your probe directory>

Run scythe -h to see command line options

REQUIREMENTS:

  • Ruby >= 2.3.0

  • OPTIONAL: Python 3.x to use the python probe

  • OPTIONAL: Java 7+ to use the Java probe

LICENSE:

(The MIT License)

Copyright © 2016 Michael Feathers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.