Skip to content

Core Concepts

This page explains the pieces of Zelos, how data moves through them, and the terms the rest of the docs use. For a shorter tour, read What is Zelos? first.

The pieces

Piece What it does
Zelos app The desktop app for macOS, Windows and Linux. You see, record, compare and analyze data here.
Zelos agent Collects data from your hardware and serves it to the app. The app includes its own agent; a headless agent runs on machines without a screen.
Extensions Plugins the agent runs to read from, and send commands to, your hardware's protocols.
SDK Libraries for Python, Rust and Go that stream data from your own code and expose actions. The Python SDK also records and reads trace files.
Zelos AI The assistant in the app. It reads your data, builds views and writes notebooks.
Notebooks Markdown files that mix notes and Python. They analyze data, and when they assert on checks they run as tests.
CLI The zelos command. It streams, records, queries, runs notebooks and manages extensions from a terminal.
Zelos Cloud Your organization's shared space for traces, layouts and notebooks.

How data flows

graph LR
    HW[Your hardware] -->|Extensions| A[Zelos agent]
    CODE[Your code] -->|SDK| A
    A -->|Live stream| APP[Zelos app]
    A -->|Actions| HW
    APP -->|Save trace| TRZ[.trz file]
    TRZ -->|Open| APP
    TRZ -->|Upload| CLOUD[Zelos Cloud]
    CLOUD -->|Open| APP
  1. Extensions and SDK code send data to an agent.
  2. The agent streams it live to every app connected to it. The app's agent also keeps recent data, so you can scroll back.
  3. In the app, you lay data out in panels on one timeline. You save what you captured as a trace file.
  4. You choose to upload a trace to Zelos Cloud to share it with your organization.
  5. Actions go the other way: from the app, through the agent, to an extension or your code.

The app's agent

The desktop app starts its own agent when it opens. It listens on port 2300, so SDK code on the same machine connects to it with no setup, and it runs the extensions you install.

Headless agents

The Zelos agent runs as a service on Linux machines without a screen: bench computers, test rigs and edge devices. It runs extensions and notebooks the same way the app's agent does. Connect the app to it with Add agent in the Data view, using the machine's address. One app can connect to several agents at once and show their signals side by side.

Local data

Your recorded data stays on your machine unless you choose to upload it. Live data stays in the agent that collected it, and traces you save are files on your disk. A trace reaches Zelos Cloud only when you upload it, and a notebook only when you publish it. Layouts are stored in Zelos Cloud so they sync across sessions and can be shared. When you use Zelos AI, your request and the data its tools read go through Zelos Cloud to an AI model provider, and your chats are stored so you can return to them. See the privacy policy for details.

Signals

All data in Zelos is organized the same way, whichever extension or SDK sent it.

  • A source is one component of your system, such as motor_controller or bus0. It names where data comes from.
  • An event is a named group of fields that a source logs together. Every field in an event shares one timestamp.
  • A field is one value in an event, with a type and an optional unit.
  • A signal is one field over time. Its path is source/event.field, for example motor_controller/status.rpm.
import zelos_sdk

zelos_sdk.init()
motor = zelos_sdk.TraceSource("motor_controller")

# One event, three signals: motor_controller/status.rpm, .torque_nm and .temperature_c
motor.log("status", {"rpm": 2500, "torque_nm": 35.5, "temperature_c": 72})

Timestamps are in nanoseconds. Signals from different sources line up on one timeline with no manual alignment.

Live and recorded

Live means data streaming from an agent right now. Panels follow the newest data, and you can pause, scrub back and zoom while new data keeps arriving.

A trace is a recording in a .trz file. Save one from the timeline with Save trace, record one from code with the SDK, or export one with the CLI. Open a trace to play it back, or open two to compare runs side by side. Traces are open columnar files, and the SDK reads them from your own tools.

How long live data is kept

The app's agent keeps the last 8 hours of live data in memory by default, up to 25% of system memory. Change the retention, the memory limit, or switch to a disk store in Settings › Data › Storage. See Settings.

A headless agent keeps no samples by default. It lists the signals that exist and streams them live to the app, but it cannot answer queries, run notebooks against past data or export traces. Start it with a memory or disk store to keep data. See Install the agent.

Working in the app

  • The workspace is everything open in the app: its tabs, their panels and the data they read. It saves itself as you work, and comes back the next time you open the app. See Workspace.
  • A panel shows signals one way: a plot, table, log, value, state timeline, raw rows, or the actions you can run. See Panels.
  • The timeline controls the time range and playback for every panel in a workspace. One cursor marks the same moment in all of them. See Timeline.
  • A layout is a saved arrangement of panels. Reuse it on the next run, or share it with your organization. See Layouts.

Actions

An action is a command that an extension or your SDK code exposes, with a form that describes its inputs. Run it from the Action panel, from the CLI, or from code with the SDK. The agent routes it to whatever registered it and returns the result. See Create actions.

Organizations and Zelos Cloud

An organization is your team in Zelos Cloud. Members share uploaded traces, layouts and published notebooks. You create or join one the first time you sign in. See Organizations.

Common questions

Do I need the headless agent?

Not on a machine with the app. The app includes its own agent. Install the headless agent on machines without a screen, such as a bench computer or test rig that the app connects to over the network.

How do I organize sources?

Use one source per logical component or subsystem, the way you would draw your system's architecture.

What should be one event, and what should be several?

Group values that change together and are logged at the same moment. Put values with different update rates in separate events.

Next steps

  • Use the app

    Connect to data and build your first panels.

    App guide

  • Stream from your code

    Send your first signals with the SDK.

    SDK quick start