Improve debug libp2p documentation

[vasco-santos]

There were several libp2p users having trouble with "silent" errors, like silent errors dialling incorrect bootstrap addresses (like: ws multiaddr pointing to a tcp port).

Users can enable debug mode by:

• Browser: in console localStorage.debug = 'libp2p:*
• Node: run node with DEBUG=libp2p:*

We should document that we use the debug module and that it can be used for debugging purposes for libp2p.

My suggestion is to create a FAQ document where we will be adding the most common questions libp2p users might have, and include there "How to debug".

@jacobheun what do you think?

[vasco-santos]

Also, should we document the debug strings? Perhaps we should have some structure on it like: libp2p:transport:...

[jacobheun]

@vasco-santos yes I think this would be helpful, and including some common debug string combos could be really helpful. Additionally, we may want to add the debug strings of each module to their respective readme/api docs to make it easier for folks to find specific ones.

Some example combo strings I use:

• All of libp2p minus noise and mplex (they're busy logs): DEBUG=libp2p*,-libp2p:mplex*,-libp2p:noise*
• Only errors: DEBUG=*:error

[vasco-santos]

I wrote a small proposal so that we can iterate on this

Format

We should have a more rigid format for libp2p modules, which can enable logging easily for each libp2p components.

We can start by a standard where each interface exports its debug string (its name per https://github.com/libp2p/js-libp2p-interfaces/tree/master/src). These exported strings should be concatenated with the implementation naming. As an example: libp2p transport interface should export a debugString = ‘libp2p:transport”, and its implementations would create their debug string as ${interface.debugString}-tcp.

We can even go a step forward and try to also bind libp2p core components with the logic aboce whenever possible. As an example, we can have components like the connectionManager and transportManager to have debug strings in the interface namespace scope: ${interface.debugString}-manager or ${interface.debugString}-core-manager . I am not yet sold to this idea, but if we find a good pattern this could be considered.

Also, we can leverage this opportunity to also tidy up the usage of module.tag vs Transport[Symbol.toStringTag]. We should uniform every thing under an exported Tag (transports need to be updated, discovery already do this). This exported Tag should be equal to the logging string part that represents the log, in order to keep everything consistent.

This will be a “breaking change” in the logs string and in the transports where people rely on the Transport[Symbol.toStringTag]. However, if we keep the same string as Transport[Symbol.toStringTag] in the log+tag, this won’t be problematic by itself. We should do the breaking change release anyway, just for the sake of the log string.

Finally, the README each module should have a debug section with its underlying debug strings, aiming to enable users to do more custom logging without the need to look into the codebase/all logs.

FAQ.md

In the context of the FAQ, I suggest we create “areas” within the document, starting by the “Debug” area. The 3 main questions seem to be:

• How can I debug libp2p?
  • Guidelines to debug module + Node.js / Browser examples
• How is libp2p debug structured?
  • Explain how libp2p debug strings are structured, similar to the above proposal
• What are the most common libp2p debug queries?
  • @jacobheun 's combo strings in Improve debug libp2p documentation #762 (comment)

Let me know your thoughts

We should also consider if we want to do: #378