taoensso.tufte — tufte 0.0.1-SNAPSHOT

A simple, fast, monitoring profiler for Clojure/Script.

Core API:

These macros conditionally[1] activate thread-local or dynamic (multi-threaded) profiling for their body:

(profiled         [level          & body] [level          :when test & body])
(profiled-dynamic [level          & body] [level          :when test & body])
(profile          [level stats-id & body] [level stats-id :when test & body])
(profile-dynamic  [level stats-id & body] [level stats-id :when test & body])

profiled* ALWAYS returns [<result> ?<thread-local-stats>] vector. profile* ALWAYS returns <result>; and handles[2] ?<thread-local-stats>.

[1] Compile-time elision for: [level ns] Runtime filtering for: [level ns (test)] ; Note optional arbitrary test

[2] See set-handler! to un/register handler fn/s (e.g. for logging or further analysis).

---

This macro conditionally[3] records body execution times when profiling is active:

(p [form-id & body] [level form-id & body]) ; ALWAYS returns body's result

[3] Compile-time elision for: [level ns] Runtime filtering for: [profiling-active?]

Please see the API docs for more info.

How/where to use this library:

Tufte is highly optimized: even without elision, you can usually leave profiling code in production (e.g. for sampled profiling, or to detect unusual performance behaviour). Tufte's stats maps are well suited to programmatic inspection + analysis.

*min-level* clj/s

e/o #{0 1 2 3 4 5 6}

*ns-filter* clj/s

(fn [?ns] -> truthy).

-compile-ns-filter clj/s

Caching impl/comple-ns-filter.

-elide? clj

(-elide? level-form ns-str-form)

Returns true iff level or ns are compile-time filtered.

-fn-sigs clj/s

(-fn-sigs fn-name sigs)

-handle! clj/s macro

(-handle! level id stats)

accumulate-stats clj/s

(accumulate-stats stats-accumulator [profiled-result profiled-?stats])

Experimental, subject to change!

chance clj/s

(chance p)

Returns true with 0<p<1 probability.

compile-ns-filter clj/s

(compile-ns-filter ns-pattern)

Returns (fn [?ns]) -> truthy. Some example patterns: "foo.bar", "foo.bar.", #{"foo" "bar"}, {:whitelist ["foo.bar."] :blacklist ["baz.*"]}

defnp clj/s macro

(defnp name doc-string? attr-map? [params*] prepost-map? body)

(defnp name doc-string? attr-map? ([params*] prepost-map? body) + attr-map?)

Like defn but wraps fn bodies with p macro.

fnp clj/s macro

(fnp name? ([params*] prepost-map? body) +)

(fnp name? [params*] prepost-map? body)

Like fn but wraps fn bodies with p macro.

format-stats clj/s

(format-stats stats)

(format-stats stats sort-field)

HandlerVal cljs

invalid-form-level-msg clj/s

invalid-min-level-msg clj/s

may-profile? clj/s

(may-profile? level)

(may-profile? level ns)

Returns true iff level and ns are runtime unfiltered.

merge-stats clj/s

(merge-stats s1 s2)

Merges stats maps from multiple runs or threads. Automatically identifies and merges concurrent time windows.

p clj/s macro

(p form-id & body)

(p level form-id & body)

Profiling spy. When ns is unfiltered and profiling is active, records execution time of named body. Always returns body's result.

profile clj/s macro

(profile level stats-id & body)

(profile level stats-id :when test & body)

When level+ns+test are unfiltered, executes named body with thread-local profiling active and dispatches stats to any registered handlers. Always returns body's result.

profile-dynamic clj/s macro

(profile-dynamic level stats-id & body)

(profile-dynamic level stats-id :when test & body)

Like profile but executes body with dynamic (multi-threaded) profiling active. Always returns body's result.

profiled clj/s macro

(profiled level & body)

(profiled level :when test & body)

When level+ns+test are unfiltered, executes body with thread-local profiling active. Always returns [<body-result> ?<stats>].

profiled-dynamic clj/s macro

(profiled-dynamic level & body)

(profiled-dynamic level :when test & body)

Like profiled but executes body with dynamic (multi-threaded) profiling active. Always returns [<body-result> ?<stats>].

profiling? clj/s

(profiling?)

Returns e/o #{nil :thread-local :dynamic}.

pspy clj/s macro

(pspy & specs)

p alias

set-basic-println-handler! clj/s

(set-basic-println-handler!)

set-handler! clj/s

(set-handler! handler-id ?handler-fn)

(set-handler! handler-id ?handler-fn ?ns-filter)

Use to un/register interest in stats output.

nil ?handler-fn => unregister id. nnil ?handler-fn => register id: (handler-fn {:level _ :ns-str _ :id _ :stats _ :stats-str _}) will be called for stats output produced by any profile or profile-dynamic calls.

Handler ideas: Save to a db, log, put! to an appropriate core.async channel, filter, aggregate, use for a realtime analytics dashboard, examine for outliers or unexpected output, ...

NB: handler errors will be silently swallowed. Please try/catch and appropriately deal with (e.g. log) possible errors within your handler fns.

set-min-level! clj/s

(set-min-level! level)

Sets root binding of minimum profiling level, e/o #{0 1 2 3 4 5 6}. 0 => Enable all profiling. 6 => Disable all profiling.

set-ns-pattern! clj/s

(set-ns-pattern! ns-pattern)

Sets root binding of namespace filter. See compile-ns-filter docstring for details on ns-pattern arg.

start-thread-local-profiling! clj/s

(start-thread-local-profiling!)

Warning: this is a low-level primitive. Prefer higher-level macros like profile when possible.

NB: must be accompanied by a call to stop-thread-local-profiling! (e.g. using try/finally).

stats-accumulator clj/s

(stats-accumulator)

Experimental, subject to change! Small util to help merge stats maps from multiple runs or threads. Returns a stateful fn with arities: ([stats-map]) ; Accumulates the given stats (you may call this from any thread) ([]) ; Deref: returns the merged value of all accumulated stats

stop-thread-local-profiling! clj/s

(stop-thread-local-profiling!)

Warning: this is a low-level primitive.

valid-form-level clj/s

(valid-form-level x)

valid-form-level? clj/s

(valid-form-level? x)

valid-min-level clj/s

(valid-min-level x)

valid-min-level? clj/s

(valid-min-level? x)

with-min-level clj/s macro

(with-min-level level & body)

Executes body with dynamic minimum profiling level, e/o #{0 1 2 3 4 5 6}. 0 => Enable all profiling. 6 => Disable all profiling.

with-ns-pattern clj/s macro

(with-ns-pattern ns-pattern & body)

Executes body with dynamic namespace filter. See compile-ns-filter docstring for details on ns-pattern arg.