[doc] Update examples

Author: ptaoussanis

README.md

@@ -37,31 +37,33 @@ See [here][GitHub releases] for earlier releases.
 ## Quick example
 
 ```clojure
-(require '[taoensso.tufte :as tufte :refer [defnp p profiled profile]])
+(require '[taoensso.tufte :as tufte)
 
-;; Request to send `profile` stats to `println`:
-(tufte/add-basic-println-handler! {})
+;; Send `profile` signals to console
+(tufte/add-handler! :my-console-handler (tufte/handler:console))
 
 ;;; Define a couple dummy fns to simulate doing some expensive work
 (defn get-x [] (Thread/sleep 500)             "x val")
 (defn get-y [] (Thread/sleep (rand-int 1000)) "y val")
 
 ;; Let's check how these fns perform:
-
-(profile ; Profile any `p` forms called during body execution
+(tufte/profile ; Profile any `p` forms called during body execution
   {} ; Profiling options; we'll use the defaults for now
   (dotimes [_ 5]
-    (p :get-x (get-x))
-    (p :get-y (get-y))))
+    (tufte/p :get-x (get-x))
+    (tufte/p :get-y (get-y))))
 
 ;; The following will be printed to *out*:
+;; 2025-04-18T11:23:08.820786Z INFO MyHost readme-examples[15,1]
+;; <<< pstats <<<
+;; pId           nCalls        Min      50% ≤      90% ≤      95% ≤      99% ≤        Max       Mean   MAD      Clock  Total
 ;;
-;; pId      nCalls      Min    50% ≤    90% ≤    95% ≤    99% ≤      Max     Mean   MAD    Clock  Total
-;; :get-x        5    501ms    503ms    505ms    505ms    505ms    505ms    503ms   ±0%    2.52s    53%
-;; :get-y        5     78ms    396ms    815ms    815ms    815ms    815ms    452ms  ±48%    2.25s    47%
+;; :get-y             5      238ms      501ms      981ms      981ms      981ms      981ms      618ms  ±42%      3.09s    55%
+;; :get-x             5      501ms      502ms      505ms      505ms      505ms      505ms      503ms   ±0%      2.51s    45%
 ;;
-;; Accounted                                                                               4.78s   100%
-;; Clock                                                                                   4.78s   100%
+;; Accounted                                                                                                    5.60s   100%
+;; Clock                                                                                                        5.60s   100%
+;; >>> pstats >>>
 ```
 
 ## Documentation

examples/README.cljc

@@ -0,0 +1,33 @@
+(ns readme-examples
+  "Basic examples that appear in the Truss README."
+  (:require [taoensso.tufte :as tufte]))
+
+(comment
+
+;; Send `profile` signals to console
+(tufte/add-handler! :my-console-handler (tufte/handler:console))
+
+;;; Define a couple dummy fns to simulate doing some expensive work
+(defn get-x [] (Thread/sleep 500)             "x val")
+(defn get-y [] (Thread/sleep (rand-int 1000)) "y val")
+
+;; Let's check how these fns perform:
+(tufte/profile ; Profile any `p` forms called during body execution
+  {} ; Profiling options; we'll use the defaults for now
+  (dotimes [_ 5]
+    (tufte/p :get-x (get-x))
+    (tufte/p :get-y (get-y))))
+
+;; The following will be printed to *out*:
+;; 2025-04-18T11:23:08.820786Z INFO MyHost readme-examples[15,1]
+;; <<< pstats <<<
+;; pId           nCalls        Min      50% ≤      90% ≤      95% ≤      99% ≤        Max       Mean   MAD      Clock  Total
+;;
+;; :get-y             5      238ms      501ms      981ms      981ms      981ms      981ms      618ms  ±42%      3.09s    55%
+;; :get-x             5      501ms      502ms      505ms      505ms      505ms      505ms      503ms   ±0%      2.51s    45%
+;;
+;; Accounted                                                                                                    5.60s   100%
+;; Clock                                                                                                        5.60s   100%
+;; >>> pstats >>>
+
+)

examples/clj/README.md

@@ -1,3 +1,3 @@
 # Tufte example project
 
-Try `lein run`, or `lein repl :headless`, etc.
+Try `lein run`, or `lein repl :headless`, etc.

examples/clj/project.clj

@@ -1,20 +1,12 @@
-(defproject com.taoensso.examples/tufte "2.6.3"
+(defproject com.taoensso.examples/tufte "2.7.0"
   :description "Tufte example web-app project"
   :url "https://github.com/ptaoussanis/tufte"
-
-  :license
-  {:name "Eclipse Public License"
-   :url  "http://www.eclipse.org/legal/epl-v10.html"
-   :distribution :repo
-   :comments "Same as Clojure"}
-
+  :main    example.server
   :plugins [[lein-ancient "0.7.0"]]
   :dependencies
-  [[org.clojure/clojure "1.11.1"]
-   [ring                "1.9.6"]
-   [ring/ring-defaults  "0.3.4"]
-   [compojure           "1.7.0"]
+  [[org.clojure/clojure "1.12.0"]
+   [ring                "1.14.1"]
+   [ring/ring-defaults  "0.6.0"]
+   [compojure           "1.7.1"]
    [hiccup              "1.0.5"]
-   [com.taoensso/tufte  "2.6.3"]]
-
-  :main example.server)
+   [com.taoensso/tufte  "2.7.0"]])

examples/clj/src/example/server.clj

@@ -1,32 +1,28 @@
 (ns example.server
-  "Quick Tufte example, showing how to use Tufte for
+  "Quick Tufte example showing how to use Tufte for
   simple ongoing application performance monitoring.
 
   Note that a similar pattern can also be used for Cljs apps.
-
   See the Tufte README for more info!"
-
   {:author "Peter Taoussanis (@ptaoussanis)"}
   (:require
    [clojure.string     :as str]
    [ring.middleware.defaults]
    [ring.adapter.jetty]
-   [compojure.core     :as comp :refer (defroutes GET POST)]
+   [compojure.core     :as comp :refer [defroutes GET POST]]
    [compojure.route    :as route]
    [hiccup.core        :as hiccup]
-   [taoensso.encore    :as enc :refer (have have?)]
+   [taoensso.encore    :as enc :refer [have have?]]
    [taoensso.tufte     :as tufte]))
 
 (enc/defonce stats-accumulator
-  "On eval, will register a Tufte handler to accumulate the results from
-  all unfiltered `profile` data. Deref this to get the accumulated data.
-
-  (tufte/profile {:id :endpoint1} ...)
-  (tufte/profile {:id :endpoint2} ...)
-  ...
-  @stats-accumulator => Return accumulated performance stats"
+  "Accumulates results from all unfiltered `profile` calls.
+  Deref this to get the accumulated data."
+  (tufte/stats-accumulator))
 
-  (tufte/add-accumulating-handler! {:ns-pattern "*"}))
+;; Register handler for `profile` results
+(tufte/add-handler! :my-accumulating-handler
+  (tufte/handler:accumulating stats-accumulator))
 
 (defroutes ring-routes
   (GET "/" ring-req
@@ -75,6 +71,11 @@
 (defn -main "For `lein run`, etc." []
   (println "Starting example Ring server...")
   (ring.adapter.jetty/run-jetty #'main-ring-handler {:port 8088 :join? false})
+
+  ;; Cleanly stop handlers on shutdown
+  (tufte/call-on-shutdown!
+    (fn [] (tufte/stop-handlers!)))
+
   (let [uri "http://localhost:8088/"]
     (println (str "Jetty running on: " uri))
     (try

examples/cljs/deps.edn

@@ -1,2 +1,2 @@
-{:deps {org.clojure/clojurescript {:mvn/version "1.11.60"}
-        com.taoensso/tufte        {:mvn/version "2.6.3"}}}
+{:deps {org.clojure/clojurescript {:mvn/version "1.11.132"}
+        com.taoensso/tufte        {:mvn/version "2.7.0"}}}

examples/cljs/src/example/hello.cljs

@@ -1,14 +1,12 @@
 (ns example.hello
-  (:require [taoensso.tufte :as tufte
-             :refer-macros (defnp p profiled profile)]))
+  (:require [taoensso.tufte :as tufte]))
 
-(tufte/add-basic-println-handler! {})
+(tufte/add-handler! :my-console-handler (tufte/handler:console))
 
 (defn get-x [] (+ 1 1))
 (defn get-y [] (+ 2 2))
 
-(profile ; Profile any `p` forms called during body execution
-  {} ; Profiling options; we'll use the defaults for now
+(tufte/profile {:level :info, :id ::my-profiling-id}
   (dotimes [_ 5]
-    (p :get-x (get-x))
-    (p :get-y (get-y))))
+    (tufte/p :get-x (get-x))
+    (tufte/p :get-y (get-y))))

examples/readme_examples.cljc

@@ -11,7 +11,7 @@ And setup your namespace imports:
 
 ```clojure
 (ns my-app
-  (:require [taoensso.tufte :as tufte :refer [defnp p profiled profile]]))
+  (:require [taoensso.tufte :as tufte]]))
 ```
 
 # Usage
@@ -23,7 +23,7 @@ Wrap the forms you'd like to [sometimes] profile with [`p`](https://taoensso.git
 ```clojure
 (defn get-customer-info []
   (let [raw-customer-map (p ::get-raw-customer (fetch-from-db))]
-    (p ::enrich-raw-customer
+    (tufte/p ::enrich-raw-customer
       (do-some-work raw-customer-map))))
 ```
 
@@ -80,7 +80,7 @@ See [`tufte/*ns-filter*`](https://taoensso.github.io/tufte/taoensso.tufte.html#v
 `p`, `profiled`, and `profile` forms can take an optional **profiling level** ∈ `#{0 1 2 3 4 5}`, e.g.:
 
 ```clojure
-(profiled {:level 3} ...) ; Only activates profiling when (>= 3 *min-level*)
+(tufte/profiled {:level 3} ...) ; Only activates profiling when (>= 3 *min-level*)
 ```
 
 These form levels will be checked against [`tufte/*min-level*`](https://taoensso.github.io/tufte/taoensso.tufte.html#var-*min-level*) which can be an constant integer, or a `[[<ns-pattern> <min-level-int>] ... ["*" <default-min-level-int>]]` for namespace-specific levels.
@@ -97,15 +97,15 @@ Compile-time | `taoensso.tufte.min-level` JVM property or `TAOENSSO_TUFTE_MIN_LE
 Finally, `profiled` and `profile` both support an optional arbitrary test expression:
 
 ```clojure
-(profiled {:when my-cond?} ...) ; Only activates profiling when `my-cond?` is truthy
+(tufte/profiled {:when my-cond?} ...) ; Only activates profiling when `my-cond?` is truthy
 ```
 
 This can be used for a wide range of sophisticated behaviour including smart, **application-aware rate limiting**.
 
 As one simpler example, we can get **sampled profiling** like this:
 
 ```clojure
-(profiled {:when (tufte/chance 0.5)} ...) ; Only activates profiling with 50% probability
+(tufte/profiled {:when (tufte/chance 0.5)} ...) ; Only activates profiling with 50% probability
 ```
 
 # Formatting `pstats`
@@ -129,15 +129,17 @@ If you're using [`tufte/add-basic-println-handler!`](https://taoensso.github.io/
 through the `:format-pstats-opts` option:
 
 ```clojure
-(tufte/add-basic-println-handler!
-  {:format-pstats-opts {:columns [:n :p50 :mean :clock :sum]
-                        :format-id-fn name}})
+;; See the individual docstrings for options, etc.:
+(tufte/add-handler! :my-console-handler
+  (tufte/handler:console
+    {:output-fn
+     (tufte/format-signal-fn
+       {:format-pstats-opts {:columns [:n :p50 :mean :clock :sum]}})}))
 
 (defnp get-x [] (Thread/sleep 500)             "x val")
 (defnp get-y [] (Thread/sleep (rand-int 1000)) "y val")
 
-(profile
-  {}
+(tufte/profile {:level :info, :id ::my-profiling-id}
   (dotimes [_ 5]
     (get-x)
     (get-y)))