Skip to content

Zelos Agent Installation

The Zelos Agent is a lightweight service for capturing tracing data on headless systems, edge devices, and servers.

Zelos Agent

If you're not running on a headless device, you don't need to install this. The app bundles its own flavor of the agent for you!

Overview

  • Lightweight

    Minimal resource usage with configurable data retention

  • Network Ready

    gRPC endpoint on port 2300 for SDK connections

  • Systemd Managed

    Runs as a system service with automatic startup

  • Data Buffering

    Temporary storage with configurable retention time

System Requirements

Platform Support

  • Ubuntu 22.04 LTS (Jammy) — primary tested target
  • Architectures: amd64 and arm64 (also runs on 64-bit Debian / Raspberry Pi OS)

Check yours with dpkg --print-architecture (must be amd64 or arm64; armhf is not built). For other platforms, contact support.

Installation

# Add the Zelos repository
echo "deb [trusted=yes] https://release.zeloscloud.io/app/ubuntu jammy main" \
    | sudo tee /etc/apt/sources.list.d/zelos.list

# Install the agent
sudo apt update
sudo apt install zelos-agent

For early releases, swap in the alpha repository instead:

echo "deb [trusted=yes] https://release.zeloscloud.io/app/alpha/ubuntu jammy main" \
    | sudo tee /etc/apt/sources.list.d/zelos.list

Debian & Raspberry Pi

Keep jammy in the line above — it's just the repo label, and apt pulls the matching amd64/arm64 build. Always add the repository (don't install a standalone .deb), so sudo apt update && sudo apt install --only-upgrade zelos-agent keeps the agent current.

Auto-start Enabled

The agent starts automatically after installation and on system boot.

Verify Installation

sudo systemctl status zelos-agent

Expected output: 

● zelos-agent.service - Zelos Agent
     Loaded: loaded (/lib/systemd/system/zelos-agent.service; enabled)
     Active: active (running) since Mon 2024-01-15 10:30:00 UTC
     ...

Configuration

Default Settings

Setting Default Value Description
Listen Address [::]:2300 Binds to all interfaces
Store Type metadata-only Minimal memory usage
Data Retention 1h How long to keep data

Customize Configuration

To bind to a specific interface or change the port:

sudo systemctl edit zelos-agent

Add:

/etc/systemd/system/zelos-agent.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/zelos-agent --listen-address 127.0.0.1:2300

For more data retention at the cost of memory:

sudo systemctl edit zelos-agent

Add:

/etc/systemd/system/zelos-agent.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/zelos-agent --store-type memory --store-retain-duration 24h

For troubleshooting:

sudo systemctl edit zelos-agent

Add:

/etc/systemd/system/zelos-agent.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/zelos-agent -vv  # Very verbose

After making changes: 

sudo systemctl daemon-reload
sudo systemctl restart zelos-agent

Command Line Options

Option Description Example
--listen-address Set bind address --listen-address [::1]:2300
--store-type Storage backend --store-type memory
--store-retain-duration Data retention --store-retain-duration 6h
-v, -vv Increase verbosity -vv for trace level
-q Quiet mode -q

Service Management

# Start the agent
sudo systemctl start zelos-agent

# Stop the agent
sudo systemctl stop zelos-agent

# Restart the agent
sudo systemctl restart zelos-agent

# Check status
sudo systemctl status zelos-agent

# Last 50 lines
sudo journalctl -u zelos-agent -n 50

# Follow logs in real-time
sudo journalctl -u zelos-agent -f

# Logs from last hour
sudo journalctl -u zelos-agent --since "1 hour ago"

# Today's logs
sudo journalctl -u zelos-agent --since today

# Disable auto-start on boot
sudo systemctl disable zelos-agent

# Re-enable auto-start
sudo systemctl enable zelos-agent

Uninstallation

To completely remove the agent:

# Stop the service
sudo systemctl stop zelos-agent

# Remove the package
sudo apt remove zelos-agent

# Remove repository
sudo rm /etc/apt/sources.list.d/zelos.list

# Update package list
sudo apt update

# Remove any custom configuration
sudo rm -rf /etc/systemd/system/zelos-agent.service.d

Troubleshooting

Agent won't start

Check for port conflicts: 

sudo lsof -i :2300

View detailed error messages: 

sudo journalctl -u zelos-agent -n 100 --no-pager

Try running manually to see errors: 

sudo /usr/bin/zelos-agent -vv

Add: 

[Service]
ExecStart=
ExecStart=/usr/bin/zelos-agent --store-type metadata-only

🚀 Next Steps