wiretap.wiretap

Main entry point for the wiretap library.

install!

(install! f vars)

For every applicable var in vars - removes any existing wiretap and alters the root binding to be a variadic function closing over the value g of the var and the user provided function f.

A var is considered applicable if its metadata does not contain the key :wiretap.wiretap/exclude and its value implements Fn, i.e. is an object created via fn.

When the resulting “wiretapped” function is called, a map representing the context of the call is first passed to f before the result is computed by applying g to to any args provided. f is then called with an updated context before the result is returned. In both cases, f is executed within a try/catch on the same thread. The result of calling f is discarded.

Returns a coll of all modified vars.

The following contextual data is will always be present in the map passed to f:

Key When Value
:id pre/post Uniquely identifies the call. Same value for pre and post calls.
:name pre/post A symbol. Taken from the meta of the var.
:ns pre/post A namespace. Taken from the meta of the var.
:function pre/post The value that will be applied to the value of :args.
:thread pre/post The name of the thread.
:stack pre/post The current stacktrace.
:depth pre/post Number of wiretapped function calls on the stack.
:args pre/post The seq of args that value of :function will be applied to.
:start pre/post Nanoseconds since some fixed but arbitrary origin time.
:parent pre/post The context of the previous wiretapped function on the stack.
:pre? pre true
:post? post true
:stop post Nanoseconds since some fixed but arbitrary origin time.
:result post The result of applying the value of :function to :args.
:error post Any exception caught during computation of the result.

If the wiretapped var is a multimethod then the following information will also be present.

Key When Value
:multimethod? pre/post true
:dispatch-val pre/post The dispatch value used to select the method.

install-post!

(install-post! f vars)

Like install! but ensures that f is only called post invocation.

The following contextual data is will always be present in the map passed to f:

Key Value
:id Uniquely identifies the call. Same value for pre and post calls.
:name A symbol. Taken from the meta of the var.
:ns A namespace. Taken from the meta of the var.
:function The value that will be applied to the value of :args.
:thread The name of the thread.
:stack The current stacktrace.
:depth Number of wiretapped function calls on the stack.
:args The seq of args that value of :function will be applied to.
:start Nanoseconds since some fixed but arbitrary origin time.
:parent The context of the previous wiretapped function on the stack.
:post? true
:stop Nanoseconds since some fixed but arbitrary origin time.
:result The result of applying the value of :function to :args.
:error Any exception caught during computation of the result.

If the wiretapped var is a multimethod then the following information will also be present.

Key Value
:multimethod? true
:dispatch-val The dispatch value used to select the method.

install-pre!

(install-pre! f vars)

Like install! but ensures that f is only called pre invocation.

The following contextual data is will always be present in the map passed to f:

Key Value
:id Uniquely identifies the call. Same value for pre and post calls.
:name A symbol. Taken from the meta of the var.
:ns A namespace. Taken from the meta of the var.
:function The value that will be applied to the value of :args.
:thread The name of the thread.
:stack The current stacktrace.
:depth Number of wiretapped function calls on the stack.
:args The seq of args that value of :function will be applied to.
:start Nanoseconds since some fixed but arbitrary origin time.
:parent The context of the previous wiretapped function on the stack.
:pre? true

If the wiretapped var is a multimethod then the following information will also be present.

Key Value
:multimethod? true
:dispatch-val The dispatch value used to select the method.

uninstall!

(uninstall!)(uninstall! vars)

Uninstalls all wiretaps from all applicable vars in vars.

A var is considered applicable if the key :wiretap.wiretap/uninstall is present in the metadata and the key :wiretap.wiretap/exclude is not.

Returns a coll of all modified vars.