Add a cookbook section to docs

[ptaoussanis]

Telemere offers a lot of flexibility, but it's not always obvious how best to use things to maximum effect.

Would be nice to collect together some cookbook-style recipes showing what examples of how Telemere can be valuable in practice.

Ideas to include:

• Examples from Missing documentation on rate sampling/limiting? #58 (comment)
• Info on async tracing / performance measurement (e.g. Slack)
• More info on debugging issues with filtering, etc.

[TuggyNE]

Another suggestion to include: how to prune the logging for spy!/trace! so large values can be summarized without filling the logs. (The obvious approach of using e.g. :xfn to update the :run-val key is insufficient, because the :msg_ key must also be removed or changed.)

[ptaoussanis]

@TuggyNE Hi there!

(The obvious approach of using e.g. :xfn to update the :run-val key is insufficient, because the :msg_ key must also be removed or changed.)

Just to clarify: you're looking for something different than (fn xfn [signal] (dissoc signal :run-val :msg_))? Could you describe a little what kind of behaviour you're looking for?

[TuggyNE]

@TuggyNE Hi there!

(The obvious approach of using e.g. :xfn to update the :run-val key is insufficient, because the :msg_ key must also be removed or changed.)

Just to clarify: you're looking for something different than (fn xfn [signal] (dissoc signal :run-val :msg_))? Could you describe a little what kind of behaviour you're looking for?

Hmm, I thought I replied to this by email, but it doesn't seem to have gotten through.

Anyway, that's roughly what I ended up with, but it confused me for quite a while that :run-val by itself was not controlling all the log results. And more generally, I think customizing the results of spy!/trace! is likely to be a reasonably common task, given how verbose they are by default.

[ptaoussanis]

Hmm, I thought I replied to this by email, but it doesn't seem to have gotten through.

No worries 👍

And more generally, I think customizing the results of spy!/trace! is likely to be a reasonably common task, given how verbose they are by default.

👍 Thanks for the extra context. Fwiw Telemere signals are intentionally pretty verbose by default. In case it wasn't obvious, note that an xfn can also be provided to handlers. So you can easilly dissoc info you don't want from traces, etc.

The idea is that handlers that aren't interested in particular info can just remove or ignore it.