babel-plugin-shotgun-logs

Getting Started

npm install babel-plugin-shotgun-logs

And then configure your project to run with babel plugins (docs)

Example .babelrc:

[
  [
    "babel-plugin-shotgun-logs",
    {
      "functionNameBlacklist": [ "unimportantFunction" ],
      "functionNameBlackoutList": [ "functionName" ],
      "isTerminal": true,
      "entryLogShowFullArgs": false,
      "entryLogArgOutputInline": true,
      "entryLogMultilineJSONargs": false,
      "exitLogReturnOutputInline": true,
      "exitLogStubObjects": true,
      "timeProfiling": false,
      "storeJSONexternally": {
        "sizeThreshold": 10000,
        "location": "s3",
        "bucket": "deleteme-shotgun-log-json-test"
      }
    }
  ]
]

Plugin options:

General Options

- functionNameBlacklist (Default: [])

A list of functions not to include in the shotgun log output

- functionNameBlackoutList (Default: [])

A list of functions to log but NOT log any functions that get called by this function

🟢  main() {"arg1":{"key1":1,"key2":2},"arg2":5}
--🟢  a() {"arg1":{"key1":1,"key2":2},"arg2":5}
----🟢  y() {"arg1":{"key1":1,"key2":2},"arg2":5}
----🔴  y() ⇒ {"a":1,"b":2}
----🟢  z() {"arg1":{"key1":1,"key2":2},"arg2":5}
----🔴  z() ⇒ {"a":1,"b":2}
--🔴  a() ⇒ {"a":1,"b":2}
🔴  main() ⇒ {"a":1,"b":2}

When set to [ "a" ]:

🟢  main() {"arg1":{"key1":1,"key2":2},"arg2":5}
--🟢  a() {"arg1":{"key1":1,"key2":2},"arg2":5}
--🔴  a() ⇒ {"a":1,"b":2}
🔴  main() ⇒ {"a":1,"b":2}

- isTerminal (default: true)

Boolean flag if you are viewing the shotgun log output on the terminal. This option changes the way that emojis are displayed to have the correct spacing in the terminal

- fileSizeLimitMb (default: 500)

When the log file reaches this size, a new log file will be created and the previous log file will be deleted. NOTE: Log file format is log/shotgun.log.<unix_timestamp>

storeJSONexternally (Default: false)

Examples:

{
  sizeThreshold: 10000,
  location: 'local',
}

{
  sizeThreshold: 10000,
  location: 's3',
  bucket: 'bucket_name'
}

sizeThreshold (Default: 10000)

The size in bytes that JSON needs to exceed to be written externally rather than in the .log file

location (Default: 'local')

Options: ['local', 's3'] If local: files are written to log/json/ If s3: files are written to an S3 bucket. The bucket name needs to be specified in the object and the credentials need to be specified by the env variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY with permission to access the bucket specified

TODO: add other options for specifying S3 credentials

bucket

The bucket to upload JSON files to if they are larger than the threshold. Only used if location is set to s3.

Options For Modifying Entry Logs

Example default function entry log:
🟢 main( arg1: { ... }, arg2: 5 ) {"arg1":{"key1":1,"key2":2},"arg2":5}

- entryLogShowFullArgs (Default: true)

Logs all of the arguments & values to the function as JSON after the signature

When true:
🟢 main( arg1: { ... }, arg2: 5 ) {"arg1":{"key1":1,"key2":2},"arg2":5}

When false:
🟢 main( arg1: { ... }, arg2: 5 )

- entryLogMultilineJSONargs (Default: false)

Logs the arguments output as multiline JSON

When true:

🟢  main( arg1: { ... }, arg2: 5 ) {
  "arg1": {
    "key1":1,
    "key2":2
  },
  "arg2":5
}

When false:
🟢 main( arg1: { ... }, arg2: 5 ) {arg1:{"key1":1,"key2":2},"arg2":5}

- entryLogArgOutputInline (Default: true)

Displays the argument object on the same line as the signature

When true:
🟢 main( arg1: { ... }, arg2: 5 ) {"arg1":{"key1":1,"key2":2},"arg2":5}

When false:

🟢  main( arg1: { ... }, arg2: 5 )
{"arg1":{"key1":1,"key2":2},"arg2":5}

- entryLogSymbol (Default: 🟢 )

The symbol to use at the start of an entry log

Default:
🟢 main( arg1: { ... }, arg2: 5 ) {"arg1":{"key1":1,"key2":2},"arg2":5}

entryLogSymbol = $
$ main( arg1: { ... }, arg2: 5 ) {"arg1":{"key1":1,"key2":2},"arg2":5}

Options For Modifying Exit Logs

Example default function exit logs:

🔴  main() ⇒ {"a":1,"b":2}
🔴  main() ⇒ 10.5

- exitLogStubObjects (Default: false)

Stubs the return value output when it is an object (leaves the value the same when the return value is a different primitive)

When true:

🔴  main() ⇒ { ... }
🔴  main() ⇒ 10.5

When false:

🔴  main() ⇒ {"a":1,"b":2}
🔴  main() ⇒ 10.5

- exitLogReturnOutputInline (Default: true)

Outputs the return value in the same line as the function name

When true:

🔴  main() ⇒ {"a":1,"b":2}
🔴  main() ⇒ 10.5

When false:

🔴  main() ⇒ 
{"a":1,"b":2}
🔴  main() ⇒
10.5

- exitLogSymbol (Default: 🔴 )

The symbol to use at the start of an entry log

Default:
🔴 main() ⇒ {"a":1,"b":2}

exitLogSymbol = $
$ main() ⇒ {"a":1,"b":2}

- timeProfiling (Default: false)

Displays how long the function took to run

When true:
🔴 main() ⏱️ 1005.789 ms ⇒ {"a":1,"b":2}