Use `debug` package to provide debugging information

[AuHau]

While working with this library I found out that it is rather hard to guess what is going wrong, when something is going wrong as there is no feedback about what is going on. This especially applies to higher level APIs that does some operations above simply translating the calls into axios calls.

I would therefore suggest implementing debug logging with debug that is pretty much industry standard and work both in node and browser.

[AuHau]

@ethersphere/js what are your thoughts on this? It would bring new dependency, but also bigger clarity. This especially relates to those modules that do not only wraps the API but have some of its own logic like SOCs or feeds.

[agazso]

What would be the proposed usage of this?

Currently we made the console logging functionality forbidden to avoid littering the code with debug messages. If I understand correctly by using this we would have a different way to add debug messages all over the code which kind of defeats the purpose of forbidding console logging.

[AuHau]

Yes, it is a similar thing yet it is not. console.log forces the output to stdout or browser console without the user's permission/request. debug package allows the user to display the output only if he desires (most probably something is not working and he's trying to understand what). On Node it is using setting DEBUG env. variable and in a browser using the local storage. It has more benefits like scoping the log entries which you can then filter out. Seeing time of executions between each log entries etc. It is a generally a widespread tool integrated in a lot of projects in JS community.

So the purpose is to give more information on what is going on in BeeJS internally for us or the user to understand what is going wrong.

[agazso]

I understand the concept of logging in general and I also understand the value of it in long running server processes where that's the only way to get information out of a running system.

What is not clear for me is what is the best practice of using debug logging in a library such as bee-js. Especially regarding what is the general guidelines on deciding to keep a debug output line in the code? How would we avoid having unnecessary debug instrumentation all over the code?

[AuHau]

Well, I would not call this logging in relation to server logging. It does not store anything in files and it has very much limited capabilities in compersion with something like Winston.

I am not aware of any guidelines or best practices for this. I have seen it used in many big projects like Mocha, libp2p, IPFS, Babel (I think) etc. Not sure if they have something like this defined.

Regarding polluting the code. I don't think it brings much overhead. I am not saying to log every function call, but to log the important actions that the code is performing. Mainly for staff that has some logic in it (Feeds, SOCs, PSS). This will be I guess up to the dev to assess what is important to log and then tweaked in review process. I would avoid having guidelines like "if you write new function put log entry in the beginning of the function body".

I think this will be important once users will hit some bugs/problems in the code, when you will be able to say "enable debug logging and gives the logs" in order to see what is going wrong.

[agazso]

I checked out Mocha, they are using it as part of outputting things to console when you run it from the command line, so that's a bit different approach.

I also checked out Libp2p and IPFS, they use it sparingly, almost only for reporting exceptions (IPFS also uses it for its command line runner debug output), see [1]. So to me it seems to me that the best practice is to not let debug output in the code (which is inline with what we are doing) only for errors, but as far as I understand that's not exactly what you are proposing here.

[1] An example search: https://github.com/ipfs/js-ipfs/search?q=debug

[nugaon]

I think this will be important once users will hit some bugs/problems in the code, when you will be able to say "enable debug logging and gives the logs" in order to see what is going wrong.

I think this is the only real reason to use this package. It seems like this pollutes the code, and you shouldn't call always print variable's value when a seemingly complicated operation happens. Then in what cases the debug must be called and with what kind of parameters? We always have to decide and think about what we should log? How much it can help to figure out the real problem usually when an issue happens? Does this extra overload (not only in term of package dependency) worth it?

IMO I wouldn't add any extra dependency for logging within this project. If you want to debug easily with tracking all scoped variables at a specific point of the running, use VSCode as we have a configuration already for this problem.

[AuHau]

@agazso haven't checked Mocha so can't really comment. But I have to object to your assessment of usage in IPFS. They usually instantiate it under log variable and then they use it for logging, for example, see how log is used here: https://github.com/ipfs/js-ipfs/blob/288a259b63a90d784a3f752e6331cd58cf32e746/packages/ipfs-core/src/components/files/cp.js

You can also check how I implemented it in rif-storage-js which is a very similar library to bee-js, although with a bit different architecture: https://github.com/rsksmart/rif-storage-js/blob/master/src/providers/ipfs.ts

Honestly, I can't really relate to your view on polluting code base with it, because IMO this actually goes well together of documenting code. The log messages then can nicely describe what is happening inside the code. Basically in some instances what you comment in code, can be instead logged. And I don't expect that the project will "double in size" because of this addition.

I am afraid I can't satisfy your desire to present you "rules how to log" as I was always doing it using my gut, but I am open to try to do research about it to set up some guidelines.

@nugaon thanks, but I don't use VSCode 🤪 😉

[agazso]

@agazso haven't checked Mocha so can't really comment. But I have to object to your assessment of usage in IPFS. They usually instantiate it under log variable and then they use it for logging, for example, see how log is used here: https://github.com/ipfs/js-ipfs/blob/288a259b63a90d784a3f752e6331cd58cf32e746/packages/ipfs-core/src/components/files/cp.js

The linked file seems to be the ipfs files cp command line tool, which to me falls under the category of command line runner debug output :)

I am afraid I can't satisfy your desire to present you "rules how to log" as I was always doing it using my gut, but I am open to try to do research about it to set up some guidelines.

Maybe it would be better to create an example PR where you could demonstrate how you would use this package and how does that solve a specific problem that you have?

[AuHau]

The linked file seems to be the ipfs files cp command line tool, which to me falls under the category of command line runner debug output :)

That is not true. This is in ipfs-core which is used by a few things not directly linked to IPFS CLI. The keyword cp might be bit misleading here. I believe this is actually run in Daemon behind the API.

Okay, I will try to assemble an example PR.