CLI tool for running Whodunit investigators
Last updated 3 months ago by kengoodridge .
BSD-2-Clause · Repository · Original npm · Tarball · package.json
$ cnpm install @whodunit/pi 
SYNC missed versions from official npm registry.

What's Whodunit?

Whodunit helps you to investigate application issues, providing a framework for troubleshooting production environments.

To do so, we provide an [investigator ecosystem]. An investigator is basically a plugin that can be run with the pi command to troubleshoot your production environment.


# install pi
npm install --global @whodunit/pi

# install an investigator
npm install --global investigator-ipauth

# run it
pi ipauth

You can also run a local investigator on your computer as such:

# Running a local investigator
pi ./path/to/local/investigator


  • --no-color - Disable colors.
  • --version - Print the current pi version.
  • --help - Print pi help menu with the list of found investigators.
  • --investigators - Print available investigators.


An investigator basically runs a decision tree or flow diagram to isolate issues to a root cause.

+---------------------+  yes   +----------------------------+  yes
|  isIPAuthenticated  +------->+isSecondGatewayAuthenticated+-------> ipWorking
+----------+----------+        +----------------------------+
           |                                 |no
           |                                 v
           |no                     sessionCacheNotWorking
     +-----+---+       no
     |isIPKnown+---------------> ipNotKnown
 +--------+-----------+    yes
 |isCustomerSubscribed+-----------> defectInGateway

You write Investigations and Conclusions, then you link them together in an Investigator.

  • Investigations - Answer yes or no questions about system conditions.
  • Conclusions - A description of your findings and recommended actions.
  • Investigator - Links Investigations and Conclusions to form a decision tree.
investigate() {
    const { isIPKnown, isCustomerSubscribed, 
        isIPAuthenticated, isSecondGatewayAuthenticated } 
        = this.investigations;
    const { ipNotKnown, customerNotSubscribed, sessionCacheNotWorking, 
        ipWorking, defectInGateway } 
        = this.conclusions;




    return this.start(isIPAuthenticated);

An example of an investigation looks like this...

module.exports = class extends Investigation {
    async investigate(yes, no) {
        const ipAuthService = await getEurekaInstance(ipAuthAppName, this.props.env);

        if (!ipAuthService) {
            this.props.message = chalk.redBright(`Unable to get instance for ${ipAuthAppName} from eureka!`);

        try {
            const url = `${ipAuthService}ipauthmiddle/authenticate`;
            const ip = {
                ipAddress: this.props.ip
            this.log(`Trying ${url} for ${this.props.ip}`);
            const { status, data } = await axios.post(url, ip);

            if(status === 200 || no(`${this.props.ip} is unknown IP`)) {
                this.props.custGroup = `${data.custId}.${data.groupId}`;
                yes(`${this.props.ip} is known IP: custGroup=${this.props.custGroup}`);
        } catch (err) {
            no(`${this.props.ip} is unknown IP: ${err.message}`);

An example of a conclusion looks like this...

module.exports = {
    ipNotKnown: {
        text: "IP is not known",
        details: "Either the IP range is not configured in Admin for ${props.ip} " +
        "or the configuration is failing to sync to the IPAuthentication service.",
        recommendations: [
            "Check in admin to see that the IP range should include ${props.ip}",
            "Contact [ArtfulDodgers](mailto:Med.ArtfulDodgers@ebsco.com) with these findings.",
            "Development should check that the IPAuthentication sync process",
        status: "fail"

Why derive Whodunit from Yeoman?

Whodunit uses a fork of the Yeoman framework for code generators, except Whodunit shares investigators instead.

  • Yeoman provides a proven ecosystem for code generators that now includes over 8000 generators, 9000 github stars and 37000 weekly downloads. Its architecture is a major reason for the success of the ecosystem.

  • Yeoman was created by engineers at Google.

  • The plugin design allows an investigator to run in different environments. Developers can write once and use many different ways. For example

    • CLI
    • Native UI
    • Web Site
    • End-to-end tests
    • Synthetic transactions
    • Self-documenting runbook or playbook
    • Focused investigators can be reused by broader investigators. For example, an investigator package can be created for each micro-service and the gateway can implement an investigator that reuses those investigators to isolate the root cause of an authentication issue.
  • Uses npm to publish and discover investigator packages.


BSD-2-Clause © Google (Original Author of yeoman) © Ken Goodridge (Derived from yeoman)

Current Tags

  • 1.0.7                                ...           latest (3 months ago)

3 Versions

  • 1.0.7                                ...           3 months ago
  • 1.0.4                                ...           3 months ago
  • 1.0.3                                ...           3 months ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (34)
Dev Dependencies (9)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |