Skip to content

zelos-trace

zelos-trace records data for live or post-processed analysis via Zelos App.

Minimum required version: 0.0.20

The command zelos-trace was added in version 0.0.20. If you have not yet installed zeloscloud or are running an earlier version, view the instructions at Installing Zelos.

Common Flags

  • --verbose/-v Enable verbose logging
  • --no-ws Do not host local websocket server
  • --bind Bind the local websocket server to this host and port (default: localhost:8080)
  • --config The station config to use to communicate with devices on this station

Environment Variables

  • ZELOS_TRACE_FORWARD_URL Forward data to a particular URL

Running the Zelos Trace Server

For more detailed information, see the command documentation for zelos-trace.

Example: Logging Mock Data

The trace server has the ability to generate mock data, in case no hardware buses are readily available.

The flag --generate-mock will add three signals to the trace: 

# msg1 is sent at 1hz
bus0/msg1.sig1  # A sine wav
bus0/msg1.sig2  # A 32-bit nanosecond counter with rollover

# msg2 is sent at 100hz
bus0/msg2.sig3  # A cosine wave

Run the server with 

zelos-trace --generate-mock

Example: Logging a CAN Bus

The trace server can log raw can frames as well as cracked messages (from a DBC file).

The flag --can adds a can bus to be logged.

To log a single bus without cracking messages 

zelos-trace --can vxcan0

To log a single bus, loading a DBC to crack messages 

zelos-trace --can vxcan0:example.dbc

To log multiple buses, repeat the --can flag 

zelos-trace --can can0:example.dbc --can can1:example2.dbc

To log via the PCAN basic api, prefix with pcan:// and specify the bitrate after the device name. 

zelos-trace --can pcan://PCAN_USBBUS1:500000:example.dbc

Example: Logging to Files

The trace server logs data to parquet-formatted files. Each trace gets an automatic unique id (uuidv4) assigned.

Log to parquet via the --to-parquet flag, specifying a folder 

zelos-trace --can can0:example.dbc --to-parquet traces/

Example: Using a station config

The trace server can be configured to utilize a station config file.

Click here to view example station configs

The flag --config file option allows users to specify the config file to use.

zelos-trace --config /home/user/.config/zelos/configs/station.toml

Override one or more config fields with the -o option 

zelos-trace --config /home/user/.config/zelos/configs/station.toml -o "some.config='some_value'" -o "some.other.config=123"

Example: Using ZELOS_TRACE_FORWARD_URL

  • Full example: 
    ZELOS_TRACE_FORWARD_URL=http://"$(hostname).local":2300/write zelos-trace --no-ws <additional arguments>
  • Forward data to hostname.local (useful for Windows + WSL) 
    ZELOS_TRACE_FORWARD_URL=http://"$(hostname).local":2300/write
  • Forward data by hostname: 
    ZELOS_TRACE_FORWARD_URL=http://some_other_pc:2300/write
  • Forward data by IP: 
    ZELOS_TRACE_FORWARD_URL=http://10.1.1.1:2300/write
  • Export environment var (you can also put this in your .bashrc): 
    export ZELOS_TRACE_FORWARD_URL=http://"$(hostname).local":2300/write

Connecting to the Zelos Trace Server

Click the "Connect Live" button on the Zelos Plot app to connect to a Zelos Trace Server running on your computer.

Zelos Plot Connect Live
Click the "Connect Live" button

Due to security restrictions imposed by the browser runtime, it's only possible to connect to a trace server running on localhost.

Once connected, the UI should show a green "Connected" status in the top-left corner.

Zelos Plot Connect Live
Green "Connected" status

Using SSH to Connect to a Remote Trace Server

It's possible to use SSH to forward the trace server port from a remote server to your local computer. Use the -L flag, specifying the local port, remote host, and remote port to open a tunnel. Optionally, provide the -N flag to not open an interactive shell.

ssh -L 8080:localhost:8080 -N USER@HOST