KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #codex #ai-agents #claude-code #dsh #dsh-plugin #cli #macos #ai-agent #deepseek-harness #open-source

taillight

★ 29 Open GitHub ↗

Real-time log viewer for syslog and application logs — filter, stream, and alert on events as they happen. Go backend with SSE streaming, Vue frontend, TimescaleDB storage, and pluggable notifications.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# taillight

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go](https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go)](https://go.dev)

Lightweight, real-time log viewer for network operations teams. Stream netlog (network device syslog), srvlog (server syslog), and application logs to your browser with a single Go binary and PostgreSQL.

**[Live Demo](https://demo.taillight.lasse.cloud)** — try it without installing anything.

![Home dashboard](https://raw.githubusercontent.com/lasseh/taillight/main/docs/screenshots/home.png)

![Srvlog stream](https://raw.githubusercontent.com/lasseh/taillight/main/docs/screenshots/srvlog-stream.png)

<details>
<summary>More screenshots</summary>

![Application log stream](https://raw.githubusercontent.com/lasseh/taillight/main/docs/screenshots/applog-stream.png)

![Device detail](https://raw.githubusercontent.com/lasseh/taillight/main/docs/screenshots/device.png)

![Volume](https://raw.githubusercontent.com/lasseh/taillight/main/docs/screenshots/dashboard.png)

</details>

## Why Taillight?

- **Real-time first** — events are pushed to the browser via Server-Sent Events the moment they hit the database. Per-client server-side filtering means you only receive what you asked for.
- **Lightweight stack** — PostgreSQL (TimescaleDB) + a single Go binary + rsyslog. No Elasticsearch, no JVM, no agent fleet to manage.
- **Three log feeds** — netlog (network device syslog), srvlog (server syslog), and applog (HTTP ingest) each have independent streams, filtering, retention, and dashboards. All three are always on; optional subsystems (notifications, AI analysis, LDAP, Netbox) are the real toggles.
- **Multiple clients** — a browser SPA in this repo, plus a terminal UI and SSH-served TUI in the companion [taillight-tui](https://github.com/lasseh/taillight-tui) repo — all consume the same SSE streams.
- **Built-in alerting** — Slack, webhook, email (SMTP), and ntfy channels. First matching event fires immediately; repeats during a silence window collapse into a single digest, with per-channel rate limiting, circuit breakers, and bounded delivery retry.
- **Optional AI analysis** — daily log briefings generated by a local Ollama LLM, surfacing anomalies and trends without sending data off-premise.

## Features

### Streaming & Filtering

- SSE push for netlog, srvlog, and application log events — no polling
- Filter by host, facility, severity, program, service, component, and full-text search
- Cursor-based pagination for historical queries

### Dashboards & Analytics

- Severity breakdown, top hosts, and recent high-severity events at a glance
- Per-host volume charts with selectable time ranges
- Per-device detail views for netlog, srvlog, and application logs
- Continuous aggregates for fast dashboard queries

### Application Log Ingest

- `POST /api/v1/applog/ingest` — structured JSON batch endpoint
- `taillight-shipper` — standalone binary that tails log files and ships them to the ingest API
- `pkg/logshipper` — Go `slog.Handler` for shipping your application's own logs
- `taillight-sdk` — Python `logging.Handler` for shipping logs from Python apps (`pip install taillight-sdk`)

### Terminal UI & SSH access

- A terminal UI client (`taillight-tui`) and an SSH server that hosts it (`taillight-wish`) live in the companion repo **[taillight-tui](https://github.com/lasseh/taillight-tui)** — both are HTTP/SSE clients of this API

### Notifications

- Slack, webhook, email (SMTP), and ntfy backends
- Rule matching by hostname, programname, severity/facility/msgid (syslog), service/component/level (applog), and full-text search
- Fingerprint model: first match fires immediately, repeats within a silence window accumulate into a single end-of-window digest, silence grows linearly on sustained firing up to `silence_max`
- Optional `coalesce` batches simultaneous first-alert bursts into one message with a real count
- Per-channel token-bucket rate limit, circuit breaker, and bounded retry (`5s → 30s → 2m → 10m`)
- Notification log with delivery status, rendered payload, and Prometheus counters for evaluated/matched/sent/suppressed

### AI Analysis

- Scheduled daily reports via local Ollama LLM
- Anomaly detection and trend summaries
- On-demand analysis trigger via API
- Postgres aggregates the logs first, so the model narrates a compact summary rather than raw lines — see [`api/internal/analyzer/README.md`](api/internal/analyzer/README.md) for how the pipeline works

### Netbox Enrichment

- On the netlog detail page, IP addresses, prefixes, AS numbers, interfaces, and the source device are looked up against [Netbox](https://netbox.dev/) and shown as cards alongside the event
- Lookups happen lazily after the page renders — list views and live SSE never call Netbox
- In-memory TTL cache (default 10 min, including negative results) keeps repeat detail-page visits free
- Per-entity errors surface inline; if Netbox is unreachable or disabled the panel hides itself, the detail page is unaffected
- Configurable auth scheme — legacy `Token <key>` (default) or OAuth-style `Bearer <key>`
- Disabled by default; configure under `netbox:` in `api/config.yml` and provide the token via `NETBOX_TOKEN`

### Themes

- 19 built-in color themes — Tokyo Night, Dracula, Catppuccin, Nord, Solarized, Gruvbox, SynthWave 84, and more
- 15 dark themes and 4 light themes
- One-click switching from the settings menu, persisted to localStorage
- Every theme includes matched chart colors for consistent data visualization

### Operations

- TimescaleDB hypertables with compression and configurable retention policies
- Prometheus metrics (`/metrics` endpoint or dedicated metrics server)
- Session-based auth with API key support (read, ingest, admin scopes)
- Interactive API documentation at `/api/docs` (Scalar/OpenAPI)
- Docker Compose one-command deployment
- Juniper netlog reference data import (XLSX)

## Architecture

```
  Netlog path (network devices):

rsyslog ──ompgsql──► netlog_events ──pg_notify──► Listener (LISTEN/NOTIFY)
                       (TimescaleDB)                         │
                                                             ▼
                                                     NetlogBroker ──► SSE ──► Browser
                                                             │
                                                             ▼
                                                     NotificationEngine
                                                     (Slack/Webhook/Email/ntfy)

Srvlog path (servers):

rsyslog ──ompgsql──► srvlog_events ──pg_notify──► Listener (LISTEN/NOTIFY)
                       (TimescaleDB)                         │
                                                             ▼
                                                     SrvlogBroker ──► SSE ──► Browser
                                                             │
                                                             ▼
                                                     NotificationEngine
                                                     (Slack/Webhook/Email/ntfy)

Application log path:

HTTP POST ──► Ingest Handler ──► applog_events ──► AppLogBroker ──► SSE ──► Browser
  (API key)                        (TimescaleDB)           │
                                                           ▼
                                                   NotificationEngine
```

**Netlog and Srvlog** share the same pipeline but use separate tables, brokers, and retention policies. rsyslog writes to `netlog_events` or `srvlog_events` via ompgsql. A trigger fires `pg_notify('<feed>_ingest', id)`. The Go backend holds a persistent `LISTEN` connection, fetches the full row, and the corresponding broker fans out to SSE clients with per-client filtering. Netlog events are enriched with Juniper reference data when available, and the netlog detail page additionally pulls device/IP/prefix/ASN/interface context from Netbox on demand.

**Why two syslog feeds?** Network devices (Juniper, Cisco, Arista) and servers (Linux, Docker, PostgreSQL) produce fundamentally different log profiles. Splitting them lets you apply independent retention policies, notification rules, and analysis. Both feeds (and applog) are always enabled; a feed you don't point logs at simply stays empty.

**Application logs:** apps `POST` JSON batches to `/api/v1/applog/ingest`. The handler inserts into `applog_events` and broadcasts directly to the `AppLogBroker` — no LISTEN/NOTIFY. The broker applies per-client filters and pushes matching events to SSE clients.

## rsyslog Filtering

Network devices — especially Juniper gear — emit thousands of syslog messages per minute: chassis polls, SNMP traps, session logs, scheduler ticks, and routine daemon output. Taillight ships a modular rsyslog configuration that applies layered filters to drop the noise before it hits the netlog database.

### Processing Pipeline

```
UDP/TCP input (514, 1514)
  → parse RFC 5424 structured data
  → capture critical severity (emerg/alert/crit) before any filtering
  → filter by msgid         (fastest — exact event name match)
  → route UI_COMMIT events  (Oxidized, commit log)
  → filter by programname   (daemon-level drops)
  → filter by facility      (local7 info noise)
  → filter by severity      (drop debug globally)
  → filter by hostname/IP   (optional per-host rules)
  → output to PostgreSQL, LibreNMS, per-host files, remote forwarding
```

### Filter Layers

Filters are applied cheapest-first. Each layer has exception keywords — messages containing `error`, `fail`, `critical`, `down`, `denied`, or `alarm` pass through even if the event type is normally dropped.

| Layer | File | Method | Drops |
|-------|------|--------|-------|
| msgid | `filters/05-by-msgid.conf` | Exact `$msgid` match | Chassis polls, RPD scheduler, RT_FLOW sessions, SNMP traps, LLDP neighbor-up, PFE stats, license checks |
| Commit routing | `filters/06-ui-commit-trigger.conf` | `$msgid` match | Routes UI_COMMIT to Oxidized and commit log |
| Program | `filters/10-by-programname.conf` | `$programname` match | cron, ntpd, mib2d, dcd, lacpd, cosd, alarmd, sshd, pfed |
| Facility | `filters/30-by-facility.conf` | `$syslogfacility` | local7 info-level messages |
| Severity | `filters/40-by-severity.conf` | `$syslogseverity` | All debug (severity 7) |
| Hostname | `filters/50-by-hostname.conf` | `$hostname`/`$fromhost-ip` | Nothing by default (examples only) |

### Juniper Device Setup

Devices must send RFC 5424 structured-data syslog for msgid-based filters to work:

```
set system syslog host <collector-ip> any notice
set system syslog host <collector-ip> port 514
set system syslog host <collector-ip> source-address <loopback-ip>
set system syslog host <collector-ip> structured-data
```

### Customization

- **Add msgid filter**: add a block to `filters/05-by-msgid.conf`
- **Add daemon filter**: add a block to `filters/10-by-programname.conf`
- **Filter specific hosts**: uncomment examples in `filters/50-by-hostname.conf`
- **Test changes**: `cd rsyslog && make test` or `docker compose run --rm test`

See [`rsyslog/README.md`](rsyslog/README.md) for the full reference including deployment, PostgreSQL output setup, and Juniper configuration details.

## Quickstart

### Docker Compose

```sh
cp .env.example .env
docker compose up -d
```

This starts TimescaleDB, the API, rsyslog, and the frontend.

| Service    | Host Port | Variable             |
|------------|-----------|----------------------|
| Frontend   | 3000      | `FRONTEND_HOST_PORT` |
| API        | 8080      | `API_HOST_PORT`      |
| PostgreSQL | 5432      | `POSTGRES_BIND`      |
| rsyslog (netlog) | 1514 | `RSYSLOG_NETLOG_PORT` |
| rsyslog (srvlog) | 1515 | `RSYSLOG_SRVLOG_PORT` |

### Create a user

```sh
docker compose exec api /app useradd --username admin --password admin
```

### Generate test data

Development/demo tooling: the main binary ships three load generators (`loadgen-netlog`, `loadgen-srvlog`, `loadgen-applog`) for seeding a fresh instance with realistic events.

```sh
# Netlog events — network device logs (direct SQL insert)
docker compose exec api /app loadgen-netlog -n 100 --delay 100ms --jitter 200ms

# Netlog events via rsyslog (full pipeline)
docker compose exec api /app loadgen-netlog -n 100 --syslog rsyslog:514 --delay 100ms

# Srvlog events — server logs (direct SQL insert)
docker compose exec api /app loadgen-srvlog -n 100 --delay 100ms --jitter 200ms

# Srvlog events via rsyslog (full pipeline)
docker compose exec api /app loadgen-srvlog -n 100 --syslog rsyslog:514 --delay 100ms

# Application log events (HTTP ingest)
docker compose exec api /app loadgen-applog -n 100 --batch 1 \
  --endpoint http://localhost:8080/api/v1/applog/ingest
```

## Log Shipper

**`taillight-shipper`** is a standalone binary that tails log files and pipes stdin, shipping structured log entries to the ingest API. Use it to onboard any application that writes to files or stdout.

**`pkg/logshipper`** is a Go `slog.Handler` — add it to your application to ship logs directly from code without an external process.

See [`cmd/taillight-shipper/`](api/cmd/taillight-shipper/) for configuration and usage.

## Terminal UI & SSH access

The terminal UI client (`taillight-tui`) and the SSH server that hosts it
(`taillight-wish`) live in the companion repository
**[taillight-tui](https://github.com/lasseh/taillight-tui)**. Both are HTTP/SSE
clients of this API — see that repo for installation, configuration, and usage.

## Configuration

### `.env` — per-deployment settings

| Variable | Default | Description |
|----------|---------|-------------|
| `POSTGRES_PASSWORD` | `taillight` | Database password |
| `POSTGRES_BIND` | `127.0.0.1:5432` | Bind address and port for PostgreSQL (`host:port`). Set to `0.0.0.0:5432` for remote access or change the port to avoid conflicts. |
| `API_HOST_PORT` | `8080` | Host port for the API |
| `RSYSLOG_NETLOG_PORT` | `1514` | Host port for netlog syslog input (`514` in production) |
| `RSYSLOG_SRVLOG_PORT` | `1515` | Host port for srvlog syslog input (`515` in production) |
| `FRONTEND_HOST_PORT` | `3000` | Host port for the web UI |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
| `AUTH_ENABLED` | `false` | Enable authentication |
| `REAL_IP_HEADER` | *(empty)* | Trusted client-IP header set by your reverse proxy (e.g. `X-Real-IP`). Empty = trust only the TCP peer. Set it behind nginx or clients are attributed to the proxy IP. |
| `API_URL` | *(empty)* | Frontend API URL (empty = same-origin) |

### `api/config.yml` — application tuning

CORS origins, connection pool sizes, retention policies, notification engine, SMTP, AI analysis, and Netbox enrichment. See [`config.yml.example`](api/config.yml.example) for all options.

Environment variables always override config file values (Viper priority: defaults → config.yml → env vars).

## Local Development

**API:**

```sh
cd api
cp config.yml.example config.yml
make build && make test && make lint
```

**Frontend:**

```sh
cd frontend
npm install && npm run dev
```

**CLI commands:**

| Command | Description |
|---------|-------------|
| `serve` | Start the HTTP/SSE server |
| `migrate` | Run database migrations (up/down/version) |
| `loadgen-netlog` | Generate netlog test events (Juniper, Cisco, Arista) |
| `loadgen-srvlog` | Generate srvlog test events (Linux, Docker, PostgreSQL) |
| `loadgen-applog` | Generate application log test events |
| `useradd` | Create a user account |
| `apikey` | Manage API keys |
| `import` | Import Juniper netlog reference data (XLSX) |
| `version` | Print the build version |

### Importing Juniper Reference Data

Copy the XLSX files into the container, then run the import:

```sh
docker compose cp System_Log_Messages_Junos_OS_25.4R1.xlsx api:/tmp/
docker compose cp System_Log_Messages_Junos_OS_Evolved_25.4R1.xlsx api:/tmp/

docker compose exec api /app import --file /tmp/System_Log_Messages_Junos_OS_25.4R1.xlsx --os junos
docker compose exec api /app import --file /tmp/System_Log_Messages_Junos_OS_Evolved_25.4R1.xlsx --os junos-evolved
```

Or upload directly to a running server via the admin API. Requires an API key with the `admin` scope (`apikey` command) and accepts `os=junos` or `os=junos-evolved`:

```sh
curl -X POST "https://<host>/api/v1/juniper/ref/upload" \
  -H "Authorization: Bearer $TAILLIGHT_API_KEY" \
  -F "os=junos" \
  -F "file=@System_Log_Messages_Junos_OS_25.4R1.xlsx"
```

Response: `{"parsed": N, "upserted": M}`. Max request size is 10 MiB.

## Components

| Directory | Description |
|-----------|-------------|
| `api/` | Go backend (chi router, pgx, SSE, LISTEN/NOTIFY) |
| `frontend/` | Vue 3 SPA (TypeScript, Tailwind CSS) |
| `rsyslog/` | Modular rsyslog filtering config for network devices |
| `api/cmd/taillight/` | Main server binary (`serve`, `migrate`, loadgens, `useradd`, `apikey`, `import`) |
| `api/cmd/taillight-shipper/` | Standalone log file tailer and ingest shipper |
| `pkg/logshipper/` | Go `slog.Handler` for programmatic log shipping |
| `sdk/python/` | Python `logging.Handler` SDK (`pip install taillight-sdk`) |
| `docs/` | Architecture, internals, notifications, and deployment guides |

## Documentation

- [Overview](docs/OVERVIEW.md) — features, quickstart, configuration, CLI reference
- [Architecture](docs/ARCHITECTURE.md) — system design, data flow, deployment topology
- [Internals](docs/INTERNALS.md) — SSE brokers, LISTEN/NOTIFY, pagination, auth
- [Notifications](docs/NOTIFICATIONS.md) — rules, channels, silence/digest model, tuning, troubleshooting
- [Interactive API Docs](http://localhost:8080/api/docs) — Scalar/OpenAPI UI (when running locally)
- [Python SDK](docs/python-logshipper.md) — Python logging handler, Django/Flask integration
- [rsyslog Config](rsyslog/README.md) — rsyslog deployment and filtering
- [nginx Examples](docs/nginx-reverse-proxy.conf.example) — production reverse proxy config

## Releases

Taillight is versioned with [semver](https://semver.org/) tags (`vX.Y.Z`). Each
release on the [releases page](https://github.com/lasseh/taillight/releases)
ships cross-compiled `taillight` and `taillight-shipper` binaries
(linux/darwin, amd64/arm64) and a multi-arch Docker image at
`ghcr.io/lasseh/taillight`. The Python SDK (`taillight-sdk`) releases
independently to PyPI via its own `py-vX.Y.Z` tags.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, and PR guidelines.

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

---

Built with Claude Code as an implementation aid — all architectural decisions are mine.

taillight

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README