modality session

Command: modality session

Create, modify, and retrieve information about sessions and the entities observed within sessions. Can set a default session. This command's functionality is exposed via subcommands:

# modality session close

Command: modality session close <session name>

Close the given session and tear down the connections. If --keep-alive is used, the connections remain intact, but data is no longer recorded until that session is reopened. If close is used without --keep-alive on a closed session whose connections are still open, it finalizes that session, i.e., it closes the connections. Otherwise, close should be idempotent.

# Options

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

--keep-alive - Close the session but keep its connections intact.

# modality session close Example

$ modality session close <name>

# 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 while recording a session.

# Options

<component name | id> - Identifier for the component. Component ID can be found with modality session component 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 <text | json> or --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 inspect 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:
  heartbeat-delay-mutator

# modality session component list

Command: modality session component list

List the components observed in a particular session.

# 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 component list 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

# modality session delete

Command: modality session delete <name>

Delete the given session.

# Options

<name> - Name of the session to delete.

--force - Bypass the user input confirmation check.

# modality session delete Example

$ modality session delete example-session

# 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 while recording a session.

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

-f, --format - 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 inspect 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]

# modality session event instances

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

List the occurrences of the given event in a particular session.

# 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 instances Example

$ modality session event instances CONSUMER_HEARTBEAT_TIMEOUT
(528479634:131080:7:8, CONSUMER_HEARTBEAT_TIMEOUT @ MONITOR_PROBE, outcome=FAIL)
(528479634:131080:8:4, CONSUMER_HEARTBEAT_TIMEOUT @ MONITOR_PROBE, outcome=FAIL)
(528479634:131080:9:4, CONSUMER_HEARTBEAT_TIMEOUT @ MONITOR_PROBE, outcome=FAIL)
(528479634:131083:13:4, CONSUMER_HEARTBEAT_TIMEOUT @ MONITOR_PROBE, outcome=FAIL)
(528479634:131083:14:4, CONSUMER_HEARTBEAT_TIMEOUT @ MONITOR_PROBE, outcome=FAIL)
(528479634:131086:18:4, CONSUMER_HEARTBEAT_TIMEOUT @ MONITOR_PROBE, outcome=FAIL)
...

# modality session event list

Command: modality session event list

List the events observed in a particular session.

# 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 (-v, -vv).

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

# modality session event list Example

$ modality session event list
NAME                        TAGS                           COUNT
CONSUMER_HEARTBEAT_TIMEOUT  [heartbeat, monitor, timeout]  40
DEINIT                      [monitor]                      9
DEINIT                      [consumer]                     9
DEINIT                      [producer]                     9
HEARTBEAT_SENDER_ID_CHECK   [heartbeat, monitor]           167
INIT                        [monitor]                      9
INIT                        [consumer]                     9
INIT                        [producer]                     9
MEASUREMENT_SAMPLED         [measurement, producer]        1277
MEASUREMENT_SAMPLE_CHECK    [consumer, measurement]        378
RECVD_HEARTBEAT_MSG         [heartbeat, monitor]           167
RECVD_MEASUREMENT_MSG       [consumer, measurement]        378
SENT_HEARTBEAT_MSG          [consumer, heartbeat]          79
SENT_HEARTBEAT_MSG          [heartbeat, producer]          90
SENT_MEASUREMENT_MSG        [measurement, producer]        450

# modality session inspect

Command: modality session inspect <session name>

Print detailed information about the given session.

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

# modality session inspect Example

$ modality session inspect test-session
Name: test-session
Opened at: 2021-05-11 09:57:04 UTC
Opened by: example-user
Status: closed
Linked SUT: example-sut
Observed Probes:
  CONSUMER_PROBE
  MONITOR_PROBE
  PRODUCER_PROBE
Observed Events:
  INIT
  DEINIT
  RECVD_HEARTBEAT_MSG
  HEARTBEAT_SENDER_ID_CHECK
  PRODUCER_HEARTBEAT_TIMEOUT
  CONSUMER_HEARTBEAT_TIMEOUT
  INIT
  DEINIT
  RECVD_MEASUREMENT_MSG
  MEASUREMENT_SAMPLE_CHECK
  SENT_HEARTBEAT_MSG
  INIT
  DEINIT
  MEASUREMENT_SAMPLED
  SENT_MEASUREMENT_MSG
  SENT_HEARTBEAT_MSG

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

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

# 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 link example-session example-sut
Are you sure you want to link SUT 'example-sut' to session example-session? (yes/no)
y

# modality session list

Command: modality session list

List the sessions.

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

-v, --verbose - Provide verbose output.

# modality session list Example

$ modality session list
NAME          SUT          STATUS
test-session  example-sut  CLOSED

# modality session open

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

Open a session. If a session with that name does not exist, it is created.

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

# modality session open 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"'

# modality session mutation

Command: modality session mutation

List and inspect the mutations and their state 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 while recording a session.

# 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 - 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 inspect 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

# modality session mutation list

Command: modality session mutation list

List the mutations observed in a particular session.

# 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 mutation list Example

$ modality session mutation list
MUTATOR                  INSTANCE  PARAMETERS              STATE
sample-data-mutator      1         [sample=-82]            communicated
sample-data-mutator      2         [sample=-1]             injected
heartbeat-delay-mutator  3         [heartbeat-delay=611]   injected
sample-data-mutator      4         [sample=-57]            injected
sample-data-mutator      5         [sample=70]             injected
heartbeat-delay-mutator  6         [heartbeat-delay=615]   communicated
heartbeat-delay-mutator  7         [heartbeat-delay=1052]  injected
heartbeat-delay-mutator  8         [heartbeat-delay=673]   injected
heartbeat-delay-mutator  9         [heartbeat-delay=1392]  injected

# modality session mutator

Command: modality session mutator subcommand

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 that was observed while recording a session.

# 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 - 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 inspect Example

$ modality session mutator inspect heartbeat-delay-mutator
Name: heartbeat-delay-mutator
ID Hash: 8813786539029173927
Source: src/consumer/main.c#L166
Tags: [consumer, heartbeat]
Probes:
  CONSUMER_PROBE
Parameters:
  Name: heartbeat-delay
    Type: u32
    Minimum Effect Value: 0
    Nominal: [0..1000]
    Safety: [0..2000]
    Hard: [0..3000]

# modality session mutator list

Command: modality session mutator list

List the mutators observed in a particular session.

# 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 mutator list Example

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

$ modality session mutator list -v
NAME                     TAGS
heartbeat-delay-mutator  [consumer, heartbeat]
sample-data-mutator      [measurement, producer]

# 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 while recording a session.

# 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 - 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 inspect Example

$ modality session probe inspect PRODUCER_PROBE
Name: PRODUCER_PROBE
Description: Producer probe
ID: 785847259
Component: producer-component
Source: c-example/src/producer/main.c#L68
Tags: [c-example, producer]

# modality session probe list

Command: modality session probe list

List the probes observed in a particular session.

# 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 list Example

$ modality session probe list
NAME            TAGS                   EVENTS
CONSUMER_PROBE  [c-example, consumer]  853
MONITOR_PROBE   [c-example, monitor]   392
PRODUCER_PROBE  [c-example, producer]  1835

# modality session probe reporting-details

Command: modality session probe reporting-details

List reporting details for the probes observed in a particular session.

# 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 - 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 probe reporting-details 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

# 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. close is idempotent; if the given scope is already closed then close is a no-op.

# Options

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

-h, --help - Prints help information. Use --help for more details.

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

# modality session scope close 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

# modality session scope close-all

Command: modality session scope close-all

Close all open scopes in the session. close-all is idempotent; if all scopes are already closed then close-all is a no-op.

# Options

-h, --help - Prints help information. Use --help for more details.

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

# modality session scope close-all 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

# modality session scope inspect

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

Print detailed information about the given scope or scope instance.

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

# modality session scope list

Command: modality session scope list

List the scopes for a session.

# 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 list Example

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

# modality session scope open

Command: modality session scope open <scope name>

Open a scope with the given name. If a scope with that given name does not exist inside the current session, it is created and opened.

# Options

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

-h, --help - Prints help information. Use --help for more details.

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

# modality session scope open Example

$ modality session scope open example-scope

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

# modality session use

Command: modality session use <session-name> Set the default 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.

# modality session use Example

$ modality session use example-session