██╗  ██╗██╗   ██╗██████╗ ██████╗  █████╗ 
    ██║  ██║╚██╗ ██╔╝██╔══██╗██╔══██╗██╔══██╗
    ███████║ ╚████╔╝ ██║  ██║██████╔╝███████║
    ██╔══██║  ╚██╔╝  ██║  ██║██╔══██╗██╔══██║
    ██║  ██║   ██║   ██████╔╝██║  ██║██║  ██║
    ╚═╝  ╚═╝   ╚═╝   ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝
                                              
    Lightweight production observability.
    Single binary. S3 persistence. Just works.

---

What is this?

Full observability without the complexity. No Kafka. No Elasticsearch. No 50-service Kubernetes deployment.

One binary. Traces + Logs. S3 storage. Done.

# Quick start
npx @hotelkite/hydra

# Or install globally
npm install -g @hotelkite/hydra && hydra

# Or with Docker
docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 ghcr.io/bookingjini-tech/hydra

# Or build from source
cargo build --release
./target/release/hydra

First run launches an interactive setup wizard.

---

Quick Start

1. Run Hydra

npx @hotelkite/hydra

2. Configure (first run only)

? Select storage type:
  > Memory (fast, data lost on restart)
    S3 (persistent, production-ready)

? S3 bucket name: my-observability-bucket
? AWS region: us-east-1
? Data retention (days): 30

3. Point your app

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

4. Open dashboard

http://localhost:8080

---

Features

Feature	Description
🔍 Distributed Tracing	Full trace visualization with span waterfall
📝 Correlated Logs	Logs auto-linked to traces via trace context
💾 S3 + Parquet	Persistent storage with date partitioning
🔐 API Keys	Admin keys + ingest keys with Argon2 hashing
📊 DuckDB Queries	Fast analytical queries on historical data
🎨 Built-in Dashboard	Web UI with date filters and detail views
📖 Swagger UI	Interactive API docs at /swagger-ui
⚡ Single Binary	No dependencies, no infrastructure

---

Endpoints

Port	Protocol	Purpose
4317	gRPC	OTLP traces & logs
4318	HTTP	OTLP traces & logs
8080	HTTP	Web UI + REST API

---

Authentication

Hydra uses two types of API keys:

Admin Key — Full access to dashboard and management APIs

• Auto-generated on first run
• Stored in config file
• Required for dashboard login

Ingest Keys — For applications to send telemetry

• Create via dashboard or API
• Scoped to ingestion only
• Revocable

# Create ingest key
curl -X POST http://localhost:8080/api/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-service"}'

# Use in your app
export HYDRA_INGEST_KEY=hydra_ingest_xxx

---

Storage Options

Memory

• Fast, zero setup
• Data lost on restart
• Good for development

S3 + Parquet + DuckDB

• Persistent storage
• Date-partitioned Parquet files
• Fast analytical queries via DuckDB
• Supports AWS S3, MinIO, any S3-compatible storage

s3://bucket/
├── traces/
│   └── year=2026/month=01/day=28/
│       └── service-name-uuid.parquet
├── logs/
│   └── year=2026/month=01/day=28/
│       └── service-name-uuid.parquet
└── index/
    └── services.json

---

API

All endpoints require Authorization: Bearer <admin_key> header.

# Services
GET /api/services              # List discovered services
GET /api/services/:name        # Get service details

# Traces
GET /api/traces                # Query traces (?service=&from=&to=&limit=)
GET /api/traces/:id            # Get full trace with all spans

# Logs
GET /api/logs                  # Query logs (?service=&from=&to=&severity=&limit=)

# Keys
POST /api/keys                 # Create ingest key
GET /api/keys                  # List ingest keys
DELETE /api/keys/:id           # Revoke ingest key

# Health
GET /health                    # Health check (no auth)

---

Examples

Node.js

cd examples/node-express
npm install
HYDRA_INGEST_KEY=your_key npm start

Python

cd examples/python-fastapi
pip install -r requirements.txt
HYDRA_INGEST_KEY=your_key python app.py

---

Config Location

OS	Path
Windows	%APPDATA%\hydra\hydra\config\config.json
macOS	~/Library/Application Support/hydra/config.json
Linux	~/.config/hydra/config.json

---

Why Hydra?

	Jaeger	Datadog	Hydra
Setup	Elasticsearch + Kafka	SaaS signup	Single binary
Cost	Infrastructure	Per-host pricing	Free
Storage	Complex	Managed	S3 (you control)
Latency	Network hops	Cloud	Local/your infra

Hydra is for teams who want observability without the operational overhead.

---

Tech Stack

• Rust + Tokio — Async runtime
• Tonic — gRPC server
• Axum — HTTP server
• DuckDB — Analytical queries
• Arrow + Parquet — Columnar storage
• AWS SDK — S3 integration

---

License

MIT