modality query

Command: modality query [query expression]

Execute a query against some region of recorded execution. Queries allow you to select occurrences of one or more events in a specified pattern with a variety of filters on event fields. For further details on writing trace queries, see the SpeQTr language reference. The query expression can be given directly or via a path to a file containing the query. Query results, formatting, and verbosity can be controlled with flags. If neither the --region-expression nor the --using options are passed this command will evaluate the query against the current default session.

# Example

$ modality query INIT@CONSUMER
Result 1:
═════════
INIT@CONSUMER(165924670:0:0:2, INIT @ CONSUMER)
  description="Consumer initialized"

Result 2:
═════════
INIT@CONSUMER(165924670:65536:0:2, INIT @ CONSUMER)
  description="Consumer initialized"
...

$ modality query --file example-query-file.tq
Result 1:
═════════
│  *  SAMPLED@PRODUCER(721752399:0:0:5, SAMPLED @ PRODUCER, payload=-1)
│  ║    description="Producer sampled raw measurement"
│  ║  
│  :  (1 elided events)
│  ║  
ɮͼ  
║  │  
*  │  RECVD_MSG@CONSUMER(165924670:2:1:3, RECVD_MSG @ CONSUMER, payload=-1)
║  │    description="Consumer received measurement message"
║  │  
*  │  TASK_LOOP@CONSUMER(165924670:2:1:4, TASK_LOOP @ CONSUMER)
║  │    description="Consumer expensive task loop iteration"

Result 2:
═════════
│  *  SAMPLED@PRODUCER(721752399:3:1:6, SAMPLED @ PRODUCER, payload=0)
│  ║    description="Producer sampled raw measurement"
│  ║  
│  :  (1 elided events)
│  ║  
ɮͼ  
║  │  
:  │  (1 elided events)
║  │  
*  │  RECVD_MSG@CONSUMER(165924670:3:3:4, RECVD_MSG @ CONSUMER, payload=0)
║  │    description="Consumer received measurement message"
║  │  
:  │  (1 elided events)
║  │  
*  │  TASK_LOOP@CONSUMER(165924670:3:3:5, TASK_LOOP @ CONSUMER)
║  │    description="Consumer expensive task loop iteration"
...

$ modality query --file example-query-file.tq --expand --limit 1
Result 1:
═════════
│  *  SAMPLED@PRODUCER(721752399:0:0:5, SAMPLED @ PRODUCER, payload=-1)
│  ║    description="Producer sampled raw measurement"
│  ║  
│  *  (721752399:0:0:6, SENT_MEASUREMENT @ PRODUCER, payload=-1)
│  ║    description="Producer sent measurement message"
│  ║  
ɮͼ  
║  │  
*  │  RECVD_MSG@CONSUMER(165924670:2:1:3, RECVD_MSG @ CONSUMER, payload=-1)
║  │    description="Consumer received measurement message"
║  │  
*  │  TASK_LOOP@CONSUMER(165924670:2:1:4, TASK_LOOP @ CONSUMER)
║  │    description="Consumer expensive task loop iteration"

# Options

[query expression] - The query to evaluate against the given region. You must either pass a query expression as an argument or use the --file option. For more information on writing query expressions see the reference.

--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.

--count - Only print the number of results, not their content.

--expand - By default, query only shows the events that match the queried pattern and probe interactions along a query path. If there are events on the returned query path that are not part of the queried pattern they will be shown as (x elided events). Passing this flag causes query to print all events (matching and elided) along the query paths.

--file <trace-expression-path> - Path to a file containing a trace query. Mutually exclusive with a query provided directly as a command line argument.

-f, --format <text | syslog | json | "{custom}"> - The printed output format, defaults to text. Same as log format, see here for details.

--limit <n> - Limit the number of returned results. If used together with --count, this acts as an upper limit on the resulting count.

--region-expression <region expression> - Evaluate the query against the provided region. See here for details on writing region expressions. If neither this option nor the --using option are passed, the query will be evaluated against the current default session.

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

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

--with-sut <sut name> - Use the given SUT rather than the one currently associated with this session.

← session →