Workers Sentinel

Workers Sentinel is a lightweight, self-hosted error tracking and monitoring solution that runs entirely on your Cloudflare account. It accepts events using the Sentry SDK wire format, allowing you to use existing Sentry SDKs by simply changing the DSN endpoint. All your error data is stored securely in SQLite-backed Durable Objects, giving you full control over your information.

Table of Contents

• Overview
• Why Workers Sentinel?
• Key Features
• Prerequisites
• Getting Started
• SDK Configuration
• Architecture
• Roadmap & Future Enhancements
• Known Limitations
• Contributing
• License

Overview

Workers Sentinel gives you a private, self-hosted error tracking solution with a modern web dashboard. By leveraging the Cloudflare ecosystem, it offers a cost-effective and scalable alternative to hosted error tracking services. All your data is stored in your own Durable Objects with SQLite storage, giving you complete control and privacy.

Why Workers Sentinel?

🔒 Privacy First

• All data stays in YOUR Cloudflare account
• No third-party tracking or data sharing
• You control your error data completely

💰 Cost-Effective

• Runs on Cloudflare's generous free tier
• Pay only for what you use beyond free limits
• No monthly subscription fees

⚡ Performance

• Built on Cloudflare's global edge network
• Fast error ingestion worldwide
• Serverless architecture scales automatically

🔌 SDK Compatible

• Works with existing Sentry SDKs
• Just change your DSN endpoint
• Supports JavaScript, Python, Go, and more

🎨 Modern Dashboard

• Clean, intuitive interface
• Stack trace visualization
• Issue grouping and management

🛠️ Easy Setup

• Deploy with one click
• Automatic project creation
• Smart authentication setup

Key Features

• 🔌 Sentry SDK Compatible: Use existing Sentry SDKs by changing only the DSN endpoint
• 🔒 Secure & Private: Self-hosted on your Cloudflare account with no third-party data access
• 🔐 Smart Authentication: Automatic first-user admin setup with session-based auth
• 📊 Issue Grouping: Automatic fingerprinting groups similar errors into issues
• 📈 Event Statistics: Track error frequency with hourly aggregations
• 🔍 Stack Traces: Full stack trace visualization with code context
• 👥 User Tracking: See how many users are affected by each issue
• 🏷️ Tags & Context: View tags, breadcrumbs, and contextual data
• ✅ Issue Management: Mark issues as resolved or ignored
• 🌐 Multi-Project: Create multiple projects with isolated data storage

Prerequisites

Before deploying Workers Sentinel, make sure you have:

• Cloudflare Account - Sign up for free
• Node.js 20+ - For local development (not required for one-click deployment)

Cloudflare Services Used:

• Workers (Compute)
• Durable Objects with SQLite (State management)
• Workers Assets (Dashboard hosting)

All these services have generous free tiers sufficient for most use cases.

Getting Started

One-Click Deploy

Use the "Deploy to Cloudflare" button above, or run:

npm create cloudflare@latest -- --template=https://github.com/G4brym/workers-sentinel/tree/main/template

Manual Deployment

# Clone the repository
git clone https://github.com/G4brym/workers-sentinel.git
cd workers-sentinel

# Install dependencies
pnpm install

# Build and deploy
pnpm deploy

First-Time Setup

1. Deploy your worker to Cloudflare
2. Visit your worker URL in a browser
3. Register the first user - this becomes your admin account
4. Create your first project - you'll receive a DSN
5. Configure your Sentry SDK with the DSN

SDK Configuration

Workers Sentinel is compatible with official Sentry SDKs. Simply use your Sentinel DSN instead of a Sentry DSN.

Cloudflare Workers (Service Binding with RPC)

For Cloudflare Workers, you can use service bindings with RPC for optimal performance. This routes requests internally within Cloudflare's network, avoiding external HTTP roundtrips and reducing latency.

Step 1: Add a service binding to your worker's wrangler.jsonc:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_flags": ["nodejs_als"],
  "services": [
    { "binding": "SENTINEL", "service": "workers-sentinel", "entrypoint": "SentinelRpc" }
  ]
}

Step 2: Initialize Sentry with the RPC transport:

import * as Sentry from '@sentry/cloudflare';
import { waitUntil } from 'cloudflare:workers';

const DSN = 'https://<public_key>@<your-worker>.workers.dev/<project_id>';

export default Sentry.withSentry(
  (env: Env) => ({
    dsn: DSN,
    transport: () => ({
      send: async (envelope) => {
        const rpcPromise = env.SENTINEL.captureEnvelope(DSN, envelope);
        waitUntil(rpcPromise);
        const result = await rpcPromise;
        return { statusCode: result.status };
      },
      flush: async () => true,
    }),
  }),
  {
    async fetch(request, env, ctx) {
      // Your worker code here
      return new Response('Hello!');
    },
  }
);

The waitUntil call ensures the RPC completes even after the HTTP response returns. The captureEnvelope method takes the DSN and envelope, handling authentication and ingestion internally.

JavaScript / Browser

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'https://<public_key>@<your-worker>.workers.dev/<project_id>',
});

Node.js

const Sentry = require('@sentry/node');

Sentry.init({
  dsn: 'https://<public_key>@<your-worker>.workers.dev/<project_id>',
});

Python

import sentry_sdk

sentry_sdk.init(
    dsn="https://<public_key>@<your-worker>.workers.dev/<project_id>",
)

Go

import "github.com/getsentry/sentry-go"

sentry.Init(sentry.ClientOptions{
    Dsn: "https://<public_key>@<your-worker>.workers.dev/<project_id>",
})

The DSN is displayed when you create a project in the dashboard, or you can find it in the project settings.

Architecture

Workers Sentinel is built with modern web technologies:

Backend (Worker):

• Hono - Fast, lightweight web framework
• Cloudflare Durable Objects - Distributed state with SQLite storage
• Sentry Envelope Parser - Compatible with Sentry SDK wire format

Frontend (Dashboard):

• Vue.js 3 - Progressive JavaScript framework
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• Pinia - State management
• Vite - Fast build tooling

Data Architecture:

• AuthState DO (singleton) - Users, sessions, project registry
• ProjectState DO (per-project) - Issues, events, statistics

Each project has its own isolated Durable Object with SQLite storage, ensuring data isolation and scalability.

Roadmap & Future Enhancements

Planned features for future releases:

• [ ] Source map support for JavaScript errors
• [ ] Release tracking and deployment correlation
• [ ] Performance monitoring (transactions, spans)
• [ ] Alerting integrations (webhook, email)
• [ ] Session replay support
• [ ] Team/organization support
• [ ] Issue assignment
• [ ] Search functionality
• [ ] Time-series charts
• [ ] Rate limiting per project
• [ ] Event retention policies

Known Limitations

Current Limitations:

• No source map support yet (stack traces show minified code)
• No performance monitoring (error tracking only)
• No alerting/notifications
• Single-user admin (no team management yet)

Sentry Feature Parity: Workers Sentinel focuses on core error tracking. Advanced Sentry features like:

• Session replay
• Performance monitoring
• Profiling
• Crons monitoring

Are not currently supported but may be added in future versions.

Browser Compatibility:

• Modern browsers required (Chrome 90+, Firefox 88+, Safari 14+)
• JavaScript must be enabled
• Cookies must be enabled for authentication

Contributing

We welcome contributions from the community!

🐛 Bug Reports

• Use the GitHub Issues page
• Include reproduction steps
• Specify your environment

✨ Feature Requests

• Check existing issues first
• Explain the use case and benefit

💻 Code Contributions

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a Pull Request

Development Setup:

# Clone and install
git clone https://github.com/G4brym/workers-sentinel.git
cd workers-sentinel
pnpm install

# Start development (runs wrangler dev)
pnpm dev

# Build dashboard
pnpm --filter @workers-sentinel/dashboard build

# Typecheck
pnpm typecheck

# Lint
pnpm lint

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for the self-hosted community

If you find Workers Sentinel useful, please consider giving it a ⭐ on GitHub!