modality query
Command: modality query [query expression]
Execute a query (opens new window) 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 queries, see the SpeQTr language reference. (opens new window) The query expression can be given directly or via a path to a file containing the query. Query results and formatting can be controlled with flags.
# Examples
$ modality query "'Sending heartbeat message' @ consumer"
No explicit workspace provided. Using the default workspace.
Result 1:
═════════
■ "Sending heartbeat message" @ consumer [432de9703f00482589e1ba9eb50194c7:22d4adb0]
║ destination=monitor
║ severity=info
║ source.file=tracing-modality/examples/monitored_pipeline.rs
║ source.line=436
║ source.module=monitored_pipeline
║ timestamp=1663227470747109661ns
║ query.label='Sending heartbeat message' @ consumer
║
Result 2:
═════════
■ "Sending heartbeat message" @ consumer [432de9703f00482589e1ba9eb50194c7:45f4fd19]
║ destination=monitor
║ severity=info
║ source.file=tracing-modality/examples/monitored_pipeline.rs
║ source.line=436
║ source.module=monitored_pipeline
║ timestamp=1663227471336841451ns
║ query.label='Sending heartbeat message' @ consumer
║
...
The below example uses a longer query, so we store it in a file:
# example-query.speqtr
"Producer sending measurement message"@producer AS sending
FOLLOWED BY
"Received measurement message"@consumer AS received
AND
sending.sample = received.sample
$ modality query --file example-query.speqtr
No explicit workspace provided. Using the default workspace.
Result 1:
═════════
■ ║ "Producer sending measurement message" @ producer [7d7174a0f4564613b842e7170eefc980:21ae07]
║ ║ destination=consumer
║ ║ nonce=-936371486071128867
║ ║ sample=0
║ ║ severity=info
║ ║ source.file=tracing-modality/examples/monitored_pipeline.rs
║ ║ source.line=251
║ ║ source.module=monitored_pipeline::producer
║ ║ timestamp=1663215055791219779ns
║ ║ query.label=sending
║ ║
╚═»╗ producer interacted with consumer at 1f79071a5f434f91ba8a8fcd4168e5c0:22f1e3
║ ║
║ ■ "Received measurement message" @ consumer [1f79071a5f434f91ba8a8fcd4168e5c0:22f1e3]
║ ║ interaction.remote_nonce=-936371486071128867
║ ║ interaction.remote_timeline_id=7d7174a0-f456-4613-b842-e7170eefc980
║ ║ interaction.remote_timestamp=1663215055791120403ns
║ ║ sample=0
║ ║ severity=info
║ ║ source.file=tracing-modality/examples/monitored_pipeline.rs
║ ║ source.line=309
║ ║ source.module=monitored_pipeline::consumer
║ ║ timestamp=1663215055791531038ns
║ ║ query.label=received
║ ║
...
# Options
[query expression] - The query to evaluate. 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 (opens new window).
--attributes <attributes> - Only show attributes that match one of the patterns in the given comma-separated list of attribute key patterns.
--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 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 <expression file path> - Path to a file containing a query expression. Mutually exclusive with a query provided directly as a command line argument.
-f, --format <text | json> - The printed output format, defaults to text.
--global - Show events from Modality's entire database. If this flag is not present events are limited to those visible from the current segment(s) of the current workspace. May not be used with --latest-segment, --segment, --segmentation-rule, or --whole-workspace.
--latest-segment - Limit data to the single most recent segment (i.e. the segment which has most recently received an event or timeline attribute update) rather than the current default segment. The latest segment is automatically updated as new data are received. May not be used with --global, --segment, --segmentation-rule, or --whole-workspace.
--limit <n> - Limit the number of returned results. If used together with --count, this acts as an upper limit on the resulting count.
--segment <segment pattern>... - Limit data to the given segment(s) rather than the current default segment(s). Accepts one or more segment name patterns, which can include * or ? as wildcards in the style of glob. May not be used with --global, --latest-segment, or --whole-workspace.
--segmentation-rule <segmentation rule pattern>... - Limit data to segments produced by the given segmentation rule(s) rather than the current default segment(s). Accepts one or more segmentation rule name patterns, which can include * or ? as wildcards in the style of glob. May not be used with --global, --latest-segment, or --whole-workspace.
--show-internal - Include internal attributes (i.e. attributes with names prefixed with internal.) in the output.
--timeline-filter <timeline filter> - A timeline filter expression to restrict the output to events from timelines that match the filter.
--validation-only - Validate that the query is syntactically correct and runnable, but do not run it.
-v, --verbose - Print verbose debugging information.
--whole-workspace - Limit data to the workspace as a monolithic whole unit, ignoring the default segment(s). May not be used with --global, --latest-segment, --segment, or --segmentation-rule.
--with-lax-causality - Trust all wall clocks for this query. This means explicit communications between timelines are not necessary to indicate that one event followed another. Practically, this means that FOLLOWED BY operators can apply across timelines, simply checking the wall clock times reported in the events' event.timestamp attribute.
--with-timeline-attributes - Display all related timeline attributes for each event.
--workspace-name <workspace name> - Name of the workspace to display data for. If not specified the current default workspace (set with modality workspace use) will be used.