# Causal Graph

Underlying data representation of recorded system execution in Modality. Modality records events sequentially per probe, and probes can be causally related using snapshots. This representation is what underlies Modality's SpeQTr language, allowing you to see which events precede (and could therefore potentially have caused) other events.

# Component

Building block of the SUT. Components allow you to draw a logical boundary around some set of related functionality in the SUT. This is useful because probes and their associated events and expectations will be registered to a component, giving you a high level view of where things are occurring when you analyze your trace. Components have a list of user-defined tags associated with them to give you more useful and flexible ways to query a trace.

# Control Message

Message from modalityd to the SUT to enable scopes and mutations. Control messages can be targeted at a specific probe or broadcast to all probes. Probes must process control messages—processing logic is entirely handled by Modality, users must simply decide when control messages can be processed. Users should periodically call modality_probe_process_control_message or the helper provided by the platform integration they are using when they deem appropriate to process control messages.

# Event

Unit of information collected by Modality and used to build a trace. Events are fired by probes. Users can define and fire events from anywhere in their code with a payload that they choose so they can verify exactly what is of interest to them. Events have a list of user-defined tags associated with them to give you more useful and flexible ways to query a trace.

# Expectation

A way to call attention to meaningful/important state of the system in a trace. Expectations are fired by probes. An expectation is a special type of event that records a boolean value indicating pass/fail, essentially describing invariants of the system. If an expectation fails Modality highlights it in the final trace.

Expectations are also used by Modality's mutation planner functionality: Modality will explore the space of allowable Mutations trying to cause your expectations to fail, intelligently stress testing your system within bounds and with goals that you specify. Expectations have a list of user-defined tags associated with them to give you more useful and flexible ways to query a trace.

# modalityd

Modality's daemon which receives reports from the SUT, builds a trace of overall system execution, serves trace data to the CLI, and sends control messages to the SUT. To collect data from a running system, a connection to modalityd must be available to the SUT. To analyze collected data, the CLI must have the connection to modalityd correctly configured. These connections are configured with a Modality configuration file or the modality config command.

# Mutation

An instance of state being changed by a mutator. Mutation parameters can be set manually with the Modality CLI or can be chosen by the mutation planner intelligently exploring the space of possible states. After a mutation is created it must be communicated to the SUT. Then, once the SUT has processed the mutation message and any mutation preconditions have been met, we say the mutation is injected. If a mutation is injected successfully that mutation is then said to be active, at which point it is taking effect in the SUT.

# Mutation Planner

Modality's subsystem which intelligently chooses mutations to exercise the SUT. The mutation planner is used when generating automatic mutations through the automatic variant of the modality mutate command.

# Mutator

Unit of instrumentation that specifies state that Modality can alter. Mutators declare a set of parameters that Modality can alter and what the allowable range of alterations is. A Mutator can appear across many components, and is activated by a probe. Mutators have a list of user-defined tags associated with them to give you more useful and flexible ways to query a trace.

# Objective

Guidance for how the mutation planner explores the space of possible Mutations. This allows Modality to focus on the environmental scenarios or parts of the SUT that you are most interested in stress-testing and verifying.

# Probe

Unit of instrumentation for Modality. Probes are put into components that you want to instrument. A component can have many probes in it. Probes are single-threaded so there should be one probe per thread. Probes serve two main functions in Modality: they record events and expectations to collect information and they register mutators to allow Modality to change the state of the SUT.

Probes also allow you to inject information from the stimulus into the trace so you can see causal relationships between the stimulus and the SUT. The last important functionality provided by probes is to take and merge snapshots, which allows Modality to associate the states of different components (and therefore the entire system) over time. Probes have a list of user-defined tags associated with them to give you more useful and flexible ways to query a trace.

# Region Expression

A predicate used to match some region or regions of recorded data. Every region expression must include at least one session. You can include a session name, a scope name, a scope instance, a component name or UUID, a probe name or ID, or coordinates, and combine them with AND, OR, and parentheses:

'session = "session-a" OR session = "session-b"'

'session = "session-a" AND (scope = "scope-a" OR scope = "scope-b")'

Sessions, scopes, and scope instances can be compared with = or !=. Coordinates can be compared with = and != but also, because they’re ordered, with <, <=, >, and >=. For more details, see the Regions Expressions reference.

# Report

Unit of recorded data sent from the SUT to modalityd. Reports are produced by probes periodically to save recorded information and clear their internal buffers. They can be sent to modalityd while the session is running or stored and sent to modalityd later. modalityd collects reports to build a trace of overall system execution. Producing and sending reports is handled automatically by many of Modality's platform integrations, but must be orchestrated by the user according to their system constraints if integrating Modality manually.

# Scope

A flexible way to delimit a region in a session. Scopes are started and stopped through the CLI and can be used to name a span of execution which will be easily viewable in the trace. A simple example of a useful scope could be "Startup" so you can see at a glance which part of the session corresponds to system startup.

# Session

A contiguous period of data collection from a SUT. Sessions are started and stopped through the CLI, dictating when Modality should be collecting information from a particular SUT. Events within a session may be causally related, and events in separate sessions can never be causally related.

# Snapshot

A way to correlate the state of different components through time. Probes can take snapshots and then send them to a probe in another component. This allows Modality to trace causal connections between components in a session.

# Stimulus

Umbrella term for any input to or force on the SUT. Typically the stimulus is either manual user action (e.g. kicked the robot), tests, or mutations in the SUT caused by modality.

# System Under Test (SUT)

The entire system you are investigating, testing, validating, etc... The SUT is composed of a set of components and their interactions. Through Modality's flexible instrumentation you can expand the SUT to include your test harness, simulator, or other related tools, allowing you to verify not only the product you're developing but the tools and process you're using to develop it.

# Tag

Flexible way to add meaning to a trace. Components, probes, events, expectations, mutators, objectives, and sessions can all be registered with a list of user-defined tags. These tags can then be used when querying a trace to refine results and help create meaningful analysis.

# Time Domain

Analysis of signals and events with respect to wall clock time. This is in contrast to the logical clocks that Modality uses which are not associated with wall clock time but rather with the sequence of events. Because clocks drift, wall clock time can only be used in Modality for probes which are in the same time domain, i.e. which use the same clock.

# Trace

Generic term for the collection of events and their relations that Modality builds to record what happened during a session.