Changelog — com.taoensso/tufte 2.0.1

Liking cljdoc? Tell your friends :D

This project uses Break Versioning

v2.0.1 - 2018 Apr 27

[com.taoensso/tufte "2.0.1"]

This is a trivial, non-breaking hotfix release

[#27] Hotfix: fix broken Cljs build (@atroche)

v2.0.0 - 2018 Apr 22

[com.taoensso/tufte "2.0.0"]

This is a major, breaking feature release. Please report any issues, thank you!

Tufte v2 introduces API flexibility improvements to expand on Tufte's strengths as an ongoing application performance monitoring tool.

Main objectives of the v2 API:

Defer more profiling costs off-thread, and on demand.
Lossless merging of profiling stats from different runs/threads/over-time.
Inclusion of percentiles in profiling stats.

These objectives are related: percentiles are expensive to calculate, so infeasible to do on the same thread as profiling capture. Also, stats like percentiles are inherently inaccurate to merge.

By deferring the conversion of captured times to stats, the Tufte v2 API makes it easy to support both lossless merging (by merging times, not stats) - and the inclusion of more expensive stats like percentiles (since the cost of stats computation can be incurred on demand, and off the capturing thread).

The net result: the v2 API is more flexible since it decouples time capture and stats computation.

The decoupling is particularly handy for the ongoing performance monitoring of production applications: the application thread/s can inexpensively capture timing info for deferred/async digestion by a background analytics/monitoring task.

tl;dr The v2 API returns PStats objects that can be ~losslessly merged, or derefed to actually compute statistics.

Detailed changes

BREAKING (1): profiled return value has changed: [<result> <?stats-map>] -> [<result> <?pstats-obj>].
BREAKING (2): profile handler keys have changed: :stats, :stats-str_ -> :pstats, :pstats-str_.
BREAKING (3): Utils were renamed: merge-stats -> merge-pstats, format-stats -> format-pstats.
BREAKING (4): Stats maps keys have changed: #{:count :min :max :mean :mad :time} -> #{:n :min :max :mean :mad :sum :p50 :p90 :p95 :p99}.
New: Various readability tweaks+improvements to the output of format-pstats.
New: profiled and profile calls now accept an :nmax option to control size of captured time buffers (used to prevent OOMs).
New: Stats will now automatically include :tufte/compaction info when buffer sizes were exceeded.
New: added several new fully-documented low-level primitives for advanced users: new-pdata, with-profiling, capture-time!.
Impl: Significant performance improvements to both dynamic and thread-local profiling.

Migration guide

If you use only profile with an out-the-box (println or timbre) handler, there are no breaking changes for you.
If you use profile with any custom handlers, you'll need to update your handler fns:
- Stats map keys (as returned by @pstats) have changed (see BREAKING (1) above).
- Map keys given to handler fns have changed (see BREAKING (2) above).
If you use profiled, see BREAKING (1, 3, 4) above.