npm package: @hotelkite/hydra
Description: Production-ready local observability platform. OpenTelemetry traces & logs with S3 persistence.
Author: HotelKite
Latest version: 0.2.0

# @hotelkite/hydra

Production-ready local observability platform. OpenTelemetry traces & logs with optional S3 persistence.

## Install

```bash
npm install -g @hotelkite/hydra
```

## Quick Start

```bash
# First run - interactive setup wizard
hydra

# Or use npx (no global install)
npx @hotelkite/hydra
```

On first run, Hydra will ask you to configure:
- Storage type (Memory or S3)
- S3 credentials (if using S3)
- Data retention period

## Endpoints

| Port | Protocol | Description |
|------|----------|-------------|
| 4317 | gRPC | OTLP traces & logs |
| 4318 | HTTP | OTLP traces & logs |
| 8080 | HTTP | Web UI & API |

## Point Your App

```bash
# For gRPC (recommended)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# For HTTP
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
```

## Authentication

Hydra uses API keys for security:

- **Admin Key**: Full access to dashboard and API (auto-generated on first run)
- **Ingest Keys**: For applications to send telemetry (create via dashboard)

Find your admin key in the config file:
- Windows: `%APPDATA%\hydra\hydra\config\config.json`
- macOS/Linux: `~/.config/hydra/config.json`

## Features

- 🔍 **Traces**: Distributed tracing with span visualization
- 📝 **Logs**: Correlated logs with trace context
- 🔐 **Auth**: Admin keys + ingest keys with Argon2 hashing
- 💾 **Storage**: In-memory or S3 + Parquet + DuckDB
- 🎨 **Dashboard**: Built-in web UI with date filters
- 📊 **API**: REST API with Swagger UI at `/swagger-ui`

## Node.js Example

```javascript
// tracing.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPLogExporter } = require('@opentelemetry/exporter-logs-otlp-grpc');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const grpc = require('@grpc/grpc-js');

// Create metadata with ingest key
const metadata = new grpc.Metadata();
metadata.set('authorization', `Bearer ${process.env.HYDRA_INGEST_KEY}`);

const sdk = new NodeSDK({
  serviceName: 'my-service',
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4317',
    metadata,
  }),
  logRecordProcessor: new SimpleLogRecordProcessor(
    new OTLPLogExporter({
      url: 'http://localhost:4317',
      metadata,
    })
  ),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();
```

```bash
HYDRA_INGEST_KEY=hydra_ingest_xxx node -r ./tracing.js app.js
```

## Storage Options

### Memory (Default)
Fast, no setup. Data lost on restart.

### S3 + Parquet
Persistent storage with DuckDB queries. Supports:
- AWS S3
- MinIO
- Any S3-compatible storage

Data is stored as Parquet files with date partitioning for fast queries.

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/services` | List discovered services |
| GET | `/api/traces` | Query traces |
| GET | `/api/traces/:id` | Get trace by ID |
| GET | `/api/logs` | Query logs |
| POST | `/api/keys` | Create ingest key |
| GET | `/api/keys` | List ingest keys |
| DELETE | `/api/keys/:id` | Revoke ingest key |

All endpoints require `Authorization: Bearer <admin_key>` header.

## More Info

- GitHub: https://github.com/bookingjini-tech/hydra
- Swagger UI: http://localhost:8080/swagger-ui (when running)