Core Concepts¶

Zelos Agent¶

The Zelos Agent is a lightweight data collection service that acts as the central hub between your instrumented applications and visualization clients. It sits between your applications (using Zelos SDKs) and your visualization tools (like Zelos App), providing:

Centralized data collection from multiple applications and services
High-performance streaming to visualization clients with minimal latency
Intelligent buffering with configurable data retention
Remote control capabilities through the Actions system

Data Flow¶

Zelos supports multiple data access patterns, from local development to cloud-scale deployments. The architecture adapts to your needs while maintaining consistent APIs and data formats across all deployment scenarios.

graph LR
    subgraph "Your System"
        A[Application Code]
        B[Zelos SDK]
    end

    subgraph "Data Pipeline"
        C[Zelos Agent]
        D[In-Memory Buffer]
    end

    subgraph "Consumers"
        E[Zelos App]
        F[.trz Files]
        G[Cloud]
    end

    A --> B
    B -->|Push| C
    C --> D
    D -->|Stream| E
    D -->|Export| F
    D -->|Upload| G

Key Points:

Push Model: Your code actively sends data
Real-time Streaming: Data flows immediately to connected clients
Multiple Consumers: Same data can be visualized live, recorded, and uploaded

Local Data¶

This diagram shows the high-level architecture pushing data directly to the Zelos App from a process using the Zelos SDK running on a local machine.

Use Cases:

Local development and debugging
Standalone applications
Quick prototyping and testing

Characteristics:

Minimal setup — just SDK and App
Lowest latency for real-time development
No additional services required

Remote Connection¶

This diagram shows the high-level architecture pushing data into the Zelos Agent from a process using the Zelos SDK running on a remote machine, and connecting to that machine with the Zelos App.

Use Cases:

Production system monitoring
Hardware-in-the-loop testing
Remote debugging and analysis
Team collaboration on shared systems

Cloud Connection¶

This diagram shows the high-level architecture pushing data into the Zelos Agent from a process using the Zelos SDK running on a remote machine, pushing that data into the Zelos Cloud, and viewing that data in the Zelos App.

Use Cases:

Enterprise-scale deployments
Multi-team collaboration
Long-term data retention
Global access and sharing

Cloud Features:

Persistent storage: data retained beyond agent memory limits
Team collaboration: share data and layouts across organizations
Global access: access data from anywhere with authentication
Scalability: handle enterprise-scale data volumes

Core Services¶

Publish Service — Data Ingestion¶

All Zelos SDKs connect to this service to send trace data. It handles:

High-throughput data ingestion from multiple concurrent sources
Automatic batching for network efficiency
Schema validation and type checking
Backpressure management to prevent memory exhaustion

Python SDKRust SDKGo SDK

import zelos_sdk

# SDK automatically connects to local agent
zelos_sdk.init()  # Connects to grpc://127.0.0.1:2300

# Or specify remote agent
zelos_sdk.init(url="grpc://remote-agent:2300")

use tokio_util::sync::CancellationToken;
use zelos_trace::{TraceRouter, TraceSource};
use zelos_trace_grpc::publish::{TracePublishClient, TracePublishClientConfig};

// Connect to agent
let config = TracePublishClientConfig::new_with_url(
    "grpc://agent-host:2300".to_string()
);
let (client, task) = TracePublishClient::new(router, config);

import "github.com/zeloscloud/zelos/go"

// Configure connection to agent
config := zelos.DefaultTracePublishClientConfig()
config.URL = "grpc://agent-host:2300"
client := zelos.NewTracePublishClient(ctx, receiver, config)

Visualization clients (like Zelos App) connect to this service to receive live data streams:

Multiple concurrent clients can subscribe simultaneously
Filtering capabilities to receive only relevant data
Historical data backfill when clients first connect
Chunked delivery optimized for network efficiency

Actions Service — Remote Control¶

Enables bidirectional communication for automation and remote control:

Action registration from connected applications
Remote execution of functions and commands
Dynamic schema discovery for automatic UI generation
Status monitoring of connected action providers

# Register actions that can be called remotely
@zelos_sdk.action("restart_service", "Restart the motor controller")
def restart_service():
    return {"status": "restarted", "timestamp": time.time()}

zelos_sdk.init(actions=True)

Data Management¶

In-Memory Storage¶

The agent maintains all data in high-performance columnar storage:

Configurable retention: 1–24 hours (default: 8 hours)
Automatic pruning: removes expired data to manage memory usage
Columnar format: optimized for time-series queries and visualization
Memory efficient: compressed storage with minimal overhead

Data Processing¶

Schema management: automatically handles evolving data schemas
Type validation: ensures data integrity and consistency
M4 downsampling: reduces high-frequency data for efficient visualization

Sources and Signals¶

Sources¶

A source represents a logical component in your system:

# Each component gets its own source
motor = zelos_sdk.TraceSource("motor_controller")
battery = zelos_sdk.TraceSource("battery_monitor")
sensors = zelos_sdk.TraceSource("sensor_array")

Think of sources as namespaces for organizing related data.

Events¶

An event is a collection of related data points logged together:

# Define what data belongs together
motor.log("status", {
    "rpm": 2500,
    "torque_nm": 35.5,
    "temperature_c": 72
})

Events ensure temporal correlation - all fields in an event share the same timestamp.

Fields¶

A field is an individual data point within an event:

Name: Identifies the data (e.g., "rpm")
Type: Data type (float, int, string, etc.)
Value: The actual data
Unit: Optional unit of measurement

Live vs Recorded¶

Zelos seamlessly handles both real-time and historical data:

Live Mode¶

Connect to running systems for immediate insights:

# Your code streams data
source.log("telemetry", data)  # → Agent → App (live view)

Recorded Mode¶

Capture data for later analysis:

# Method 1: Using context manager
with zelos_sdk.TraceWriter(f"example.trz") as writer:
    source.log("sensor_data", {
        "temperature": 25.0,
        "humidity": 50.0,
    })

Time Synchronization¶

All data in Zelos is timestamped at collection with nanosecond precision:

Event occurs → SDK captures → Timestamp applied → Agent receives

Benefits:

Automatic correlation across sources
No manual timestamp alignment
Accurate ordering of events
Precise timing measurements

Data Hierarchy¶

Zelos organizes data in a four-level hierarchy:

Segment (UUID)
└── Source (component name)
    └── Event (event type)
        └── Field (data field)

Example:

a1b2c3d4.../motor_controller/status.rpm
│          │                 │      │
Segment    Source            Event   Field

This creates a unique address for every piece of data.

Common Questions¶

How much overhead does Zelos add?

Minimal. The SDK batches data and uses async I/O. Typical overhead is <1% CPU and a few MB of RAM.

Can I use Zelos in production?

Yes! Zelos is designed for production use. Configure retention and memory limits appropriately.

How do I organize sources?

Use sources to represent logical components or subsystems. Think about how you'd explain your system architecture.

What should be an event vs multiple events?

Group data that's logically related and updated together. Separate data with different update frequencies.

How much data can Zelos handle?

The agent can handle millions of points/second. The app downsamples for visualization but keeps full precision for analysis.

Next Steps¶

Now that you understand the core concepts:

SDK Guide - Start instrumenting →

Core Concepts¶

Zelos Agent¶

Data Flow¶

Local Data¶

Remote Connection¶

Cloud Connection¶

Core Services¶

Publish Service — Data Ingestion¶

Subscribe Service — Data Streaming¶

Actions Service — Remote Control¶

Data Management¶

In-Memory Storage¶

Data Processing¶

Sources and Signals¶

Sources¶

Events¶

Fields¶

Live vs Recorded¶

Live Mode¶

Recorded Mode¶

Time Synchronization¶

Data Hierarchy¶

Common Questions¶

Next Steps¶