modality session

Command: modality session

Create, manage, and retrieve information about sessions and the entities observed within sessions. Note that for this command the component, event, mutation, mutator, and probe subcommands will only show entities that were actually observed in the relevant session. This is in contrast to the modality sut command, which shows all entities defined for a given SUT. This command's functionality is exposed via subcommands:

# modality session close

Command: modality session close <session name>

Close the given session. Close is idempotent, so calling close on an already closed session does nothing.

# Example

$ modality session close <session name>

# Options

<session name> - Name of the session to close.

# modality session component

Command: modality session component

Inspect and list the observed components for a particular session. Subcommands:

# modality session component inspect

Command: modality session component inspect <component name | id>

Print detailed information about a component that was observed in a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session component inspect consumer-component
Name: consumer-component
ID: 76d0538f-1ff2-4865-bc41-8219aebac409
Tags: []
SUT: example-sut
Probes:
  CONSUMER_PROBE
Events:
  INIT
  DEINIT
  RECVD_MEASUREMENT_MSG
  MEASUREMENT_SAMPLE_CHECK
  SENT_HEARTBEAT_MSG
Mutators:

# Options

<component name | id> - Identifier for the component. Component ID can be found with modality session component list -vv.

--color <auto | always | never> - 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.

-f, --format <text | json> - The printed output format. Defaults to text.

--include-internal - Show Modality's internal events/probes.

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

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

# modality session component list

Command: modality session component list

List the components observed in a particular session. Note that this differs from modality sut component list in that this command only prints components that were actually observed in this session (i.e. components for which at least one event was observed), whereas the sut variant prints all components defined for the SUT. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session component list
NAME                TAGS                    PROBES  EVENTS
consumer-component  [example-tag]           1       5
monitor-component   [tag2]                  1       7
producer-component  [example-tag, tag2]     1       5

# Options

--color <auto | always | never> - 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.

--include-internal - Show Modality's internal component in the list.

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

# modality session delete

Command: modality session delete <session name>

Delete the given session.

# Example

$ modality session delete example-session

# Options

<session name> - Name of the session to delete.

--force - Bypass the user input confirmation check.

# modality session event

Command: modality session event

List and inspect the observed events for a particular session. Subcommands:

# modality session event inspect

Command: modality session event inspect <event name | id>

Print detailed information about an event that was observed in a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session event inspect CONSUMER_HEARTBEAT_TIMEOUT
Name: CONSUMER_HEARTBEAT_TIMEOUT
Description: Monitor detected consumer heartbeat timeout
ID: 6
Type Hint: 
Kind: failure
Component: monitor-component
Source: c-example/src/monitor/main.c#L172
Tags: [heartbeat, monitor, timeout]

# Options

<event name | id> - Identifier for the event. Event ID can be found with modality session event list -vvv.

--color <auto | always | never> - 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.

-f, --format <text | json> - The printed output format. Defaults to text.

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

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

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

# modality session event instances

Command: modality session event instances <event name | id>

List the occurrences of the given event in a particular session. Default output includes coordinates (colon-separated set of integers to identify a specific instance of an event), event name and probe, payload if applicable, and description. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session event instances SAMPLED
(721752399:0:0:3, SAMPLED @ PRODUCER, payload=-1)
  description="Producer sampled raw measurement"
(721752399:0:0:4, SAMPLED @ PRODUCER, payload=-2)
  description="Producer sampled raw measurement"
(721752399:0:0:5, SAMPLED @ PRODUCER, payload=-1)
  description="Producer sampled raw measurement"
(721752399:3:1:4, SAMPLED @ PRODUCER, payload=0)
  description="Producer sampled raw measurement"
(721752399:3:1:5, SAMPLED @ PRODUCER, payload=1)
...

# Options

<event name | id> - Identifier for the event. Event ID can be found with modality session event list -v.

--color <auto | always | never> - 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.

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

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

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

# modality session event list

Command: modality session event list

List the events observed in a particular session. Note that this differs from modality sut event list in that this command only prints events that were actually observed in this session, whereas the sut variant prints all events defined for the SUT. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session event list
NAME                 TAGS                                    COUNT
CONSUMER_REGISTERED  [heartbeat, monitor]                    20
CONSUMER_TIMEOUT     [heartbeat, monitor, timeout]           42
DEINIT               [consumer]                              20
DEINIT               [monitor]                               20
DEINIT               [producer]                              20
HEARTBEAT_ID_CHECK   [heartbeat, monitor]                    439
INIT                 [consumer]                              20
INIT                 [producer]                              20
INIT                 [monitor]                               20
PRODUCER_REGISTERED  [heartbeat, monitor]                    20
RECVD_MSG            [communication, heartbeat, monitor]     439
RECVD_MSG            [communication, consumer, measurement]  864
SAMPLED              [measurement, producer, sample]         3220
SENT_HEARTBEAT       [communication, heartbeat, producer]    240
SENT_HEARTBEAT       [communication, consumer, heartbeat]    214
SENT_MEASUREMENT     [communication, measurement, producer]  1200
TASK_LOOP            [consumer, process-loop]                16314

# Options

--color <auto | always | never> - 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.

--include-internal - Show Modality's internal component in the list.

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

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

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

# modality session inspect

Command: modality session inspect <session name>

Print detailed information about the given session.

# Example

$ modality session inspect example-session
Name: example-session
Opened at: 2022-01-18 09:46:30 UTC
Opened by: example-user
Tags: []
Status: closed
Linked SUT: example-sut
Observed Probes:
  CONSUMER
  MONITOR
  PRODUCER
Observed Events:
  INIT
  DEINIT
  SAMPLED
  SENT_MEASUREMENT
  SENT_HEARTBEAT
  INIT
  DEINIT
  RECVD_MSG
  HEARTBEAT_ID_CHECK
  PRODUCER_REGISTERED
  CONSUMER_REGISTERED
  CONSUMER_TIMEOUT
  INIT
  DEINIT
  TASK_LOOP
  RECVD_MSG
  SENT_HEARTBEAT

# Options

<session name> - Name of the session to be inspected.

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

-f, --format <text | json> - The printed output format. Defaults to text.

--include-internal - Include Modality's internal events/probes/components.

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

Command: modality session link <session name> <sut name>

(Re)assign the default SUT definition associated with a session (only works for closed sessions).

$ modality session link example-session example-sut
Are you sure you want to link SUT 'example-sut' to session example-session? (yes/no)
y

# Options

<session name> - Name of the session.

<sut name> - Name of the SUT to associate with this session.

--force - Bypass the user input confirmation check.

# modality session list

Command: modality session list

List all known sessions.

# Example

$ modality session list
NAME             TAGS  SUT          STATUS
example-session  []    example-sut  CLOSED
objective-test   []    example-sut  CLOSED

# Options

--color <auto | always | never> - 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.

-f, --format <text | json> - The printed output format. Defaults to text.

-v, --verbose - Provide verbose output.

# modality session open

Command: modality session open <session name> <sut name>

Open a new session. Session names are unique—there cannot be another session with the name provided to this command.

# Example

$ modality session open new-session example-sut
If you would like to use this session as your default run 'modality session use "new-session"'

# Options

<session name> - Name to give to the newly opened session.

<sut name> - Name of the SUT to associate with this session.

--force - Close any other open sessions that were using the connections needed for this session.

--tag <tag>... - A collection of tags to be associated with this session. This parameter may be supplied multiple times and combined with --tags.

--tags <tags> - A comma-separated list of tags to be associated with the session. Can be combined with --tag.

# modality session mutation

Command: modality session mutation

List and inspect the mutations for a particular session. Subcommands:

# modality session mutation inspect

Command: modality session mutation inspect <mutator name> <mutation instance id>

Print detailed information about a mutation that was observed in a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session mutation inspect sample-data-mutator 4
Mutator: sample-data-mutator
Probe: PRODUCER_PROBE
Instance: 4
State: injected
Parameters:
  Name: sample
    Value: -57
Preconditions:
  MEASUREMENT_SAMPLED@PRODUCER_PROBE

# Options

<mutator name> <mutation instance id> - Identifier for the mutation. modality session mutation list gives a list of mutations with both <mutator name> and <mutation instance id> provided.

--color <auto | always | never> - 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.

-f, --format <text | json> - The printed output format. Defaults to text.

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

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

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

# modality session mutation list

Command: modality session mutation list

List the mutations observed in a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session mutation list
MUTATOR              INSTANCE  PARAMETERS    STATE
sample-data-mutator  1         [sample=59]   injected
sample-data-mutator  2         [sample=0]    injected
sample-data-mutator  3         [sample=14]   injected
sample-data-mutator  4         [sample=56]   injected
sample-data-mutator  5         [sample=35]   injected
sample-data-mutator  6         [sample=68]   communicated
sample-data-mutator  7         [sample=0]    injected
...

# Options

--color <auto | always | never> - 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.

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

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

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

# modality session mutator

Command: modality session mutator

List and inspect the observed mutators for a particular session. Subcommands:

# modality session mutator inspect

Command: modality session mutator inspect <mutator name | id>

Print detailed information about a mutator for which at least one mutation was observed in a particular session. You can see which mutators were present in a particular session with modality session mutator list. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session mutator inspect sample-data-mutator
Name: sample-data-mutator
ID Hash: 931521712542889512
Source: src/producer/main.c#L141
Tags: [sample]
Probes:
  PRODUCER
Parameters:
  Name: sample
    Type: i8
    Minimum Effect Value: 0
    Nominal: [-50..50]
    Safety: [-120..120]
    Hard: [-128..127]

# Options

<mutator name | id> - Identifier for the mutator. Mutator ID can be found with modality session mutator list -v.

--color <auto | always | never> - 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.

-f, --format <text | json> - The printed output format. Defaults to text.

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

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

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

# modality session mutator list

Command: modality session mutator list

List the mutators observed in a particular session, i.e. mutators for which at least one mutation was observed. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session mutator list
NAME                 TAGS
sample-data-mutator  [sample]

$ modality session mutator list -v
NAME                 TAGS      PROBES      SOURCE
sample-data-mutator  [sample]  [PRODUCER]  src/producer/main.c#L141

# Options

--color <auto | always | never> - 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.

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

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

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

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

# modality session probe

Command: modality session probe

List, inspect, and see reporting details of the observed probes for a particular session. Subcommands:

# modality session probe inspect

Command: modality session probe inspect <probe name | id>

Print detailed information about a probe that was observed in a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session probe inspect PRODUCER
Name: PRODUCER
Description: Producer probe
ID: 721752399
Component: producer-component
Source: c-example/src/producer/main.c#L67
Tags: [c-example, producer]
Wall Clock Id: 1
Wall Clock Resolution: 1 ns

# Options

<probe name | id> - Identifier for the probe. Probe ID can be found with modality session probe list -v.

--color <auto | always | never> - 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.

-f, --format <text | json> - The printed output format. Defaults to text.

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

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

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

# modality session probe list

Command: modality session probe list

List the probes observed in a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session probe list
NAME      TAGS                   EVENTS
CONSUMER  [c-example, consumer]  17432
MONITOR   [c-example, monitor]   1000
PRODUCER  [c-example, producer]  4700

# Options

--color <auto | always | never> - 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.

--include-internal - Include Modality's internal probe in the list.

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

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

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

# modality session probe reporting-details

Command: modality session probe reporting-details

Print information about data reporting for the probes observed in a particular session. This command can inform you if you are losing data and therefore need to adjust your buffer sizes and/or reporting frequency. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session probe reporting-details
PROBE     REPORTS  REPORT GAPS  MISSING REPORTS  OVERWRITTEN OCCURRENCES  OVERWRITTEN ENTRIES
CONSUMER  1945     0            0                0                        0
MONITOR   389      0            0                0                        0
PRODUCER  929      0            0                0                        0

# Options

--color <auto | always | never> - 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.

-f, --format <text | json> - The printed output format. Defaults to text.

--include-internal - Include Modality's internal probe in the list.

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

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

# modality session scope

Command: modality session scope

Open, close, list, or inspect scopes for a particular session. Subcommands:

# modality session scope close

Command: modality session scope close <scope name>

Close the scope with the given name in a particular session. close is idempotent; if the given scope is already closed this is a no-op. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session scope list
NAME                                   STATUS  INSTANCES
DroneOperational                       Closed  1
DroneSetup                             Closed  1
example-scope                          Open    1

$ modality session scope close example-scope
$ modality session scope list NAME STATUS INSTANCES DroneOperational Closed 1 DroneSetup Closed 1
example-scope Closed 1

# Options

<scope name> - Name of the scope to close.

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

# modality session scope close-all

Command: modality session scope close-all

Close all open scopes in a particular session. close-all is idempotent; if all scopes are already closed this is a no-op. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session scope list
NAME                                   STATUS  INSTANCES
DroneOperational                       Closed  1
DroneSetup                             Open    1
example-scope                          Open    1

$ modality session scope close-all
$ modality session scope list NAME STATUS INSTANCES DroneOperational Closed 1 DroneSetup Closed 1
example-scope Closed 1

# Options

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

# modality session scope inspect

Command: modality session scope inspect <scope name> [instance-id]

Print detailed information about the given scope or scope instance in a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session scope inspect DroneSetup
Name: DroneSetup
Instances:
  Instance: 1
    Opened at: 2021-05-11 09:57:04 UTC
    Closed at: 2021-05-11 09:57:10 UTC
    Opened by: example-user
  Instance: 2
    Opened at: 2021-08-23 20:23:25 UTC
    Closed at: 2021-08-23 20:23:30 UTC
    Opened by: example-user
  ...

# Options

<scope name> - Identifier for the scope to inspect.

instance-id - Optional instance ID to inspect a single instance of the named scope.

--color <auto | always | never> - 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.

-f, --format <text | json> - The printed output format. Defaults to text.

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

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

# modality session scope list

Command: modality session scope list

List the scopes for a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session scope list
NAME                                   STATUS  INSTANCES
DroneOperational                       Closed  1
DroneSetup                             Closed  1

# Options

--color <auto | always | never> - 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.

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

-v, --verbose - Provide verbose output.

# modality session scope open

Command: modality session scope open <scope name>

Open a scope with the given name in a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session scope open example-scope

$ modality session scope list
NAME                                   STATUS  INSTANCES
DroneOperational                       Closed  1
DroneSetup                             Closed  1
example-scope Open 1

# Options

<scope name> - Name for the newly opened scope.

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

# modality session tag

Command: modality session tag

Manage tags for a particular session. Subcommands:

# modality session tag add

Command: modality session tag add <tag name>...

Add tags to a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session tag add first-tag second-tag

$ modality session tag list
TAGS
first-tag
second-tag

# Options

<tag name> - Tag string to associate with the session. You may provide multiple tags.

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

# modality session tag list

Command: modality session tag list

List the tags associated with a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session tag list
TAGS
first-tag
second-tag

# Options

-f, --format <text | json> - The printed output format. Defaults to text.

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

# modality session tag remove

Command: modality session tag remove <tag name>...

Remove tags from a particular session. If no session is specified with the --using flag the default session will be used.

# Example

$ modality session tag remove first-tag

$ modality session tag list
TAGS
second-tag

# Options

<tag name> - Tag string to remove from the session. You may provide multiple tags.

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

# modality session use

Command: modality session use <session-name>

Use the given session as default. Many commands implicitly require a session—these commands will use the default session unless you specify a different one with the --using option.

# Example

$ modality session use example-session

# Options

<session-name> - The name of the session to be set as default.

--force - Use the given name as the default session even if it doesn't currently exist.