modality log

Command: modality log

Print a linear, git-style log view of a trace. This view shows a graphical representation of the trace where every vertical line is a probe and communication between probes is shown with horizontal lines. Extra information is printed next to the graph for each event. At default verbosity this information consists of coordinates (colon-separated numbers which constitute a unique ID for an instance of an event), event name and probe, payload or expectation outcome value, and event description.

# Example

$ modality log --from 438896705:4:3:5 --radius 3
*    (438896705:3:2:6, MEASUREMENT_SAMPLE_CHECK @ CONSUMER, outcome=PASS)
      description="Consumer checked sample value"
  
«  PRODUCER interacted with CONSUMER
  
  *  (785847259:4:3:2, MEASUREMENT_SAMPLED @ PRODUCER, payload=-2)
      description="Producer took measurement"
  
*    (438896705:4:3:5, RECVD_MEASUREMENT_MSG @ CONSUMER, payload=-1)
      description="Consumer received measurement message"
  
*    (438896705:4:3:6, MEASUREMENT_SAMPLE_CHECK @ CONSUMER, outcome=PASS)
      description="Consumer checked sample value"
  
«  PRODUCER interacted with CONSUMER
  
  *  (785847259:5:4:2, MEASUREMENT_SAMPLED @ PRODUCER, payload=-2)
      description="Producer took measurement"
  

# Options

--color <always | never | auto> - Whether to color the output. Default is auto, which will autodetect the target output location and whether or not it is capable of handling color escape codes.

--component <name | id> - Restrict output to the given component.

-f, --format <syslog | "{custom}"> - Specify the format for each event row. See below for details.

--from <from> - Event coordinate to center output around. Must be used in combination with --radius.

--include-internal - Include Modality's internal entities in the output.

--probe <name | id> - Restrict output to the given probe.

--radius <radius> - Number of events in each direction around the central --from coordinate to print. Must be used in combination with --from.

--region-expression <region express> - Limit to events in this region. See the reference for more information about region expressions.

--using <session name> - Use the given session rather than the default one.

-v, -vv, --verbose - Provide (more) verbose output.

# Formatting log

log provides a list of formatters which map to the data points that are available for any event:

Specifier Data
%ei Event id
%en Event name
%ef Event file
%el Event line
%ed Event description
%et Event type hint
%ep Event payload
%er Raw event payload
%ec Event coordinate
%pi Probe id
%pn Probe name
%pf Probe file
%pl Probe line
%pd Probe description
%ci Component id
%cn Component name
%rt Receive time

In the case that a probe's or event's metadata is not available, then the name (%en, %pn) specifiers fall back to their respective ids, while the others will just return an empty string.

From these, log provides a few standard output formats:

# Default

%en @ %pn (%ec)

If the -v (verbose 1) flag is used, the following is added to the output.

tags: %et
src: "%ef#L%el"

If the -vv (verbose 2) flag is used, the following is added to the verbose 1 output.

probe_description: %pd
probe_tags: %pt
probe_src: "%pf#L%pl"
component: %cn

# Syslog

Syslog output follows the RFC 3164 format:

PRIORITY=<events = 6, expectations = 4> TIMESTAMP=%rt HOSTNAME=%pn MSG=%ed

syslog can be passed to the --format flag to get this pre-defined format.