Workspace Definition File

# Introduction

# Why Workspaces?

Workspaces serve a crucial function in Modality. Modality compiles all the data you ever collect into a single database, building an empirical model of your system that allows you to ask complex questions, across disparate parts and over time.

Many tasks, however, concern a specific subset of this data. Workspaces let you create a view on your Modality database that only includes the relevant data for what you're trying to accomplish.

The way you filter your data with a workspace is by choosing what set of timelines to include. You specify this with any number of timeline filter expressions, boolean expressions based on timeline attributes. Details on writing these expressions can be found in the reference.

Since workspaces work by filtering, if you create a new workspace with a blank definition (or with no definition at all), it will include all data in Modality's database. You can also specify workspace metadata attributes as key-value pairs, helping you label and organize workspaces. All fields in a workspace definition are optional.

# Segmentation

The other powerful feature of workspaces is segmentation. Many use cases involve some related set of data that is split into discrete chunks. In one case, you could have a workspace for a test suite, and segments for each individual test case. In another, you could have a workspace for a specific test system, and segments for each discrete time you import data from that system.

Segmentation rules let you tell Modality how to split up your data. Modality will then automatically create segments in your workspace that you can analyze, individually or together.

# Workspace Definition File Fields

timeline-filters
string[]
Array of strings where each string is a timeline filter expression. Timeline filter expressions are boolean expressions to test whether a timeline should be included in the workspace. If all expressions return true for a given timeline that timeline is included. For details see the reference.
workspace-attributes
string[]
Array of strings where each string is a key-value assignment. These attributes will be stored as metadata on the workspace for workspace management. Note that these attributes do not require the _. prefix that timeline filter expressions do—they are just assigning a value to a key.
custom-interactions
string[]
Array of strings where each string describes a kind of interaction that Modality should look for, in the trace data. These are also referred to as 'declarative interactions', as they essentially specify shape of an interaction via a query that would match it, if it did exist. They have the form event_a@tl1 AS tx -> event_b@tl2 AS rx AND cond1 AND cond2.... The first part specifies what events (on what timelines) are participating in the interaction. Then, the additional conditions further constrain the interactions, using the bound names from the first part. For example, you might write AND tx.sequence_id = rx.sequnce_id if a sequence number is used in the communication between two components, and the fact that it matches can be used to infer that the relationship exists.
[[segmentation-rule]]
array of tables
Array of tables, each describing a segmentation rule. Segmentation rules specify timeline attributes for Modality to use to automatically split up your data into segments. You can then use the modality segment command to manage and select these for investigation. If you have multiple segmentation rules they will create multiple parallel sets of segments. In other words, each rule will produce a set of segments that cover all of the data in the workspace. Each rule must specify name and attributes.
  • name
    string
    Name of this segmentation rule. This is required.
  • attributes
    string[]
    Array of timeline attributes. Each timeline in the workspace will be assigned to a segment with the other timelines that have the same values for these attributes. This is required.
  • segment-name-template
    string
    Template for naming the segments generated by this rule. This is a template with string interpolation for attribute names placed in {} braces.
  • causally-partition-segments
    bool
    If set to true (the default), Modality will not look for interactions between segments. If set to false, Modality will look for interactions between the segments generated from this rule. In most cases, this should be set to the 'true'.

# Example Workspace Definition Files

# Simple Workspace

# Limit this workspace to data from the example system
timeline-filters = ["_.system = 'example-system'"]

# Metadata for workspace management
workspace-attributes = ["example = true", "complexity = simple"]

# Segment by 'run_id'
[[segmentation-rule]]
name = "by-run-id"
attribute = "timeline.run_id"
segment-name-template = "Run {timeline.run_id}"
causally-partition-segments = true

# Drone Test Workspace

# NOTE: This could also be written as a single expression, like
# ["_.system = 'drone' AND _.operation = 'integration-tests'"]
timeline-filters = ["_.system = 'drone'", "_.operation = 'integration-tests'"]

# Metadata for workspace management
workspace-attributes = ["system = drone", "operation = integration-tests", "segmentation = test-case"]

# Custom interactions to connect between the drone's communications
# component and the base station. Here we look for matching
# 'sequence_num' fields, as well as message hash (which is named
# differently on either side).
custom-interactions = ['send_telemetry@drone_comms as tx -> recv_telemetry@station as rx AND tx.sequence_num = rx.sequence_num AND tx.msg_hash = rx.computed_hash']

# This rule segments on both run ID and test case ID. This way we will
# get a segment for each time each test case was run. If we only
# segmented by test case ID, we would get one segment for each test
# case containing all the timelines for all the times that test case
# has been run.
[[segmentation-rule]]
name = "test-cases"
attributes = ["run_id", "test_case_id"]
segment-name-template = "Test Case {timeline.test_case_id}"

← modality config →