Future Tracer

The Future Tracer is a diagnostic and troubleshooting tool in KOS Studio that allows you to monitor and analyze asynchronous operations (Futures) running on your connected device or running image. Futures are KOS’s solution for handling long-running device operations,like dispensing beverages, running calibration sequences, or executing maintenance cycles,that can take seconds to hours to complete. The Future Tracer provides visibility into these operations, showing their progress, timing, relationships, and outcomes in real-time.

Understanding KOS Futures

Before using the Future Tracer, it’s helpful to understand what Futures are and why they’re essential for device operations.

What Are Futures?

A KOS Future is like a smart ticket for a long-running operation. When an operation starts (such as “Make Coffee”), the system immediately returns a Future object that represents that operation. This Future:

  • Provides real-time progress updates as the operation proceeds
  • Shows the current step and estimated time remaining
  • Indicates whether the operation can be cancelled
  • Reports the final outcome (success, failure, or cancellation)

Why Device Operations Need Futures

Physical devices operate on fundamentally different timelines than web applications. In typical web operations, database queries return instantly, API calls complete in hundreds of milliseconds, and even file uploads finish within seconds. These operations happen so quickly that users barely notice the delay.

Device operations, however, work on an entirely different scale. Dispensing a beverage takes 30 to 60 seconds as the system heats water, positions nozzles, mixes ingredients, and pours the drink. Heating systems need 2 to 5 minutes to reach the proper temperature for operation. Calibration sequences can run for 15 minutes or more as the device tests sensors, adjusts motors, and validates settings. Maintenance cycles may take hours to complete as they run through cleaning stages, rinse cycles, and validation procedures.

Traditional async solutions (like promises) are “fire-and-forget” with no progress updates, no visibility into multi-step processes, and no ability to cancel. Futures solve these problems by providing:

  • Immediate response: Get a Future handle right away
  • Real-time updates: Automatic progress notifications without polling
  • User control: Cancel operations when safe to do so
  • Complex operations made simple: Backend handles multi-step orchestration while UI sees a single operation

Future Lifecycle

Futures move through several phases during their lifetime:

  1. Initiation: Operation starts and Future is created
  2. Progress: Updates flow in as the operation proceeds through its steps
  3. Completion: Operation finishes successfully, fails, or is cancelled

Common Future Examples

Coffee Dispensing
Behind the scenes: ingredient check → water heating → nozzle positioning → mixing → dispensing → cleanup
User experience: Single “Making your coffee…” operation with progress

Maintenance Cycles
Behind the scenes: pre-cleaning diagnostics → multiple cleaning stages → rinse cycles → validation → readiness check
User experience: “Running cleaning cycle…” with time estimates

Accessing the Future Tracer

Opening the Tool

  1. Log into KOS Studio
  2. In the Connection Manager window, locate your running image or active IP connection
  3. Find the Active Tools section for that connection
  4. Click + Start New Tool
  5. Select Future Tracer from the dropdown menu

Note: The Future Tracer is only available for active connections.

The Future Tracer consists of two windows:

  • Future Tracer (Parent Futures window): The main list of tracked Futures
  • Future Tracer Details: Detailed timeline view for individual Futures

The Future Tracer continues to be accessible even after your connection becomes inactive:

  • Previously loaded data remains visible
  • You can still analyze and review Futures that were tracked
  • Refresh functionality is disabled until connection is restored
  • Once connection is reestablished, you can refresh to get new data

Understanding the Future Tracer Interface

The Future Tracer has two main components:

Parent Futures Window

The main window displays a table listing all parent Futures being tracked on the device. This provides an at-a-glance view of current and recent operations.

Future Details Window

A detailed visualization window that shows the complete timeline, events, and relationships for a specific Future.

Working with the Parent Futures Window

Initial Empty State

When you first open the Future Tracer, you’ll see an empty window with instructions to refresh the list to begin tracking Futures on your device.

Refreshing the Future List

To load Futures from your connected device:

  1. Click the Refresh button in the Parent Futures window
  2. The tool fetches all currently tracked Futures from the device
  3. The table populates with Future information

Subsequent Refreshes:

  • Click Refresh again to load newly tracked Futures since the last refresh
  • New Futures are added to the existing list
  • The list accumulates Futures over time during your session

Viewing Future Information

The Parent Futures table displays the following columns for each Future:

ID

  • Unique identifier for the Future
  • Used to correlate with device logs and other diagnostic tools

Name

  • Descriptive name of the operation
  • Examples: “DispenseBeverage”, “SystemCalibration”, “CleaningCycle”

Status

  • Current state of the Future
  • Status indicators and meanings:
    • Success (Green): Operation completed successfully
    • Fail (Red): Operation encountered an error and failed
    • Cancel (Orange): Operation was cancelled by user action
    • Aborted (Yellow): Operation was cancelled by the system
    • In Progress (Blue): Operation is currently running

Created

  • Timestamp showing when the Future was created

Duration

  • Time the operation took to complete (in milliseconds)
  • For completed Futures (Success, Fail, Cancel, Aborted)
  • Empty for In Progress Futures

List Organization

The Parent Futures list is organized to make tracking operations easy:

Chronological Sorting:

  • Futures are sorted in chronological order
  • Newer Futures appear at the bottom of the list
  • This makes it easy to see the progression of operations over time

Scrolling:

  • If the number of Futures exceeds what’s viewable on screen, the list is scrollable
  • You can review historical operations as well as current ones

Opening Future Details

To view detailed information about a specific Future:

  1. Find the Future in the Parent Futures table
  2. Click the Play button (▶) for that Future
  3. A Future Details window opens showing the complete timeline

Multiple Details Windows:

  • You can open multiple Future Details windows for different Futures
  • Each window shows the timeline for its specific Future
  • Clicking the Play button again for an already-open Future brings that window to the front

Connection Requirements:

  • Play button is enabled only for active connections
  • For inactive connections, you cannot open new Future Details windows
  • Previously opened details windows remain accessible with their loaded data

Working with the Future Details Window

The Future Details window provides a comprehensive visualization of a Future’s execution, including all events, states, callbacks, and child Futures.

Window Overview

The Future Details window consists of three main areas:

  1. Future Name (Top)
  • Displays the name of the parent Future you’re analyzing
  1. Time-Frame Panel (Top)
  • Interactive timeline showing the complete duration of the Future
  • Allows you to focus on specific time segments
  1. Main Content Area
  • Left side: List of Futures, events, and child Futures
  • Right side: Detailed timeline with visual representation

Understanding the Time-Frame Panel

The time-frame panel at the top of the window shows a condensed timeline of the entire Future duration and allows you to zoom in on specific time periods.

Setting Up Your View

Initial View:

  • The timeline shows the complete duration of the parent Future
  • All events are visible but may be compressed

Focusing on a Time Segment:

  1. Set Beginning Marker: Click once on the timeline to place the beginning marker
  2. Set End Marker: Click a second time to place the end marker
  3. Adjust Markers: Click and drag either marker bar to modify the selected time range
  4. Move Selection: Click and drag the selected time-frame (area between markers) to shift your view along the timeline
  5. Reset View: Drag markers to the very ends of the timeline to see the complete duration again

Visual Timeline Indicators

The time-frame panel shows color-coded bars representing Future states:

State Colors:

  • Green: Success
  • Red: Fail
  • Yellow: Aborted
  • Orange: Cancelled
  • Blue: In Progress

These colors help you quickly identify the outcome and status of Futures in the timeline.

Working with the List of Futures

The left panel of the Future Details window shows an expandable/collapsible tree structure of all Futures, events, and child Futures.

Expanding and Collapsing Items

Individual Items:

  • Click on any item in the list to expand or collapse it
  • Expanded items show their associated events and child Futures
  • Collapsed items hide these details for a cleaner view

Head Events:

  • Click the Head Events button to show/hide events and states at the beginning of the Future
  • Head events include initialization, setup, and early callbacks

Tail Events:

  • Click the Tail Events button to show/hide events and states at the end of the Future
  • Tail events include completion, cleanup, and final callbacks

Organizing Your View

Use the expand/collapse controls to:

  • Focus on specific parts of the Future execution
  • Hide irrelevant details to reduce visual clutter
  • Compare timing between different child Futures
  • Investigate specific events or callbacks

Understanding the Detailed Timeline

The right side of the Future Details window shows a visual timeline of all events, states, and callbacks as they occurred during the Future’s execution.

Timeline Elements

Timeline Bars:

  • Visual bars represent when Futures were active
  • Bar colors indicate the outcome (using the same color scheme as the time-frame panel)
  • Bar length shows duration

Line Types:

  • Thin Lines: Show the duration when a Future was active
  • Thick Lines: Show the duration when a Future was runnable (actively executing)

Timeline Markers:

  • Click on the timeline to add a marker
  • The marker shows the exact time at that point
  • Use markers to compare timing between different events

Synchronized Views

The list on the left and the timeline on the right are synchronized:

  • Expanding/collapsing items in the list updates the timeline display
  • Showing/hiding head or tail events reflects on both sides
  • Changes to the time-frame panel zoom the timeline accordingly

Scrolling Through Time

Use the scroll controls to:

  • Navigate through long-running operations
  • Focus on specific phases of execution
  • Compare events that occurred at different times
  • Follow the progression of child Futures

Color-Coded Status

The timeline uses consistent color coding to show Future outcomes:

Status Colors:

  • Success (Green): Future completed successfully
  • Fail (Red): Future encountered an error
  • Aborted (Yellow): System cancelled the Future
  • Cancelled (Orange): User cancelled the Future
  • In Progress (Blue): Future is still running

Analyzing Future Relationships

The Future Details window helps you understand how parent and child Futures relate:

Parent-Child Hierarchy:

  • Parent Futures can spawn child Futures to handle sub-operations
  • The tree structure on the left shows these relationships
  • Example: A “DispenseBeverage” Future might have child Futures for “HeatWater”, “PositionNozzle”, and “PourLiquid”

Timing Analysis:

  • See when child Futures started relative to their parent
  • Identify whether child Futures run sequentially or in parallel
  • Understand where time is spent in complex operations

Dependency Tracking:

  • Trace which events triggered which child Futures
  • Identify bottlenecks where operations wait for dependencies
  • Verify that operations execute in the expected order

The Future Tracer displays a connection footer that helps you identify which device or simulator the tool is connected to:

Image Name:

  • Shows the name of the Studio image running on the device
  • Helps identify which tools belong to which connections

Target Name or IP Address:

  • Displays the device target name or IP address
  • Makes it easy to distinguish between multiple devices

Device Connection Status:

  • Shows connection to the device (not the KOS Server)
  • You can run the tool without server connection but typically need device connection
  • Standard KOS Studio connection indicators apply

Troubleshooting with Future Tracer

Common Analysis Scenarios

Investigating Slow Operations:

  1. Open Future Tracer and refresh to load current Futures
  2. Find the slow operation in the Parent Futures list
  3. Note the Duration and compare to expected timing
  4. Open Future Details to see the timeline
  5. Identify which child Futures or events took the longest
  6. Focus on those specific phases for deeper investigation

Diagnosing Operation Failures:

  1. Locate the failed Future (Status: Fail in red)
  2. Open Future Details for that Future
  3. Examine the timeline to see where the failure occurred
  4. Check which child Future or event failed
  5. Use timing information to correlate with device logs
  6. Identify patterns if multiple operations fail at similar points

Understanding Complex Operations:

  1. Open Future Details for the operation
  2. Expand all events to see the complete sequence
  3. Observe the parent-child relationships
  4. Use the time-frame panel to focus on specific phases
  5. Compare expected behavior with actual execution order
  6. Verify that all expected child Futures completed

Analyzing Cancelled Operations:

  1. Find cancelled Futures (Status: Cancel or Aborted)
  2. Open Future Details to see when cancellation occurred
  3. Check whether cancellation was user-initiated (Cancel) or system-initiated (Aborted)
  4. Examine what cleanup operations occurred after cancellation
  5. Verify the device returned to a safe state

Comparing Multiple Operations:

  1. Open Future Details for multiple similar operations
  2. Arrange windows side-by-side
  3. Compare timing and duration
  4. Identify variations in execution patterns
  5. Look for operations that deviate from normal behavior

Quick Tips for Effective Troubleshooting

  • Use the Refresh button regularly to capture ongoing operations as they occur
  • Open Future Details immediately for In Progress Futures to watch operations in real-time
  • Set time-frame markers to isolate specific phases that seem problematic
  • Collapse unrelated child Futures to focus on the parts you’re investigating
  • Look for timing patterns across multiple similar operations to identify systemic issues
  • Correlate Future IDs with device logs for comprehensive troubleshooting
  • Keep the tool open after connections become inactive to preserve diagnostic data
  • Use color coding to quickly spot failed or aborted operations in the timeline
  • Compare Duration values between successful and failed operations to identify anomalies
  • Track child Future relationships to understand dependencies and execution flow