Add a sample #spy/t session

README.md

@@ -116,6 +116,70 @@ trials or experiments.
 data is saved, that can become quite a lot of data, so this can be used
 to clean up very long running sessions.
 
+## Example annotated `#spy/t` session
+```clojure
+;;Let's run some code on futures, but see the chronological result
+user=> (future (Thread/sleep 1000) #spy/t (+ 1 2))
+       (future #spy/t ^{:form 1} (+ 3 4))
+#<Future@1013d7df: :pending>
+;;We'll need to use the repl functions
+user=> (use 'spyscope.repl)
+nil
+;;trace-query shows all the traces by default, separated by dashed lines
+user=> (trace-query)
+user$eval35677$fn__35689.invoke(NO_SOURCE_FILE:1) (+ 3 4) => 7
+----------------------------------------
+user$eval35677$fn__35678.invoke(NO_SOURCE_FILE:1) => 3
+nil
+;;We'll define and invoke a function with a #spy/t
+user=> (defn my-best-fn [] #spy/t (* 5 6))
+       (my-best-fn)
+30 ;Here's the return value--note that the trace isn't printed
+;;Let's see all traces so far 
+user=> (trace-query)
+user$eval35677$fn__35689.invoke(NO_SOURCE_FILE:1) (+ 3 4) => 7
+----------------------------------------
+user$eval35677$fn__35678.invoke(NO_SOURCE_FILE:1) => 3
+----------------------------------------
+user$eval35822$my_best_fn__35823.invoke(NO_SOURCE_FILE:1) => 30 ;Here's our new trace
+nil
+;;We can use a filter regex to only see matching stack frames 
+;;Usually, you can filter by the name of the innermost function
+;;You can increase the :fs metadata parameter to have more context to filter by
+user=> (trace-query #"best")
+user$eval35822$my_best_fn__35823.invoke(NO_SOURCE_FILE:1) => 30
+nil
+;;Move onto a new generation
+user=> (trace-next)
+nil
+;;No traces in this generation
+user=> (trace-query)
+nil
+;;Increase the number of generations in the query to review older traces
+user=> (trace-query 2)
+user$eval35677$fn__35689.invoke(NO_SOURCE_FILE:1) (+ 3 4) => 7
+----------------------------------------
+user$eval35677$fn__35678.invoke(NO_SOURCE_FILE:1) => 3
+----------------------------------------
+user$eval35822$my_best_fn__35823.invoke(NO_SOURCE_FILE:1) => 30
+nil
+;;Add a new trace to the current generation
+user=> (my-best-fn)
+30
+;;We can see that there's only one trace in this generation--the one we just made
+user=> (trace-query)
+user$eval35822$my_best_fn__35823.invoke(NO_SOURCE_FILE:1) => 30
+nil
+;;We can combine the generation and regex filter to search and filter many generations
+;;Here we see the invocations of my-best-fn from the current and previous generation
+user=> (trace-query #"best" 2)
+user$eval35822$my_best_fn__35823.invoke(NO_SOURCE_FILE:1) => 30
+----------------------------------------
+user$eval35822$my_best_fn__35823.invoke(NO_SOURCE_FILE:1) => 30
+nil
+user=> 
+```
+
 ## Contributors
 
 David Greenberg (@dgrnbrg) and Herwig Hochleitner (@bendlas)