Tutorial

In this tutorial we will use an example system from the Modality tracing.rs library to collect and view some sample data.

# Setup

First, install Modality.

Once installed, create a user. For this tutorial we'll create a user named "tutorial".

$ modality user create tutorial --use

The example is a Rust program that must be built from source. If you don't already have it on your system, install the rust compiler and the standard rust package manager cargo using rustup. (opens new window)

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Run the Example System

Clone a copy of our open source tracing.rs integration, which includes a few examples showing how it's used.

$ git clone https://github.com/auxoncorp/modality-tracing-rs

Use cargo to run the example system. Cargo will automatically download, compile, and link the required dependencies into the final binary. This example system optionally takes a parameter that limits how long it will run for—we'll limit it to run for 3 seconds.

$ cd modality-tracing-rs
$ cargo run --example monitored_pipeline -- 3
    Finished dev [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/examples/monitored_pipeline`
Running pipeline of collaborating processes indefinitely. Sending traces to modality.
2022-07-20T00:36:32.927870Z  INFO monitored_pipeline::consumer: Starting up
2022-07-20T00:36:32.952271Z  INFO monitored_pipeline::producer: Starting up
2022-07-20T00:36:32.952480Z  INFO monitored_pipeline::producer: Producer sampled raw measurement sample=0
2022-07-20T00:36:32.952578Z  INFO monitored_pipeline::producer: Producer sending measurement message sample=0 destination="consumer"
2022-07-20T00:36:32.952696Z  INFO monitored_pipeline: Sending heartbeat measurement message destination="monitor"
2022-07-20T00:36:32.952968Z  INFO monitored_pipeline::consumer: Received measurement message sample=0 interaction.remote_timeline_id=c87758c7-8c0d-4ef1-a622-7c5e3a7ffabd interaction.remote_timestamp=1658277392952499123
2022-07-20T00:36:32.953580Z  INFO monitored_pipeline::monitor: Starting up
2022-07-20T00:36:32.953781Z  INFO monitored_pipeline::monitor: Received heartbeat message source="producer" interaction.remote_timeline_id=c87758c7-8c0d-4ef1-a622-7c5e3a7ffabd interaction.remote_timestamp=1658277392952604550
2022-07-20T00:36:32.954024Z  INFO monitored_pipeline::monitor: Monitor has observed a component for the first time for that component source="producer"
2022-07-20T00:36:33.116859Z  INFO monitored_pipeline::producer: Producer sampled raw measurement sample=-1
2022-07-20T00:36:33.117004Z  INFO monitored_pipeline::producer: Producer sending measurement message sample=-1 destination="consumer"
2022-07-20T00:36:33.193490Z  INFO monitored_pipeline::consumer: Received measurement message sample=-1 interaction.remote_timeline_id=c87758c7-8c0d-4ef1-a622-7c5e3a7ffabd interaction.remote_timestamp=1658277393116906800
2022-07-20T00:36:33.219735Z  INFO monitored_pipeline::producer: Producer sampled raw measurement sample=0
2022-07-20T00:36:33.219874Z  INFO monitored_pipeline::producer: Producer sending measurement message sample=0 destination="consumer"
...
^C

# Explore the Data

To verify that you successfully ran the example system and get an idea of what it was doing, use modality log.

                             Starting up @ monitor   [f97ef9fb716146169dd0ed4060aa4d24:00]
                               name = Starting up
                               severity = info
                               source.file = tracing-modality/examples/monitored_pipeline.rs
                               source.line = 351
                               source.module = monitored_pipeline::monitor
                               timestamp = 1657844955864252036ns
                            
                             Starting up @ consumer   [398ac97bc3b84e378a39ca72b6827a16:5ca0]
                               name = Starting up
                               severity = info
                               source.file = tracing-modality/examples/monitored_pipeline.rs
                               source.line = 282
                               source.module = monitored_pipeline::consumer
                               timestamp = 1657844955888002100ns
                            
                             Starting up @ producer   [a582d7ec2b004e5e889b85e29f2c3c38:5ca6]
                               name = Starting up
                               severity = info
                               source.file = tracing-modality/examples/monitored_pipeline.rs
                               source.line = 194
                               source.module = monitored_pipeline::producer
                               timestamp = 1657844955888045766ns
                            
─╮                           [Interaction i0000] Producer sampled raw measurement @ producer   [a582d7ec2b004e5e889b85e29f2c3c38:5e83]
                        name = Producer sampled raw measurement
                        sample = 0
                        severity = info
                        source.file = tracing-modality/examples/monitored_pipeline.rs
                        source.line = 219
                        source.module = monitored_pipeline::producer
                        timestamp = 1657844955888216388ns
                     
───╮                         [Interaction i0001] Producer sending measurement message @ producer   [a582d7ec2b004e5e889b85e29f2c3c38:5ef7]
 │ │                           destination = consumer
 │ │                           name = Producer sending measurement message
 │ │                           sample = 0
 │ │                           severity = info
 │ │                           source.file = tracing-modality/examples/monitored_pipeline.rs
 │ │                           source.line = 242
 │ │                           source.module = monitored_pipeline::producer
 │ │                           timestamp = 1657844955888341508ns
 │ │                        
 │ │                         Sending heartbeat measurement message @ producer   [a582d7ec2b004e5e889b85e29f2c3c38:5f86]
 │ │                           destination = monitor
 │ │                           name = Sending heartbeat measurement message
 │ │                           severity = info
 │ │                           source.file = tracing-modality/examples/monitored_pipeline.rs
 │ │                           source.line = 416
 │ │                           source.module = monitored_pipeline
 │ │                           timestamp = 1657844955888527891ns
 │ │                        
 ╰────────────▶               [Interaction i0000] Received measurement message @ consumer   [398ac97bc3b84e378a39ca72b6827a16:6026]
                        interaction.remote_timeline_id = a582d7ec-2b00-4e5e-889b-85e29f2c3c38
                        interaction.remote_timestamp = 1657844955888284960ns
                        name = Received measurement message
                        sample = 0
                        severity = info
                        source.file = tracing-modality/examples/monitored_pipeline.rs
                        source.line = 297
                        source.module = monitored_pipeline::consumer
                        timestamp = 1657844955888701885ns
                     
   ╰──▶                      [Interaction i0001] Received heartbeat message @ monitor   [f97ef9fb716146169dd0ed4060aa4d24:60df]
                               interaction.remote_timeline_id = a582d7ec-2b00-4e5e-889b-85e29f2c3c38
                               interaction.remote_timestamp = 1657844955888431929ns
                               name = Received heartbeat message
                               severity = info
                               source = producer
                               source.file = tracing-modality/examples/monitored_pipeline.rs
                               source.line = 361
                               source.module = monitored_pipeline::monitor
                               timestamp = 1657844955889129663ns
                            
                             Monitor has observed a component for the first time for that component @ monitor   [f97ef9fb716146169dd0ed4060aa4d24:62c9]
                               name = Monitor has observed a component for the first time for that component
                               severity = info
                               source = producer
                               source.file = tracing-modality/examples/monitored_pipeline.rs
                               source.line = 368
                               source.module = monitored_pipeline::monitor
                               timestamp = 1657844955889313386ns
                            
─╮                           [Interaction i0002] Producer sampled raw measurement @ producer   [a582d7ec2b004e5e889b85e29f2c3c38:01e793]
                        name = Producer sampled raw measurement
                        sample = 1
                        severity = info
                        source.file = tracing-modality/examples/monitored_pipeline.rs
                        source.line = 219
                        source.module = monitored_pipeline::producer
                        timestamp = 1657844955988890282ns
                     
                      Producer sending measurement message @ producer   [a582d7ec2b004e5e889b85e29f2c3c38:01e900]
                        destination = consumer
                        name = Producer sending measurement message
                        sample = 1
                        severity = info
                        source.file = tracing-modality/examples/monitored_pipeline.rs
                        source.line = 242
                        source.module = monitored_pipeline::producer
                        timestamp = 1657844955989210324ns
                     
 ╰────────────▶               [Interaction i0002] Received measurement message @ consumer   [398ac97bc3b84e378a39ca72b6827a16:01eb68]
                               interaction.remote_timeline_id = a582d7ec-2b00-4e5e-889b-85e29f2c3c38
                               interaction.remote_timestamp = 1657844955989159599ns
                               name = Received measurement message
                               sample = 1
                               severity = info
                               source.file = tracing-modality/examples/monitored_pipeline.rs
                               source.line = 297
                               source.module = monitored_pipeline::consumer
                               timestamp = 1657844955989882722ns
                     
...

Just like that you have an example dataset to explore. To learn more about listing events and timelines, query and log capabilities, or system topology, see the CLI reference. You can also run the example multiple times to see workspaces and segmentation in action.