9.9 Invoking dzn trace

The dzn trace command is a pseudo-filter to convert between different trace formats:

event trace (trail)

An event trace or trail is a list of event names observable by interacting with a Dezyne model, for example, for doc/examples/hello-world.dzn:

p.hello
p.world
p.return

event trace (character separated)

Some tools, such as the simulator also read an event trace separated by a comma or a space:

 p.hello,p.world,p.return
"p.hello p.world p.return"

code trace (arrow trace)

The Dezyne executable code can produce a trace showing the sender and the receiver of an event on the same line:

<external>.p.hello -> sut.p.hello
<external>.p.world <- sut.p.world
<external>.p.return <- sut.p.return

simulator trace (split-arrow trace)

The simulator produces a trace showing the sender and the receiver of an event both on their own line:

<external>.p.hello -> ...
... -> sut.p.hello
... <- sut.p.world
<external>.p.world <- ...
... <- sut.p.return
<external>.p.return <- ...

which is especially useful when the lines are prefixed with location information.

The dzn trace command reads arrow traces and converts them to a code trace (the default) or an event trace. A split-arrow trace can also be converted to an ASCII sequence diagram. Its syntax is:

dzn dzn-option… trace option… [FILE]

The options can be among the following:

--format=format

-f format

Display trace in format format, one of diagram, event, json, or sexp. The default is code.

Note: The json can be processed by Dezyne-P5 to draw a trace diagram in a browser.

--help

-h

Display help on invoking dzn trace, and then exit.

--internal

-i

Show communication between components in the system. When using the option --format=diagram on a system trace, the communication between components in the system is hidden by default.

--locations

-L

Show locations in output.

--meta

-m

When using format=event also show meta-events, such as <defer> and <illegal>.

--trace=trace

-t trace

Use trace trace. The default is to read from standard input.