Customizing output format

Ref #573, #565, #553, #456, #453, #402, #578, #526, #525, #488

Right now it’s very clear that debug takes a subjective stance on its output format. This is unsuitable for a variety of use-cases, especially the disparity between the isatty(2) == 0 and == 1 cases.

Let’s figure out how to solve this.

---

My initial knee-jerk idea would be to introduce a DEBUG_FORMAT environment variable. It would accept a string with delimiters similar to date-time or printf formats that indicate different elements of a debug log.

This would also remove the need for a plethora of custom environment variables that have been proposed.

We’d have a default format that would then be the same between interactive/non-interactive TTY sessions (fd 2, as always).

This would look something like

DEBUG_FORMAT="%N %m %D"

Where %N is the namespace (colored if interactive terminal), %m is the message and %D is the time diff - the exact format in the screenshot in the readme.

Of course there would be other delimiters available, and the above doesn’t necessarily need to be the default, but it would solve pretty much any use-case imaginable regarding the output format in a non-subjective manner.

---

That’s just my personal proposal, but this RFC is after any solution, so if you have a different idea please sound off below.

[Joshfindit]

I’m honestly only in this thread because I want debug to stop automatically returning seconds and instead always return milliseconds.

  ChannelChecker getting channel_id 1656344628 +2ms
  ChannelChecker getting channel_id 891441386 +2ms
  ChannelChecker getting channel_id 2042650534 +1ms
  ChannelChecker getting channel_id 1015526937 +3ms
  ChannelChecker getting channel_id 1649651584 +2s
  ChannelChecker getting channel_id 815734771 +2ms
  ChannelChecker getting channel_id 388112384 +1ms
  ChannelChecker getting channel_id 1290004369 +3ms
  ChannelChecker getting channel_id 1247374628 +1ms
  ChannelChecker getting channel_id 2020239812 +3ms
  ChannelChecker getting channel_id 969553134 +3ms

It’s easy to miss that one call took 1000x longer.

[Qix-]

Referring to https://github.com/visionmedia/debug/issues/442#issuecomment-443757866 and #442 in general, asking for a JSON output format:

const debug = require('debug')('rest:debug:myEndpoint', {output: 'JSON'})

Definitely not - the end consumer of the application should have full control over the output format. This would result in many different output formats, which would make this library useless to most people.

DEBUG=*;format:JSON node myScript.js

This would be a breaking change as it’s using namespaces for something they aren’t designed to do.

---

In reality, you could argue that prefixing J to any one flag would run it through JSON.stringify().

For example, if %m is the message, then %Jm is the message passed through JSON.stringify().

It’s not uncommon to prefix flags for extended functionality, so this wouldn’t be breaking ‘the UNIX way’ either.

You’d then have something like the following, giving you guaranteed valid JSON output.

DEBUG_FORMAT='{"message": %Jm, "time": %J{...}, "delta": %J+}'