🔭 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

$3

Simply include the Telescope script with your project ID:

``html





`

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:
`html

`

$3

`bash
npm install @ultron.studio/telescope
`

`javascript
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

$3

- 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.)

$3

- 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

$3

- 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

$3

- 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

$3

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

$3

- 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

$3

- 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

$3

- 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

$3

`bash
npm install @ultron.studio/telescope
`

$3

`html

`

$3

`html

`

Quick Start

$3

`javascript
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');
`

$3

`javascript
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

$3

#### 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

$3

#### captureException(error: Error, context?: Partial): Promise

Capture a JavaScript error with full stack trace.

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

#### captureMessage(message: string, level?: LogLevel, context?: Partial): Promise

Capture a custom message.

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

$3

#### addBreadcrumb(breadcrumb: Breadcrumb): void

Add a breadcrumb to track user actions.

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

$3

#### setUser(user: User): void

Set user information for context.

`javascript
setUser({
id: '12345',
username: 'john_doe',
email: 'john@example.com'
});
`

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

Set a tag for filtering and grouping.

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

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

Set custom context data.

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

🚀 Enhanced Features API

$3

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

`javascript
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

`javascript
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:

`javascript
// 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)
`

$3

#### getPerformanceMetrics(): PerformanceMetrics

Get current performance metrics including Web Vitals.

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

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

Measure the execution time of a function.

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

#### measurePerformanceAsync(name: string, fn: () => Promise): Promise

Measure the execution time of an async function.

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

#### markPerformance(name: string): void

Mark a performance milestone.

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

$3

#### startSessionReplay(): void

Start recording user interactions.

`javascript
startSessionReplay();
`

#### stopSessionReplay(): void

Stop recording user interactions.

`javascript
stopSessionReplay();
`

#### getSessionEvents(): SessionEvent[]

Get recorded session events.

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

$3

#### isOffline(): boolean

Check if the application is currently offline.

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

#### getOfflineQueueSize(): number

Get the number of events in the offline queue.

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

#### processOfflineQueue(): Promise

Manually process the offline queue.

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

$3

#### Enhanced Stack Traces

Telescope automatically captures enhanced stack traces with:
- Source code context
- Function arguments (sanitized)
- Module information
- Source map support

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

$3

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

#### Vanilla JavaScript

`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

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

#### Angular Integration

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

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

🎯 Why Choose Telescope?

$3

- 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

$3

- 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

$3

- 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:

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

Development

$3

`bash


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
`

$3

`bash


Run all tests

npm test

Run tests with coverage

npm run test -- --coverage

Run specific test file

npm test -- telescope.test.ts
`

Demo

$3

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

$3

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

$3

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

$3

- [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

$3

- [ ] 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

$3

- [ ] 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