spyscope
A Clojure(Script) library providing reader tags for trace-oriented debugging of single- and multi-threaded applications.
What is spyscope?
Spyscope is a Clojure and ClojureScript library designed for trace-oriented debugging. It provides reader tags that allow developers to instrument code with minimal syntax, offering detailed insights into program execution, especially in multi-threaded scenarios. It solves the problem of understanding complex program flow and state changes during debugging.
Clojure and ClojureScript developers working on applications where understanding execution flow, especially in concurrent or multi-threaded contexts, is critical.
Developers choose Spyscope for its low-overhead instrumentation via reader tags, rich contextual debugging with stack traces and filtering, and its unique ability to handle multi-threaded debugging without interleaved output.
Overview
Trace-oriented debugging tools for Clojure
Use Cases
Best For
- Debugging concurrent Clojure applications with multiple threads
- Adding trace statements with minimal code changes using reader tags
- Analyzing program flow across generations of execution
- Filtering debug output by namespace or stack frame to reduce noise
- Debugging ClojureScript applications in a browser environment
- Understanding timing and order of events in asynchronous code
Not Ideal For
- Projects requiring interactive, step-by-step debugging with graphical IDEs like IntelliJ or CIDER
- Teams that prioritize real-time debugging feedback over post-hoc trace analysis
- Performance-critical applications where any overhead from reader tags or async tracing is unacceptable
- Developers unfamiliar with Clojure's reader tags or advanced metadata syntax
Pros & Cons
Pros
Uses reader tags like #spy/p, #spy/d, #spy/t to instrument code with just six characters, reducing keystrokes and optimizing developer efficiency.
Provides stack traces, timestamps, markers, and configurable filtering (e.g., :nses regex) to give detailed insights into execution, especially useful for complex flows.
Prints on a dedicated tracing thread to prevent interleaved output from multiple threads, making it ideal for debugging multi-threaded applications.
Stores traces in generations with functions like trace-query and trace-next, allowing post-hoc comparison across runs to understand code changes over time.
Cons
Requires manual injections in Leiningen profiles or additional steps in Boot (e.g., load-data-readers!), which can be error-prone and hinder quick adoption.
Asynchronous tracing and reader tags introduce runtime cost, making it less suitable for production environments or high-performance debugging scenarios.
Primarily console-based, lacking built-in support for graphical debuggers in popular Clojure IDEs, which may limit its appeal for visual debugging workflows.
Frequently Asked Questions
Related Projects
lein-figwheelFigwheel builds your ClojureScript code and hot loads it into the browser as you are coding!
ultraA Leiningen plugin for a superior development environment
flow-storm-debuggerA debugger for Clojure and ClojureScript with some unique features.
prettyLibrary for helping print things prettily, in Clojure - ANSI fonts, formatted exceptions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.