DEVLOG.md 2023-12-03
Wanted to post an update on the final feature I’m letting cook before I’m ready to release Matcha v0.2.0: a custom tracing engine!
On the latest branch, I’ve completely removed the :recon dependency, in favor of bespoke implementation of tracing function calls. This is not done lightly! :recon is a battle-tested project and I’ve benefited from it a lot, including by using it for Matcha up til now.
However, Matcha has a few goals incompatible with it.
Recon Tracing
Recon’s goal is to be diagnostic tool, and offers tracing functionality to that end. However,
:recon_tracedoes not support process send/receive tracing- only function call tracing
:recon_tracedoes not support unlimited tracing- every trace must have a hard limit or rate limit
:recon_tracedoes not support reacting to trace messages with arbitrary code- only sending a formatted string to an io device
:recon_tracedoes not support customization of the supervision tree it uses
Some of these limitations are circumventable if you write your own matchspecs, but are intentionally inaccessible.
Note that these are all smart design decisions for its goals, not limitations! :recon provides several production diagnostic tools, and :recon_trace is but one of them. As a tool used to analyze critical issues in live production systems, however—it must be completely safe to use in all circumstances, and by necessity limit some of the power of :erlang’s tracing.
Matcha Tracing
Matcha’s goal has always been to make the power of difficult-to-use erlang features involving match specifications more accessible to Elixir developers.
Originally, this was focused on composing them, but over time, my ambition has come to envelope tracing as well. Match specifications are only a small part of tracing, just as they are a small part of :ets. However, outside of match specifications, :ets is pretty approachable. This is not true of tracing in general.
As such, I have been working on giving Matcha.Trace these abilities that :recon_trace lacks, with more feature parity with all of Erlang’s tracing capabilities. My goals are to offer:
- high-level APIs for tracing calls that mirror the safety guarantees of
:recon_traceby default - high-level APIs for tracing sends and receives with similar guarantees
- non-default options to selectively do less “safe” things with them
- tools to react to trace messages with arbitrary code, rather than just printing information
- tools to mount the tracing engine into your running application as a first-class component, rather than just a diagnostic sidecar
The implementation in the latest branch does not preserve :recon_trace.calls’s safety features, but it sets the stage for doing so while still allowing for overriding them. It provides an abstraction around tracing calls in particular, so that receive and send can be easily added to it. It is also implemented with a modular supervision tree—when the documentation catches up, it will describe their usage such that you can integrate tracing within your own application’s supervision tree to accomplish whatever your heart desires.
Ultimately, this should lead me to a system that is as safe as :recon by default, but empowers developers with even more cool capabilities!
Deprecations
While I’m eyeing a minor < 1.0.0 version bump, I thought I’d mention some planned deprecations that will come in 0.2.0:
- Elixirs
< 1.14.0will not be supported- the new
Matcha.Tracesupervision trees usePartitionSupervisorwhich is fairly new - supporting all the ways back to elixir
1.11.0has caused some friction in how we interact with the Eilxir compiler I am eager to eliminate,1.14.0is a good fresh slate
- the new
- As such, per the compatability docs Erlang/OTP
< 23.0support will be dropped- this enables the Matcha compiler to do less special-casing around match spec features introduced in
23.0and up, too
- this enables the Matcha compiler to do less special-casing around match spec features introduced in
Matcha.{Pattern, Spec}.source/1is nowraw/1- a “raw” spec is a much better term for this concept
- on
latest, the underlying struct field is still called:sourcebut this may change at any time
As always, thanks for reading! 