diff --git a/src/SUMMARY.md b/src/SUMMARY.md index f2c14df..2cf1d5d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -83,7 +83,7 @@ - [Python]() - [Smalltalk]() - [Bash (Shell)]() -- [Capturing and rendering interaction traces]() +- [Capturing and rendering interaction traces](./guide/tracing.md) # Specifications and Theory diff --git a/src/figures/Interaction snapshot.png b/src/figures/Interaction snapshot.png new file mode 100644 index 0000000..fb1d0ba Binary files /dev/null and b/src/figures/Interaction snapshot.png differ diff --git a/src/guide/tracing.md b/src/guide/tracing.md new file mode 100644 index 0000000..6abc50a --- /dev/null +++ b/src/guide/tracing.md @@ -0,0 +1,46 @@ +# Capturing and rendering interaction traces + + - Trace schema: [[syndicate-protocols]/schemas/trace.prs][trace.prs] + - Trace rendering tool: [syndicate-render-msd][] + +[trace.prs]: https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/trace.prs +[syndicate-render-msd]: https://git.syndicate-lang.org/syndicate-lang/syndicate-render-msd + +The `syndicate-server` program is able to capture traces of all [Syndicated Actor +Model](../glossary.md#syndicated-actor-model) interactions that traverse it, saving them as +`TraceEntry` records (defined in [trace.prs][]) to a file for later analysis. + +## Recording a trace + +To record a trace, start `syndicate-server` with the `-t ` (or `--trace-file +`) command-line options. All interactions will be recorded in the named file. + +The contents of the file will look a bit like this: + +```preserves +>> +>> +>> +>> +>> +>> +>> +>> +>> + [ >> 3>>> ]>> + [ >> 3>>>]>> + [ > >]> #!"81/122:00007fa7c800ff10">> 13>>>]>> + [ >]> #!"11/102:00007fa75c0010b0">> 23>>>]>> +... +``` + +## Rendering a trace + +Tools such as [syndicate-render-msd][] can process trace files to produce +message-sequence-diagram-like interactive renderings of their contents. The trace file +excerpted above renders (in part) in the browser to the following screenshot: + +![Interaction snapshot](<../figures/Interaction snapshot.png>) + +Enhancements such as streaming of a live trace and filtering and selecting subtraces are on the +roadmap.