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.