🔭 Telescope

A comprehensive, enterprise-grade error monitoring and performance tracking system specifically designed for Telegram Mini Apps. Telescope helps you capture, track, and analyze errors in your JavaScript/TypeScript applications with advanced features including performance monitoring, session replay, offline support, and enhanced debugging capabilities.

🚀 Quick Start

Method 1: Script Tag (Easiest)

Simply include the Telescope script with your project ID:

<!-- Basic usage with project ID in URL -->
<script src="https://cdn.jsdelivr.net/npm/@ultron.studio/telescope@latest/dist/telescope.standalone.min.js?project=your-project-id"></script>

<!-- With additional configuration -->
<script src="https://cdn.jsdelivr.net/npm/@ultron.studio/telescope@latest/dist/telescope.standalone.min.js?project=your-project-id" 
        data-environment="production" 
        data-debug="true"></script>

That's it! Telescope will automatically:

• Initialize with your project ID
• Start monitoring for errors
• Track performance metrics
• Capture unhandled exceptions
• Send data to your Telescope backend

Script Tag Configuration Options

You can configure Telescope using data attributes on the script tag:

| Attribute | Description | Example | |-----------|-------------|---------| | data-project-id | Your Telescope project ID | data-project-id="your-project-id" | | data-environment | Environment (production, development, staging) | data-environment="production" | | data-debug | Enable debug mode (true/false) | data-debug="true" | | data-endpoint | Custom Telescope backend endpoint | data-endpoint="https://your-backend.com" |

Example with all options:

<script src="https://cdn.jsdelivr.net/npm/@ultron.studio/telescope@latest/dist/telescope.standalone.min.js?project=your-project-id"
        data-environment="production"
        data-debug="false"
        data-endpoint="https://api.your-telescope.com"></script>

Method 2: NPM Package

npm install @ultron.studio/telescope

import { init, captureException } from '@ultron.studio/telescope';

const telescope = init({
  dsn: 'https://your-telescope-endpoint.com/your-project-id',
  environment: 'production',
  performance: { enabled: true },
  sessionReplay: { enabled: true },
  offline: { enabled: true }
});

// Capture errors with enhanced context
captureException(new Error('Something went wrong'));

✨ Features

🚨 Advanced Error Capture

• Enhanced Stack Traces: Source map support, function arguments, and source code context
• Sensitive Data Sanitization: Automatic redaction of passwords, tokens, and secrets
• Error Grouping: Intelligent error grouping and deduplication
• Custom Error Types: Support for all JavaScript error types (TypeError, ReferenceError, etc.)

📈 Performance Monitoring

• Web Vitals: LCP, FID, CLS, FCP tracking with real-time updates
• Resource Timing: Network requests and loading performance monitoring
• Memory Usage: JavaScript heap monitoring (when available)
• Custom Metrics: Measure functions and async operations with detailed timing
• Performance Milestones: Mark and measure custom performance points

🎬 Session Replay

• User Interaction Tracking: Clicks, inputs, navigation, scrolling, and resizing
• Privacy Controls: Text masking, input sanitization, URL blocking, and selector filtering
• Event Recording: Configurable duration and event limits
• Real-time Status: Live recording indicators and controls

📱 Offline Support

• Error Queuing: Store errors when offline with automatic retry logic
• Automatic Sync: Process queue when connection is restored
• Retry Logic: Exponential backoff with configurable limits
• Storage Management: Local storage with size limits and cleanup

🍞 Enhanced Breadcrumbs

• Comprehensive Tracking: User actions, navigation, API calls, and custom events
• Smart Categorization: Automatic categorization of different event types

🎯 Advanced Sampling

• Client-Side Sampling: Sentry-like sampling strategies to reduce network traffic
• Level-Based Sampling: Different rates for fatal, error, warning, info, and debug levels
• User-Based Sampling: Boost sampling for new users and track user error patterns
• Time-Based Sampling: Adjust sampling rates during business hours
• Rate Limiting: Prevent overwhelming your backend with too many events
• Disabled by Default: Sampling is off by default for maximum error capture

🌐 Advanced Context Collection

• Browser Information: Detailed device, browser, and network data
• Telegram Integration: Automatic Telegram Mini App context detection
• User Journey: Navigation and interaction pattern tracking
• Custom Context: Flexible context addition and management

🔧 Developer Experience

• TypeScript Support: Full type safety and IntelliSense
• Multiple Formats: NPM package, CDN bundle, or script tag integration
• Flexible Configuration: Extensive configuration options for all environments
• Debug Tools: Comprehensive debugging and testing utilities

Installation

NPM Package

npm install @ultron.studio/telescope

CDN Bundle

<script src="https://unpkg.com/@ultron.studio/telescope@latest/dist/telescope.umd.min.js"></script>

Script Tag

<script src="https://unpkg.com/@ultron.studio/telescope@latest/dist/telescope.umd.min.js"></script>

Quick Start

Basic Setup

import { init, captureException, captureMessage } from '@ultron.studio/telescope';

// Initialize Telescope
const telescope = init({
  dsn: 'https://your-telescope-endpoint.com/your-project-id',
  environment: 'production',
  debug: true
});

// Capture an error
try {
  // Your code here
  throw new Error('Something went wrong!');
} catch (error) {
  captureException(error);
}

// Capture a custom message
captureMessage('User performed important action', 'info');

Advanced Configuration

import { init } from '@ultron.studio/telescope';

const telescope = init({
  dsn: 'https://ingest.telescope.dev/project-id',
  environment: 'production',
  release: '1.0.0',
  debug: false,
  maxBreadcrumbs: 100,
  sampleRate: 1.0,
  
  // Enhanced stack traces
  stackTrace: {
    sourceMaps: true,
    offline: false,
    maxDepth: 50
  },
  
  // Performance monitoring
  performance: {
    enabled: true,
    webVitals: true,
    resourceTiming: true,
    memoryUsage: true
  },
  
  // Session replay
  sessionReplay: {
    enabled: false,
    maxDuration: 300000, // 5 minutes
    maxEvents: 1000,
    privacy: {
      maskText: true,
      maskInputs: true,
      blockUrls: [],
      blockSelectors: []
    }
  },
  
  // Offline support
  offline: {
    enabled: true,
    maxQueueSize: 100,
    maxRetries: 3,
    retryDelay: 1000
  },
  
  // Advanced sampling configuration (disabled by default)
  sampling: {
    enabled: false,  // Set to true to enable sampling
    baseRate: 1.0,  // Base sampling rate (0.0 to 1.0)
    levelRates: {
      fatal: 1.0,    // Always sample fatal errors
      error: 1.0,    // Always sample errors
      warning: 0.5,  // 50% of warnings
      info: 0.1,     // 10% of info messages
      debug: 0.01    // 1% of debug messages
    },
    userSampling: {
      enabled: false,
      newUserBoost: 1.5,      // Boost sampling for new users
      newUserThreshold: 10    // First 10 errors per user
    },
    timeSampling: {
      enabled: false,
      businessHoursMultiplier: 1.2, // Boost during business hours
      businessHoursStart: 9,        // 9 AM
      businessHoursEnd: 17          // 5 PM
    },
    rateLimiting: {
      enabled: false,
      maxEventsPerMinute: 100       // Rate limit per minute
    }
  },
  
  beforeSend: (event) => {
    // Filter or modify events before sending
    if (event.exception?.values?.[0]?.value?.includes('ignore')) {
      return null; // Don't send this event
    }
    return event;
  },
  beforeBreadcrumb: (breadcrumb) => {
    // Filter or modify breadcrumbs
    return breadcrumb;
  }
});

API Reference

Initialization

init(config: TelescopeConfig): Telescope

Initialize Telescope with the given configuration.

Parameters:

• config.dsn (string): Your Telescope DSN endpoint
• config.environment (string, optional): Environment name (default: 'production')
• config.release (string, optional): Release version
• config.debug (boolean, optional): Enable debug logging (default: false)
• config.maxBreadcrumbs (number, optional): Maximum breadcrumbs to store (default: 50)
• config.sampleRate (number, optional): Legacy sampling rate 0-1 (default: 1.0)
• config.sampling (object, optional): Advanced sampling configuration (disabled by default)
  • config.sampling.enabled (boolean): Enable advanced sampling (default: false)
  • config.sampling.baseRate (number): Base sampling rate 0-1 (default: 1.0)
  • config.sampling.levelRates (object): Per-level sampling rates
  • config.sampling.userSampling (object): User-based sampling settings
  • config.sampling.timeSampling (object): Time-based sampling settings
  • config.sampling.rateLimiting (object): Rate limiting settings
• config.beforeSend (function, optional): Event filter function
• config.beforeBreadcrumb (function, optional): Breadcrumb filter function

Error Capture

captureException(error: Error, context?: Partial<ErrorEvent>): Promise<void>

Capture a JavaScript error with full stack trace.

try {
  // Your code
} catch (error) {
  captureException(error, {
    tags: { component: 'user-auth' },
    extra: { userId: '12345' }
  });
}

captureMessage(message: string, level?: LogLevel, context?: Partial<ErrorEvent>): Promise<void>

Capture a custom message.

captureMessage('User logged in successfully', 'info');
captureMessage('API request failed', 'warning', {
  tags: { endpoint: '/api/users' }
});

Breadcrumbs

addBreadcrumb(breadcrumb: Breadcrumb): void

Add a breadcrumb to track user actions.

addBreadcrumb({
  type: 'user',
  category: 'auth',
  message: 'User clicked login button',
  data: { buttonId: 'login-btn' }
});

User Management

setUser(user: User): void

Set user information for context.

setUser({
  id: '12345',
  username: 'john_doe',
  email: '[email protected]'
});

setTag(key: string, value: string): void

Set a tag for filtering and grouping.

setTag('environment', 'staging');
setTag('version', '1.2.3');

setContext(key: string, context: any): void

Set custom context data.

setContext('custom', {
  feature: 'new-checkout',
  experiment: 'variant-a'
});

🚀 Enhanced Features API

Advanced Sampling

Telescope provides sophisticated client-side sampling capabilities similar to Sentry, allowing you to control which errors are captured and sent to your backend.

Sampling Configuration

import { init } from '@ultron.studio/telescope';

const telescope = init({
  dsn: 'https://your-telescope-endpoint.com/your-project-id',
  sampling: {
    enabled: true,  // Enable advanced sampling
    baseRate: 0.5,  // 50% base sampling rate
    
    // Per-level sampling rates
    levelRates: {
      fatal: 1.0,    // Always sample fatal errors
      error: 1.0,    // Always sample errors
      warning: 0.5,  // 50% of warnings
      info: 0.1,     // 10% of info messages
      debug: 0.01    // 1% of debug messages
    },
    
    // User-based sampling
    userSampling: {
      enabled: true,
      newUserBoost: 1.5,      // 50% boost for new users
      newUserThreshold: 10    // First 10 errors per user
    },
    
    // Time-based sampling
    timeSampling: {
      enabled: true,
      businessHoursMultiplier: 1.2, // 20% boost during business hours
      businessHoursStart: 9,        // 9 AM
      businessHoursEnd: 17          // 5 PM
    },
    
    // Rate limiting
    rateLimiting: {
      enabled: true,
      maxEventsPerMinute: 50        // Max 50 events per minute
    }
  }
});

Sampling Statistics

import { getSamplingStats } from '@ultron.studio/telescope';

// Get current sampling statistics
const stats = getSamplingStats();
console.log('Sampled events:', stats.sampled);
console.log('Dropped events:', stats.dropped);
console.log('Effective rate:', stats.effectiveRate);

Sampling Decision Reasons

When sampling is enabled, you can see why events were sampled or dropped:

// Enable debug mode to see sampling decisions
const telescope = init({
  dsn: 'your-dsn',
  debug: true,
  sampling: {
    enabled: true,
    baseRate: 0.5
  }
});

// This will log sampling decisions to console:
// [Telescope] Error sampled out: rate_limit (rate: 0.0)
// [Telescope] Error sampled: random (rate: 0.5)

Performance Monitoring

getPerformanceMetrics(): PerformanceMetrics

Get current performance metrics including Web Vitals.

const metrics = getPerformanceMetrics();
console.log('LCP:', metrics.lcp);
console.log('FID:', metrics.fid);
console.log('CLS:', metrics.cls);

measurePerformance<T>(name: string, fn: () => T): T

Measure the execution time of a function.

const result = measurePerformance('data-processing', () => {
  // Your expensive operation
  return processLargeDataset(data);
});

measurePerformanceAsync<T>(name: string, fn: () => Promise<T>): Promise<T>

Measure the execution time of an async function.

const result = await measurePerformanceAsync('api-call', async () => {
  return await fetch('/api/data');
});

markPerformance(name: string): void

Mark a performance milestone.

markPerformance('user-interaction-start');
// ... some operation
const duration = measureBetween('user-interaction-start', 'user-interaction-end');

Session Replay

startSessionReplay(): void

Start recording user interactions.

startSessionReplay();

stopSessionReplay(): void

Stop recording user interactions.

stopSessionReplay();

getSessionEvents(): SessionEvent[]

Get recorded session events.

const events = getSessionEvents();
console.log('Recorded events:', events);

Offline Support

isOffline(): boolean

Check if the application is currently offline.

if (isOffline()) {
  console.log('App is offline, errors will be queued');
}

getOfflineQueueSize(): number

Get the number of events in the offline queue.

const queueSize = getOfflineQueueSize();
console.log(`${queueSize} events queued for sync`);

processOfflineQueue(): Promise<void>

Manually process the offline queue.

await processOfflineQueue();
console.log('Offline queue processed');

Enhanced Error Capture

Enhanced Stack Traces

Telescope automatically captures enhanced stack traces with:

• Source code context
• Function arguments (sanitized)
• Module information
• Source map support

// Errors automatically include enhanced context
try {
  throw new Error('Something went wrong');
} catch (error) {
  captureException(error); // Enhanced stack trace included
}

Framework Integration

Telescope works with any JavaScript framework or vanilla JavaScript. Here are some integration examples:

Vanilla JavaScript

// Global error handling
window.addEventListener('error', (event) => {
  captureException(event.error);
});

// Performance monitoring
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    measurePerformance(entry.name, entry.duration);
  }
});
observer.observe({ entryTypes: ['measure', 'navigation'] });

Vue.js Integration

// In your Vue app
app.config.errorHandler = (err, instance, info) => {
  captureException(err, {
    extra: { component: instance?.$options.name, info }
  });
};

Angular Integration

// In your Angular app
import { ErrorHandler } from '@angular/core';

export class TelescopeErrorHandler implements ErrorHandler {
  handleError(error: any): void {
    captureException(error);
  }
}

🎯 Why Choose Telescope?

Enterprise-Grade Features

• Comprehensive Error Monitoring: Advanced stack traces, source maps, and context collection
• Performance Tracking: Real-time Web Vitals and custom performance metrics
• Session Replay: Complete user interaction recording with privacy controls
• Offline Support: Reliable error queuing and automatic synchronization
• Framework Agnostic: Works with any JavaScript framework or vanilla JavaScript

Developer Experience

• TypeScript Support: Full type safety and excellent IntelliSense
• Flexible Configuration: Extensive configuration options for all environments
• Multiple Integration Methods: NPM package, CDN, or script tag
• Comprehensive Documentation: Detailed API reference and examples
• Live Demos: Interactive demos showcasing all features

Production Ready

• Sensitive Data Protection: Automatic sanitization of passwords and tokens
• Error Grouping: Intelligent error deduplication and grouping
• Performance Optimized: Minimal impact on application performance
• Browser Compatibility: Support for all modern browsers
• Telegram Mini App Optimized: Specialized for Telegram Mini App environments

Telegram Mini App Integration

Telescope automatically detects and captures Telegram Mini App context:

// Telescope automatically detects:
// - Telegram WebApp version
// - Platform information
// - User data from initData
// - Mini app specific context
// - Performance metrics
// - User interactions
// - Network conditions

Development

Setup

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the project
npm run build

# Run in development mode
npm run dev

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test -- --coverage

# Run specific test file
npm test -- telescope.test.ts

Demo

Basic Demo

Open demo/index.html in your browser to see the basic Telescope features:

• Error triggering buttons
• Console output showing captured errors
• Breadcrumb tracking
• User context management

Enhanced Demo

Open demo/enhanced-demo.html in your browser to see all advanced features:

• Real-time Performance Metrics: Live Web Vitals display (LCP, FID, CLS, FCP)
• Interactive Error Testing: Various error types with enhanced stack traces
• Session Replay Controls: Start/stop recording with event tracking
• Offline Simulation: Test offline queuing and automatic sync
• Breadcrumb Testing: User action and navigation tracking
• Advanced Features: Error filtering, context collection, and sampling
• Status Indicators: Connection status, recording status, and queue size
• Performance Monitoring: Custom measurements and Web Vitals tracking

Live Demo

You can also test the enhanced demo online at: http://localhost:8080/demo/enhanced-demo.html (when running locally)

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Roadmap

✅ Completed Features

• [x] Performance monitoring - Web Vitals, custom metrics, resource timing
• [x] User session replay - Interaction tracking with privacy controls
• [x] Advanced filtering and grouping - Client-side filtering and error grouping
• [x] Framework agnostic - Works with any JavaScript framework or vanilla JavaScript
• [x] Enhanced error capture - Source maps, context, and sensitive data sanitization
• [x] Offline support - Error queuing and automatic sync
• [x] Advanced breadcrumbs - Comprehensive user action tracking

🚧 In Progress

• [ ] Backend data ingestion service - Python-based API for processing errors
• [ ] Real-time error notifications - Live error alerts and monitoring
• [ ] Advanced analytics dashboard - Comprehensive error analytics and insights

📋 Planned Features

• [ ] Network request tracking - HTTP request monitoring and performance
• [ ] Vue.js integration - Hooks and components for Vue applications
• [ ] Angular integration - Services and components for Angular applications
• [ ] Mobile app support - React Native and Flutter SDKs
• [ ] Telegram bot integration - Error notifications via Telegram bot
• [ ] Advanced error grouping - ML-powered error clustering and deduplication
• [ ] Custom dashboards - Configurable monitoring dashboards
• [ ] Team collaboration - Multi-user error management and assignment