Sibyl
v0.1.0

Getting Started

Sibyl is an AI-native observability platform that investigates incidents automatically. Get started in under 5 minutes.

QUICK START

1

Create an account

Sign up and create your first project to get a DSN.

2

Install the SDK

Add the Sibyl SDK to your project.

3

Start investigating

Errors and traces flow in automatically. Ask Sibyl to investigate any incident.

Installation

Install the Sibyl SDK for your platform.

Node.js

bash
npm install @sibyl/node

Python

bash
pip install sibyl-sdk

Configuration

Initialize Sibyl with your project DSN. You can find this in your project settings.

DSN Format

text
https://<public-key>@ingest.sibyl.dev/<project-id>

Environment Variables

VariableRequiredDescription
SIBYL_DSNYesYour project DSN from the dashboard
SIBYL_ENVIRONMENTNoEnvironment name (production, staging, dev)
SIBYL_SAMPLE_RATENoEvent sample rate from 0.0 to 1.0 (default: 1.0)
SIBYL_DEBUGNoEnable debug logging (default: false)

Node.js SDK

The Node.js SDK auto-captures unhandled exceptions, promise rejections, and HTTP breadcrumbs.

Basic Setup

typescript
import { Sibyl } from '@sibyl/node';

Sibyl.init({
  dsn: process.env.SIBYL_DSN,
  environment: 'production',
});

Manual Capture

typescript
// Capture an error
try {
  await riskyOperation();
} catch (err) {
  Sibyl.captureException(err, {
    service: 'payment-service',
    userId: user.id,
  });
}

// Capture a message
Sibyl.captureMessage('Deployment started', 'info', {
  version: '1.2.3',
});

Graceful Shutdown

typescript
process.on('SIGTERM', async () => {
  await Sibyl.flush();
  await Sibyl.close();
  process.exit(0);
});

Python SDK

The Python SDK supports FastAPI, Django, and the standard logging module.

Basic Setup

python
import sibyl

sibyl.init(
    dsn="https://key@ingest.sibyl.dev/proj_123",
    environment="production",
)

FastAPI Integration

python
from fastapi import FastAPI
from sibyl.integrations.fastapi import SibylMiddleware

app = FastAPI()
app.add_middleware(SibylMiddleware)

Django Integration

python
# settings.py
MIDDLEWARE = [
    'sibyl.integrations.django.SibylMiddleware',
    # ... other middleware
]

API Reference

All API endpoints require authentication via Bearer token or API key.

POST/v1/ingest

Batch ingest events and spans

{ "events": [...], "spans": [...] }
POST/v1/investigate

Start an AI investigation (SSE stream)

{ "query": "Why are we seeing 500s?", "projectId": "..." }
GET/api/explore/logs

Search and filter log events

?level=error&service=api&from=2024-01-01
GET/api/explore/traces

List distributed traces

?service=api&minDuration=1000
GET/api/incidents

List grouped incidents

?status=open&level=error
POST/api/search

Hybrid semantic + keyword search

{ "query": "database connection timeout" }

Integrations

Framework-specific middleware for automatic error and performance capture.

Express.js

typescript
import express from 'express';
import { Sibyl } from '@sibyl/node';
import { sibylExpressMiddleware } from '@sibyl/node/integrations/express';

Sibyl.init({ dsn: process.env.SIBYL_DSN });

const app = express();
app.use(sibylExpressMiddleware());

// Your routes...

app.listen(3000);

Next.js

typescript
// next.config.js
const { withSibyl } = require('@sibyl/node/integrations/nextjs');

module.exports = withSibyl({
  // your Next.js config
});

OpenTelemetry

typescript
import { SibylSpanExporter } from '@sibyl/node';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';

const provider = new NodeTracerProvider();
provider.addSpanProcessor(
  new SimpleSpanProcessor(new SibylSpanExporter())
);
provider.register();

Self-Hosting

Run Sibyl on your own infrastructure with Docker Compose.

Prerequisites

  • Docker & Docker Compose
  • Node.js 20+
  • pnpm 9+
  • Google AI Studio API key (free tier)

1. Start Infrastructure

bash
git clone https://github.com/your-org/sibyl.git
cd sibyl
cp .env.example .env.local

# Start PostgreSQL, Redis, ClickHouse, Qdrant
docker compose -f infra/docker-compose.yml up -d

2. Install & Run

bash
pnpm install
pnpm db:push          # Apply database schema
pnpm dev              # Start web + ingest service

3. Environment Variables

bash
# .env.local
DATABASE_URL=postgresql://sibyl:sibyl@localhost:5432/sibyl
CLICKHOUSE_URL=http://localhost:8123
REDIS_URL=redis://localhost:6379
QDRANT_URL=http://localhost:6333
GEMINI_API_KEY=your-api-key
JWT_SECRET=your-secret-key
NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_INGEST_URL=http://localhost:3001
Sibyl Documentation v0.1.0Back to home