@geekmidas/telescope

中文文档
9.6.1发布于 2026/11/16TypeScriptESM + CJS构建来源已验证近 30 天下载 1.4万

Laravel Telescope-style debugging and monitoring for web applications

原始使用文档
文档目录32 节
  1. Installation
  2. Quick Start
  3. With Hono
  4. Framework-Agnostic Core
  5. Features
  6. Configuration
  7. Sensitive Data Redaction
  8. Enable Redaction
  9. Default Redacted Paths
  10. Add Custom Paths
  11. Full Control
  12. Path Syntax
  13. Programmatic Access
  14. Storage Backends
  15. InMemoryStorage
  16. KyselyStorage (Coming Soon)
  17. Custom Storage
  18. API
  19. Telescope Class (Core)
  20. Hono Adapter
  21. Lambda Adapter
  22. Logger Integrations
  23. Dashboard API
  24. Query Parameters
  25. WebSocket
  26. Types
  27. RequestEntry
  28. ExceptionEntry
  29. LogEntry
  30. Integration with gkm dev
  31. Best Practices
  32. License

@geekmidas/telescope

Laravel Telescope-style debugging and monitoring for web applications. Capture and inspect HTTP requests, exceptions, and logs in real-time.

Framework-agnostic core with adapters for Hono, AWS Lambda, and more.

Installation

pnpm add @geekmidas/telescope

Quick Start

With Hono

import { Hono } from 'hono';
import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
import { createMiddleware, createUI } from '@geekmidas/telescope/server/hono';

const telescope = new Telescope({
  storage: new InMemoryStorage(),
});

const app = new Hono();

// Add middleware to capture requests
app.use('*', createMiddleware(telescope));

// Mount the dashboard
app.route('/__telescope', createUI(telescope));

// Your routes
app.get('/users', (c) => c.json({ users: [] }));

export default app;

Visit http://localhost:3000/__telescope to view the dashboard.

Framework-Agnostic Core

The core Telescope class is framework-agnostic. You can use it directly for manual recording:

import { Telescope, InMemoryStorage } from '@geekmidas/telescope';

const telescope = new Telescope({
  storage: new InMemoryStorage(),
});

// Record a request manually
await telescope.recordRequest({
  method: 'POST',
  path: '/api/users',
  url: 'http://localhost:3000/api/users',
  headers: { 'content-type': 'application/json' },
  body: { name: 'John' },
  query: {},
  status: 201,
  responseHeaders: {},
  responseBody: { id: '123' },
  duration: 45.2,
});

// Log messages
await telescope.log('info', 'User created', { userId: '123' });

// Record exceptions
try {
  throw new Error('Something went wrong');
} catch (error) {
  await telescope.exception(error);
}

Features

  • Request Recording: Capture HTTP requests with headers, body, query params, and response
  • Exception Tracking: Record exceptions with stack traces and source context
  • Log Aggregation: Collect application logs with context
  • Real-time Updates: WebSocket-powered live dashboard
  • Storage Agnostic: Use in-memory for dev, database for production
  • Hono Integration: First-class middleware and route mounting
  • Lambda Integration: Wrapper and Middy middleware for AWS Lambda with auto-flush

Configuration

const telescope = new Telescope({
  // Required: Storage backend
  storage: new InMemoryStorage(),

  // Optional: Enable/disable telescope (default: true)
  enabled: true,

  // Optional: Dashboard path (default: '/__telescope')
  path: '/__telescope',

  // Optional: Record request/response bodies (default: true)
  recordBody: true,

  // Optional: Max body size to record in bytes (default: 64KB)
  maxBodySize: 64 * 1024,

  // Optional: URL patterns to ignore
  ignorePatterns: ['/health', '/metrics', '/__telescope/*'],

  // Optional: Auto-prune entries older than X hours
  pruneAfterHours: 24,

  // Optional: Redact sensitive data (see Redaction section)
  redact: true,
});

Sensitive Data Redaction

Telescope can automatically redact sensitive data from recorded requests, responses, and logs using @pinojs/redact.

Enable Redaction

const telescope = new Telescope({
  storage: new InMemoryStorage(),

  // Enable with default paths
  redact: true,
});

Default Redacted Paths

When redact: true, these paths are automatically redacted:

Headers:

  • headers.authorization, headers.cookie, headers.x-api-key
  • responseHeaders.set-cookie

Request/Response Body:

  • body.password, body.token, body.accessToken, body.refreshToken
  • body.apiKey, body.secret, body.creditCard, body.cardNumber, body.cvv, body.ssn
  • body.*.password, body.*.token, body.*.secret (nested fields)
  • Same patterns for responseBody.*

Query Parameters:

  • query.token, query.api_key, query.apiKey, query.access_token, query.secret

Log Context:

  • context.password, context.token, context.secret, context.apiKey

Add Custom Paths

Provide an array to add paths (merged with defaults):

const telescope = new Telescope({
  storage: new InMemoryStorage(),

  // Add custom paths to defaults
  redact: ['user.ssn', 'payment.cardNumber', 'data.*.privateKey'],
});

Full Control

Use an object for complete control over redaction:

const telescope = new Telescope({
  storage: new InMemoryStorage(),

  redact: {
    paths: ['headers.authorization', 'body.password'],
    censor: '***HIDDEN***', // Custom replacement (default: '[REDACTED]')
  },
});

Path Syntax

Paths use dot notation with wildcard support:

PatternMatches
headers.authorizationExact path
body.passwordExact nested path
body.*.passwordAny object with password field in body
*.secretSecret field at any level

Programmatic Access

import { createRedactor, DEFAULT_REDACT_PATHS } from '@geekmidas/telescope';

// Create a standalone redactor
const redactor = createRedactor(true);
const safeData = redactor({ headers: { authorization: 'Bearer secret' } });
// safeData.headers.authorization === '[REDACTED]'

// Access default paths
console.log(DEFAULT_REDACT_PATHS);

Storage Backends

InMemoryStorage

Best for development and testing. Data is lost on restart.

// From main package
import { InMemoryStorage } from '@geekmidas/telescope';
// Or direct import
import { InMemoryStorage } from '@geekmidas/telescope/storage/memory';

const storage = new InMemoryStorage({
  maxEntries: 1000, // Max entries per type (default: 1000)
});

KyselyStorage (Coming Soon)

For production use with database persistence.

import { KyselyStorage } from '@geekmidas/telescope/storage/kysely';

const storage = new KyselyStorage(db, {
  tablePrefix: 'telescope_', // Table name prefix
});

Custom Storage

Implement the TelescopeStorage interface:

import type { TelescopeStorage } from '@geekmidas/telescope';

class MyStorage implements TelescopeStorage {
  async saveRequest(entry: RequestEntry): Promise<void> { /* ... */ }
  async getRequests(options?: QueryOptions): Promise<RequestEntry[]> { /* ... */ }
  async getRequest(id: string): Promise<RequestEntry | null> { /* ... */ }

  async saveException(entry: ExceptionEntry): Promise<void> { /* ... */ }
  async getExceptions(options?: QueryOptions): Promise<ExceptionEntry[]> { /* ... */ }
  async getException(id: string): Promise<ExceptionEntry | null> { /* ... */ }

  async saveLog(entry: LogEntry): Promise<void> { /* ... */ }
  async getLogs(options?: QueryOptions): Promise<LogEntry[]> { /* ... */ }

  async prune(olderThan: Date): Promise<number> { /* ... */ }
  async getStats(): Promise<TelescopeStats> { /* ... */ }
}

API

Telescope Class (Core)

telescope.recordRequest(entry)

Record a request entry programmatically.

await telescope.recordRequest({
  method: 'GET',
  path: '/api/users',
  url: 'http://localhost:3000/api/users',
  headers: {},
  query: {},
  status: 200,
  responseHeaders: {},
  duration: 25.5,
});

telescope.log(level, message, context?, requestId?)

Record a log entry programmatically.

await telescope.log('info', 'User logged in', { userId: '123' });
await telescope.log('error', 'Payment failed', { orderId: '456' });

telescope.exception(error, requestId?)

Record an exception programmatically.

try {
  await riskyOperation();
} catch (error) {
  await telescope.exception(error);
  throw error;
}

telescope.broadcast(event)

Send a custom event to all connected WebSocket clients.

telescope.broadcast({
  type: 'custom',
  payload: { message: 'Hello' },
  timestamp: Date.now(),
});

telescope.prune(olderThan)

Manually prune entries older than a date.

const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
const deleted = await telescope.prune(oneHourAgo);
console.log(`Pruned ${deleted} entries`);

telescope.destroy()

Clean up resources (intervals, WebSocket clients).

telescope.destroy();

Hono Adapter

Import from @geekmidas/telescope/server/hono:

import { createMiddleware, createUI, setupWebSocket, getRequestId } from '@geekmidas/telescope/server/hono';

createMiddleware(telescope)

Returns Hono middleware that captures requests and responses.

app.use('*', createMiddleware(telescope));

createUI(telescope)

Returns a Hono app with dashboard UI and API routes.

app.route('/__telescope', createUI(telescope));

setupWebSocket(app, telescope, upgradeWebSocket)

Set up WebSocket routes for real-time updates.

import { createNodeWebSocket } from '@hono/node-ws';

const { upgradeWebSocket } = createNodeWebSocket({ app });
setupWebSocket(createUI(telescope), telescope, upgradeWebSocket);

getRequestId(c)

Get the request ID from Hono context (set by middleware).

app.get('/api/data', (c) => {
  const requestId = getRequestId(c);
  // Use requestId for correlated logging
  telescope.log('info', 'Processing request', { data: 'value' }, requestId);
  return c.json({ success: true });
});

Lambda Adapter

Import from @geekmidas/telescope/adapters/lambda:

import { wrapLambdaHandler, LambdaAdapter } from '@geekmidas/telescope/adapters/lambda';

wrapLambdaHandler(telescope, handler, options?)

Wrap a Lambda handler to automatically record requests and flush telemetry before the Lambda context freezes.

import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
import { wrapLambdaHandler } from '@geekmidas/telescope/adapters/lambda';

const telescope = new Telescope({ storage: new InMemoryStorage() });

export const handler = wrapLambdaHandler(telescope, async (event, context) => {
  // Your Lambda logic here
  return { statusCode: 200, body: JSON.stringify({ success: true }) };
});

Supports API Gateway v1 (REST API), API Gateway v2 (HTTP API), and ALB events. For non-HTTP invocations, records the event as the request body.

Options

wrapLambdaHandler(telescope, handler, {
  // Auto-flush telemetry before Lambda freezes (default: true)
  autoFlush: true,

  // Detect Lambda resource attributes from environment (default: true)
  detectResource: true,
});

LambdaAdapter Class

For more control, use the LambdaAdapter class directly:

import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
import { LambdaAdapter } from '@geekmidas/telescope/adapters/lambda';

const telescope = new Telescope({ storage: new InMemoryStorage() });
const adapter = new LambdaAdapter(telescope);

export const handler = async (event, context) => {
  const requestContext = adapter.extractRequestContext(event);

  try {
    const result = await processEvent(event);

    const responseContext = adapter.extractResponseContext(result, requestContext.startTime);
    await telescope.recordRequest({
      method: requestContext.method,
      path: requestContext.path,
      url: requestContext.url,
      headers: requestContext.headers,
      query: requestContext.query,
      body: requestContext.body,
      ip: requestContext.ip,
      status: responseContext.status,
      responseHeaders: responseContext.headers,
      responseBody: responseContext.body,
      duration: responseContext.duration,
    });

    return result;
  } catch (error) {
    await telescope.exception(error, requestContext.id);
    throw error;
  } finally {
    await adapter.flush();
  }
};

Middy Middleware

For use with the Middy middleware framework:

import middy from '@middy/core';
import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
import { telescopeMiddleware } from '@geekmidas/telescope/adapters/lambda';

const telescope = new Telescope({ storage: new InMemoryStorage() });

export const handler = middy(async (event, context) => {
  return { statusCode: 200, body: JSON.stringify({ success: true }) };
}).use(telescopeMiddleware({ telescope }));

Logger Integrations

Telescope integrates with existing logging libraries so you don't need to change your application code.

Pino Transport

Use with Pino's multistream to send logs to both stdout and Telescope:

import pino from 'pino';
import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
import { createPinoDestination } from '@geekmidas/telescope/logger/pino';

const telescope = new Telescope({ storage: new InMemoryStorage() });

const logger = pino(
  { level: 'debug' },
  pino.multistream([
    { stream: process.stdout },
    { stream: createPinoDestination({ telescope }) }
  ])
);

// Logs go to both console and Telescope
logger.info({ userId: '123' }, 'User logged in');

TelescopeLogger (ConsoleLogger wrapper)

Wraps any Logger interface and forwards logs to Telescope:

import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
import { TelescopeLogger, createTelescopeLogger } from '@geekmidas/telescope/logger/console';
import { ConsoleLogger } from '@geekmidas/logger/console';

const telescope = new Telescope({ storage: new InMemoryStorage() });

// Option 1: Using the class
const logger = new TelescopeLogger({
  telescope,
  logger: new ConsoleLogger({ app: 'myApp' }),
});

// Option 2: Using the factory function
const logger = createTelescopeLogger(telescope, new ConsoleLogger());

// Logs go to both console and Telescope
logger.info({ action: 'startup' }, 'Application started');

// Create child loggers with context
const authLogger = logger.child({ module: 'auth' });
authLogger.debug({ userId: '123' }, 'User authenticated');

// Bind to a request ID for correlation
const requestLogger = logger.withRequestId('req-abc123');
requestLogger.info('Processing request');

Dashboard API

The dashboard UI is served at the configured path. It also exposes a REST API:

EndpointDescription
GET /api/requestsList requests
GET /api/requests/:idGet request details
GET /api/exceptionsList exceptions
GET /api/exceptions/:idGet exception details
GET /api/logsList logs
GET /api/statsGet storage statistics

Query Parameters

All list endpoints support:

  • limit - Number of entries (default: 50, max: 100)
  • offset - Pagination offset (default: 0)
  • search - Full-text search
  • before - Entries before date (ISO string)
  • after - Entries after date (ISO string)
  • tags - Comma-separated tags filter

Example:

GET /__telescope/api/requests?limit=20&search=POST&after=2024-01-01

WebSocket

Connect to /__telescope/ws for real-time updates:

const ws = new WebSocket('ws://localhost:3000/__telescope/ws');

ws.onmessage = (event) => {
  const { type, payload, timestamp } = JSON.parse(event.data);

  switch (type) {
    case 'request':
      console.log('New request:', payload);
      break;
    case 'exception':
      console.log('New exception:', payload);
      break;
    case 'log':
      console.log('New log:', payload);
      break;
    case 'connected':
      console.log('Connected, clients:', payload.clientCount);
      break;
  }
};

Types

RequestEntry

interface RequestEntry {
  id: string;
  method: string;
  path: string;
  url: string;
  headers: Record<string, string>;
  body?: unknown;
  query?: Record<string, string>;
  status: number;
  responseHeaders: Record<string, string>;
  responseBody?: unknown;
  duration: number;
  timestamp: Date;
  ip?: string;
  userId?: string;
  tags?: string[];
}

ExceptionEntry

interface ExceptionEntry {
  id: string;
  name: string;
  message: string;
  stack: StackFrame[];
  source?: SourceContext;
  requestId?: string;
  timestamp: Date;
  handled: boolean;
  tags?: string[];
}

LogEntry

interface LogEntry {
  id: string;
  level: 'debug' | 'info' | 'warn' | 'error';
  message: string;
  context?: Record<string, unknown>;
  requestId?: string;
  timestamp: Date;
}

Integration with gkm dev

When using gkm dev, Telescope is automatically integrated:

gkm dev --port 3000

# Output:
# API:        http://localhost:3000
# Telescope:  http://localhost:3000/__telescope

Configure in gkm.config.ts:

export default {
  routes: './src/endpoints/**/*.ts',
  envParser: './src/config/env',
  logger: './src/logger',

  dev: {
    telescope: {
      enabled: true,
      path: '/__telescope',
    },
  },
};

Best Practices

  1. Disable in Production: Use environment variables to disable Telescope in production

    const telescope = new Telescope({
      storage: new InMemoryStorage(),
      enabled: process.env.NODE_ENV === 'development',
    });
    
  2. Ignore Health Checks: Exclude noisy endpoints

    ignorePatterns: ['/health', '/ready', '/metrics']
    
  3. Limit Body Size: Prevent memory issues with large payloads

    maxBodySize: 32 * 1024 // 32KB
    
  4. Auto-Prune: Enable automatic cleanup for long-running dev sessions

    pruneAfterHours: 4
    
  5. Use Database Storage in Staging: For debugging issues in staging environments

    const storage = process.env.NODE_ENV === 'production'
      ? null // Disabled
      : process.env.NODE_ENV === 'staging'
        ? new KyselyStorage(db)
        : new InMemoryStorage();
    

License

MIT

版本与发布记录

@geekmidas/telescope 共发布 205 个版本,首次发布于 2025/12/30;过去 12 个月发布了 205 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.6.1latest2026/11/16今天
10.0.0-alpha.185alpha2026/11/16今天
10.0.0-alpha.1842026/11/16今天
10.0.0-alpha.1832026/11/16今天
10.0.0-alpha.1822026/11/132 天前
10.0.0-alpha.1812026/11/133 天前

关于 @geekmidas/telescope 的常见问题

@geekmidas/telescope 是什么?

Laravel Telescope-style debugging and monitoring for web applications

如何安装 @geekmidas/telescope?

在项目目录运行 npm install @geekmidas/telescope,或使用 pnpm add / yarn add / bun add。

@geekmidas/telescope 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geekmidas/telescope 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@geekmidas/telescope 可以商用吗?

@geekmidas/telescope 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@geekmidas/telescope 的下载量有多少?

根据 npm 官方下载统计,@geekmidas/telescope 在 2026/10/16 – 2026/11/14 这 30 天内被下载 13,723 次,日均约 457 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geekmidas/telescope 还在维护吗?

最新版本 9.6.1 发布于 2026/11/16(今天);至今共发布 205 个版本,其中过去 12 个月发布了 205 个;首次发布于 2025/12/30。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。