Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/slunghq/slung/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This guide will walk you through installing Slung, starting the server, sending events, and querying data. You’ll have a working setup in under 10 minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Zig compiler installed
  • Nix package manager installed
  • At least 1 GB of RAM
  • Node.js and npm/pnpm (for the TypeScript client)
See the installation guide for detailed setup instructions.

​
Step 1: Build and Start Slung

1

Clone the repository

git clone https://github.com/slunghq/slung
cd slung
2

Build the server

Build Slung with optimizations:
nix develop -c zig build --release=fast
cp ./zig-out/bin/slung .
This creates an optimized binary in the current directory.
3

Start the server

Run Slung on the default port (2077):
./slung
You should see:
Slung server listening on http://0.0.0.0:2077
The server accepts WebSocket connections at ws://localhost:2077/ and provides a health check endpoint at http://localhost:2077/health.

​
Step 2: Send Events with TypeScript Client

Now let’s send some events to Slung using the official TypeScript client SDK.
1

Install the client SDK

In a new terminal, navigate to the client SDK directory:
cd sdks/client/typescript
pnpm install
2

Run the simulated stream example

Start sending simulated temperature events:
pnpm run example:simulated
This sends events every 10ms with these tags:
series: temp
tags: ["sensor=1", "env=dev", "service=api"]
value: random float around 90 with ±1.2 jitter
3

View the output

You should see:
connected to slung websocket
sending simulated events every 10ms
The client is now streaming events to Slung. Leave it running for the next steps.

​
Step 3: Send Custom Events

You can also send custom events programmatically using the SDK. 
import { SlungClient } from "@slunghq/client";

const client = new SlungClient("ws://127.0.0.1:2077");
await client.connect();

// Send a single event
client.sendEvent({
  value: 42.5,
  timestamp: Date.now() * 1000, // microseconds
  series: "temperature",
  tags: ["sensor=1", "location=warehouse"]
});
Wire Protocol: Events are encoded as little-endian binary frames:
[timestamp:i64][value:f64][series_len:u16][tag_count:u16][series_utf8][tag_len:u16+tag_utf8]...
Timestamps must be Unix epoch microseconds.

​
Step 4: Query Your Data

Slung provides a powerful query DSL for retrieving and aggregating data.

​
Query Syntax

Queries follow this format: 
OP:SERIES:[TAGS]:[RANGE]
  • OP: Aggregation operation (AVG, SUM, MIN, MAX, COUNT) - optional
  • SERIES: Series name (e.g., temp, cpu.usage)
  • TAGS: Tag filters with boolean logic (AND, OR, NOT)
  • RANGE: Time range (optional) - [start,end] in microseconds or relative units

​
Query Examples

AVG:temp:[sensor=1]:[1h,now]

​
Time Range Units

Supported time units for relative ranges:
  • s, sec, second(s): Seconds
  • m, min, minute(s): Minutes
  • h, hr, hour(s): Hours
  • d, day(s): Days
  • w, wk, week(s): Weeks
Use now to reference the current time: [1h,now] queries the last hour.

​
Step 5: Build a Workflow (Optional)

For advanced use cases, create custom workflows that react to events in real-time. 
use slung::prelude::*;

#[main]
fn main() -> Result<()> {
    // Subscribe to live stream updates
    let handle = query_live("AVG:temp:[sensor=1]")?;
    poll_handle(handle, on_event, 100.0)?;
    
    Ok(())
}

fn on_event(event: Event, alert_threshold: f64) -> Result<()> {
    if event.value > alert_threshold {
        println!("ALERT: temp={} at {}", event.value, event.timestamp);
        
        // Write back to all connected producers
        for producer in event.producers {
            writeback_ws(producer, "ALERT: threshold exceeded")?;
        }
    }
    
    Ok(())
}
Workflows are compiled to WebAssembly and executed by Slung’s WASM runtime. See the Workflows guide for more details.

​
Verify the Setup

Check that everything is working:
1

Health check

curl http://localhost:2077/health
Should return:
{
  "status": "ok"
}
2

Check data ingestion

After running the simulated stream for a few seconds, stop it and check the data directory:
ls -lh demo/
You should see TSM files being created.

​
Benchmarking

Test Slung’s performance with the built-in benchmark: 
cd sdks/client/typescript

# Ingest 1M events with 2000 per batch
pnpm run example:benchmark -- --count 1000000 --batch 2000 --series temp --tags sensor=1,env=bench

# Duration-based benchmark (30 seconds)
pnpm run example:benchmark -- --duration 30 --batch 2000 --series temp --tags sensor=1,env=bench --linger-ms 3000

​
Next Steps

Core Concepts

Learn about Slung’s data model and architecture

Query Syntax

Master the query DSL with advanced examples

Build Workflows

Create real-time workflows with the Rust SDK

Client SDKs

Explore the TypeScript client SDK API reference

​
Troubleshooting

Make sure the Slung server is running on port 2077:
netstat -an | grep 2077
Or specify a different URL:
SLUNG_WS_URL=ws://127.0.0.1:2077 pnpm run example:simulated
Ensure you’re using Zig 0.15.2 or higher:
zig version
Use the Nix development shell for the correct version:
nix develop
zig version
Make sure dependencies are installed:
cd sdks/client/typescript
pnpm install
Check that the server is accepting connections:
curl http://localhost:2077/health

Build docs developers (and LLMs) love

Get started for freeTalk to us