Clarify documentation around transports, worker threads, and destinations

[JaneJeon]

Altering log objects/logging middlewares

As far as I can tell, there are several different ways to "alter" a log object (and by this I mean the object we pass into log.info()/warn()/whatever): redactions, transports, formatters, and serializers.

At times, it's difficult to figure out what to use where.

For example, say I want to remove req.params from every request that's logged. Do I use redaction or a serializer (with something like lodash/omit)?

Or say I'm an idiot and want to replace pino's built-in timestamp (so, 1. removing time property and 2. setting some customTime: new Date() on every request log). Do I use redaction + formatter or a transport to handle all mutation or a serializer function to handle this?

In general, there seems to be so many APIs doing so many similar things and it's confusing what to use when, why a particular API exists, etc. Ideally we would have one and only one logging "middleware/hooks" approach that can be used for all of the above as needed, but at the very least some clarity into this would be appreciated.

Log routing

Like above, there seems to be a "why are there many APIs that all do seemingly the same thing and why is it not clear in the documentation which one is for which" problem.

With v7, there are now apparently two ways to route logs: streams and transports. How are they different? If I have both, how do they interact? If I want to use pino-pretty and pipe it to stdout while logging errors in JSON form to a rotating file? Etc.

Destinations

Related to streams and transports, I see that it is recommended to use pino.destination() whenever possible for the "free" 30% performance uplift, but the documentation seemingly only documents cases in which destination is the only option (e.g. pino(pino.destination(...))). How does it play with streams and transports? Can I even use it with streams and transports? If so, how do I plug it in to both (e.g. is there an option for that)? etc.

Main vs. Worker Threads

Clearly, blocking the event loop is bad. But surely there must be a tradeoff between just pushing everything onto the worker threads vs. handling it in the main thread?

Also, which "features" can we enable worker threads for and how? It's never mentioned how you explicitly "turn on" worker threads and for which features (e.g. streams vs. transports vs. the 5 different ways of mutating lob objects outlined in the first heading). Can we get a documentation for this?

## Exit Logging

I saw that with pino v7, you no longer need to use pino.final. Does that mean I don't need to listen to unhandledException and uncaughtException, or just that I merely need to use logger.info/warn/etc rather than obtaining a finalLogger?

[mcollina]

I will reply bottom up, as it's the simplest solution:

I saw that with pino v7, you no longer need to use pino.final. Does that mean I don't need to listen to unhandledException and uncaughtException, or just that I merely need to use logger.info/warn/etc rather than obtaining a finalLogger?

Just merely use logger.info() and similar, there is no need to use pino.final() anywhere, we take care of that in Node v12+.

[mcollina]

Thanks for your feedback, this is gold. It will take a while to get us through it all - we will update the docs with some more clear "best practices".

[JaneJeon]

Thank you, feel free to update documentation at your own pace!

(Oh, but if you do update it, could you let me know? Thanks)

[JaneJeon]

Hey uh, any update on this? Thanks

[mcollina]

Thank you, feel free to update documentation at your own pace!

Not really but if you would like to send PR it would be mostly welcomed.

[JaneJeon]

Thank you, feel free to update documentation at your own pace!

Sorry, just wanted to see if the issue has been long-forgotten and was out of your mind. If you’re still working on it, that’s fine

[JaneJeon]

I don’t know if I’m reading the mood correctly but please don’t be offended, my goal wasn’t to prod you into doing things!

[mcollina]

Sorry, just wanted to see if the issue has been long-forgotten and was out of your mind. If you’re still working on it, that’s fine

I'm not working on it. It's in the backlog, maybe one day we'll get to it.