hono-telescope

⚠️ Beta Release: This package is currently in beta. APIs may change before the stable release.

A powerful debugging and monitoring tool for Hono applications, inspired by Laravel Telescope. Monitor HTTP requests, exceptions, logs, and database queries with a beautiful web dashboard.

---

🌐 Live Demo

🎉 Try it live! No installation needed. Test all features on our hosted example:

📊 Hono Telescope Dashboard

API Base URL: https://hono-telescope-9lvpv.ondigitalocean.app

---

✨ Features

Currently Available:

• 🔍 HTTP Request Monitoring - Track all incoming and outgoing requests with detailed headers and payloads
• 🚨 Exception Tracking - Capture and monitor application errors with stack traces
• 📝 Log Monitoring - Monitor console logs with different severity levels
• 🗄️ Database Query Monitoring - Track SQL queries (Prisma, Sequelize, MongoDB, Bun SQLite) with execution time
• 📊 Beautiful Dashboard - Modern React-based web interface with real-time updates
• 🎯 Zero Configuration - Works out of the box with sensible defaults
• 🏷️ Tagging System - Organize entries with custom tags and context
• 🔧 TypeScript Support - Full type definitions and type safety
• ⚡ High Performance - Minimal overhead with efficient memory management
• 🌐 Bun & Node.js - Works with both runtimes seamlessly
• 🗂️ Multiple Database Support - Integrates with popular database libraries

Planned Features (Roadmap):

• 🎨 Code Formatting - Built-in Prettier integration for consistent code style
• 🔖 Automated Versioning - Release-it integration for semantic versioning
• 💾 Data Export - Export monitored data in multiple formats (JSON, CSV)
• 🔔 Alerts & Notifications - Real-time alerts for errors and performance issues
• 📈 Analytics & Reporting - Advanced analytics and historical data analysis
• 🔐 Authentication & Authorization - Dashboard access control
• 🌍 Multi-Tenancy Support - Support for multiple isolated projects
• 📱 Mobile Dashboard - Responsive mobile-friendly dashboard improvements
• 🧩 Plugin System - Extensible plugin architecture for custom integrations
• 🔄 Data Persistence - Optional database storage for long-term monitoring

📦 Installation

# Using npm
npm install hono-telescope

# Using yarn
yarn add hono-telescope

# Using pnpm
pnpm add hono-telescope

# Using bun
bun add hono-telescope

Quick Start

import { Hono } from 'hono';
import { setupTelescope } from 'hono-telescope';

const app = new Hono();

// Setup Telescope with default configuration
setupTelescope(app);

// Your routes
app.get('/', (c) => {
  console.log('Home page accessed');
  return c.json({ message: 'Hello World!' });
});

export default app;

Visit http://localhost:3000/telescope to access the dashboard.

📋 Complete Example: See src/example/index.ts for a full working example with all Telescope features including database query monitoring, multiple HTTP clients (fetch + Axios), and error handling.

API Testing

Try the Live Demo

Visit the live dashboard and test these endpoints:

API Base: https://hono-telescope-9lvpv.ondigitalocean.app

Quick Test with Shell Script

Run all endpoints at once with our test script:

# Download and run the test script
bash <(curl -s https://raw.githubusercontent.com/jubstaaa/hono-telescope/main/src/example/test-all-endpoints.sh)

Or if you have the repo cloned locally:

bash src/example/test-all-endpoints.sh

This will automatically test all endpoints and populate the Telescope dashboard with data! ✨

Available Test Endpoints

Users Management

# Get all users
curl https://hono-telescope-9lvpv.ondigitalocean.app/api/users

# Create a new user
curl -X POST https://hono-telescope-9lvpv.ondigitalocean.app/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "[email protected]", "username": "johndoe"}'

# Get user by ID
curl https://hono-telescope-9lvpv.ondigitalocean.app/api/users/1

# Update user
curl -X PUT https://hono-telescope-9lvpv.ondigitalocean.app/api/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "username": "janedoe"}'

# Delete user
curl -X DELETE https://hono-telescope-9lvpv.ondigitalocean.app/api/users/1

Database Operations (SQLite with Bun)

# Trigger database query
curl https://hono-telescope-9lvpv.ondigitalocean.app/api/health/db

External Requests (HTTP Interceptor)

# Trigger outgoing HTTP request (tested with Axios)
curl https://hono-telescope-9lvpv.ondigitalocean.app/api/external/request

Error Handling (Exception Tracking)

# Trigger an error
curl https://hono-telescope-9lvpv.ondigitalocean.app/api/error

Logging (Log Monitoring)

# Trigger log entries
curl https://hono-telescope-9lvpv.ondigitalocean.app/api/logs

View the Dashboard

After making requests, visit the Telescope Dashboard to see:

• 📊 Incoming Requests - All HTTP requests with headers, payload, and response
• 📤 Outgoing Requests - External API calls made by the app
• 📝 Logs - Console logs captured in real-time
• ⚠️ Exceptions - Errors and stack traces
• 🗄️ Queries - Database queries with execution time
• 📈 Statistics - Summary of all monitored events

Configuration

import { setupTelescope } from 'hono-telescope';

setupTelescope(app, {
  enabled: true, // Enable/disable Telescope
  path: '/telescope', // Dashboard path
  max_entries: 1000, // Maximum entries to store
  ignored_paths: ['/health'], // Paths to ignore
  watchers: {
    requests: true, // Monitor HTTP requests
    exceptions: true, // Monitor exceptions
    logs: true, // Monitor logs
    queries: true, // Monitor database queries
  },
});

Database Query Monitoring

Hono Telescope automatically intercepts and monitors queries from:

• Prisma - Full ORM support with $queryRaw and $executeRaw
• Sequelize - SQL ORM query tracking
• MongoDB - NoSQL document operations
• Bun SQLite - Native SQLite database queries

Queries are automatically captured with:

• ⏱️ Execution time
• 📋 Query text and bindings
• 🔗 Parent request context
• 🚨 Error information if query fails

Development

Getting Started

First, install dependencies:

bun install

Then build the project for the first time:

bun run build

Running in Development Mode

Hono Telescope requires three separate processes running simultaneously for full development experience. Open three terminal windows:

Terminal 1 - TypeScript Compilation (Watch Mode)

bun run dev

This watches for TypeScript changes and compiles them to JavaScript.

Terminal 2 - Example Application

bun run dev:example

This starts the example Hono application with hot reload at http://localhost:3000

• Example API endpoints: http://localhost:3000/api/...