@stacksleuth/core
Version:
Advanced TypeScript-based core profiling engine for StackSleuth - Real-time performance monitoring with flexible profiler, span tracing, and unified agent architecture. Features comprehensive metrics collection, memory optimization, and production-ready i
497 lines (378 loc) • 13.6 kB
Markdown
# @stacksleuth/core
<div align="center">
**Advanced TypeScript-based Core Profiling Engine for StackSleuth**
[](https://badge.fury.io/js/%40stacksleuth%2Fcore)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
</div>
## 🚀 What is StackSleuth Core?
StackSleuth Core is the foundational profiling engine that powers the entire StackSleuth performance monitoring ecosystem. It provides real-time performance monitoring with flexible profiler, span tracing, and unified agent architecture. Features comprehensive metrics collection, memory optimization, and production-ready instrumentation.
## ✨ Key Features
- **🔬 Advanced Profiling**: Real-time code profiling with microsecond precision
- **📊 Span Tracing**: Distributed tracing across your entire application stack
- **🎯 Adaptive Sampling**: Intelligent sampling to minimize performance overhead
- **💾 Memory Optimization**: Built-in memory leak detection and optimization
- **🔧 Extensible Architecture**: Foundation for specialized monitoring agents
- **📈 Performance Metrics**: Comprehensive performance data collection
- **🌐 Production Ready**: Battle-tested instrumentation for production environments
- **🔄 Real-time Monitoring**: Live performance insights with minimal latency
## 📦 Installation
```bash
npm install @stacksleuth/core
```
```bash
yarn add @stacksleuth/core
```
```bash
pnpm add @stacksleuth/core
```
## 🏁 Quick Start
### Basic Profiling
```typescript
import { ProfilerCore } from '@stacksleuth/core';
// Initialize the profiler
const profiler = new ProfilerCore({
enabled: true,
sampleRate: 0.1, // 10% sampling
bufferSize: 1000
});
// Start profiling
profiler.startProfiling();
// Your application code
async function criticalFunction() {
const span = profiler.startSpan('critical-operation');
try {
// Simulate work
await performDatabaseQuery();
await processData();
span.setStatus('success');
} catch (error) {
span.setStatus('error', error.message);
throw error;
} finally {
span.end();
}
}
// Get performance metrics
const metrics = profiler.getMetrics();
console.log('Performance Summary:', metrics);
```
### Advanced Configuration
```typescript
import { ProfilerCore, BaseAgent } from '@stacksleuth/core';
// Custom configuration
const profiler = new ProfilerCore({
enabled: true,
endpoint: 'https://your-monitoring-endpoint.com',
apiKey: 'your-api-key',
sampleRate: 0.05, // 5% sampling for production
bufferSize: 2000,
flushInterval: 10000, // 10 seconds
debug: false,
adaptiveSampling: true,
memoryOptimization: true
});
// Create custom agent
class CustomAgent extends BaseAgent {
public startMonitoring(): void {
console.log('Starting custom monitoring...');
// Your custom monitoring logic
}
public stopMonitoring(): void {
console.log('Stopping custom monitoring...');
// Your cleanup logic
}
}
const agent = new CustomAgent({
enabled: true,
sampleRate: 0.1
});
```
### Memory Profiling
```typescript
import { MemoryProfiler } from '@stacksleuth/core';
const memoryProfiler = new MemoryProfiler();
// Start memory monitoring
memoryProfiler.startMonitoring();
// Take memory snapshot
const snapshot = memoryProfiler.takeSnapshot();
console.log('Memory usage:', snapshot);
// Detect memory leaks
const leaks = memoryProfiler.detectLeaks();
if (leaks.length > 0) {
console.warn('Memory leaks detected:', leaks);
}
```
## 🏗️ Architecture
StackSleuth Core follows a modular architecture:
```
┌─────────────────┐
│ Your App │
└─────────────────┘
│
┌─────────────────┐
│ StackSleuth │
│ Agents │
└─────────────────┘
│
┌─────────────────┐
│ StackSleuth │
│ Core │
└─────────────────┘
│
┌─────────────────┐
│ Data Layer │
└─────────────────┘
```
### Core Components
- **ProfilerCore**: Main profiling engine
- **BaseAgent**: Foundation for all monitoring agents
- **SpanTracer**: Distributed tracing implementation
- **MetricsCollector**: Performance data aggregation
- **AdaptiveSampler**: Intelligent sampling strategies
- **MemoryProfiler**: Memory usage optimization
## 📊 API Reference
### ProfilerCore
```typescript
class ProfilerCore {
constructor(config: ProfilerConfig)
// Core methods
startProfiling(): void
stopProfiling(): void
startSpan(name: string, metadata?: any): Span
recordMetric(name: string, value: number, metadata?: any): void
// Data access
getMetrics(): PerformanceMetrics
getSpans(): Span[]
exportData(): ExportData
// Configuration
updateConfig(config: Partial<ProfilerConfig>): void
getConfig(): ProfilerConfig
}
```
### BaseAgent
```typescript
abstract class BaseAgent {
constructor(config: AgentConfig)
// Abstract methods (implement in subclasses)
abstract startMonitoring?(): void
abstract stopMonitoring?(): void
// Built-in methods
recordMetric(name: string, value: number, metadata?: any): void
getConfig(): AgentConfig
updateConfig(config: Partial<AgentConfig>): void
}
```
## 🎯 Why Choose StackSleuth Core?
### 🚀 **Performance First**
- Ultra-low overhead (< 1% performance impact)
- Adaptive sampling reduces monitoring costs
- Production-optimized memory management
### 🔧 **Developer Experience**
- TypeScript-first with excellent IntelliSense
- Intuitive API design
- Comprehensive documentation and examples
### 🌐 **Enterprise Ready**
- Proven in production environments
- Scalable architecture for large applications
- Industry-standard security practices
### 🔄 **Ecosystem Integration**
- Foundation for 15+ specialized agents
- Seamless integration with popular frameworks
- Extensible plugin architecture
## 🚀 Specialized Agents
StackSleuth Core powers a complete ecosystem of monitoring agents:
- **Frontend**: `@stacksleuth/frontend-agent`, `@stacksleuth/vue-agent`, `@stacksleuth/svelte-agent`
- **Backend**: `@stacksleuth/backend-agent`, `@stacksleuth/fastapi-agent`, `@stacksleuth/django-agent`, `@stacksleuth/laravel-agent`
- **Databases**: `@stacksleuth/db-agent`, `@stacksleuth/redis-agent`, `@stacksleuth/mongodb-agent`, `@stacksleuth/mysql-agent`
- **Browser**: `@stacksleuth/browser-agent`, `@stacksleuth/browser-extension`
- **Tools**: `@stacksleuth/cli`, `@stacksleuth/performance-optimizer`
## 📖 Examples
### Express.js Integration
```typescript
import express from 'express';
import { ProfilerCore } from '@stacksleuth/core';
const app = express();
const profiler = new ProfilerCore({ enabled: true });
// Middleware for automatic request profiling
app.use((req, res, next) => {
const span = profiler.startSpan(`${req.method} ${req.path}`);
res.on('finish', () => {
span.setMetadata({
statusCode: res.statusCode,
responseTime: Date.now() - span.startTime
});
span.end();
});
next();
});
app.get('/api/users', async (req, res) => {
const span = profiler.startSpan('fetch-users');
try {
const users = await fetchUsers();
res.json(users);
span.setStatus('success');
} catch (error) {
span.setStatus('error', error.message);
res.status(500).json({ error: 'Failed to fetch users' });
} finally {
span.end();
}
});
```
### Custom Metrics
```typescript
import { ProfilerCore } from '@stacksleuth/core';
const profiler = new ProfilerCore({ enabled: true });
// Business metrics
function trackBusinessMetric(metricName: string, value: number) {
profiler.recordMetric(metricName, value, {
timestamp: Date.now(),
source: 'business-logic',
environment: process.env.NODE_ENV
});
}
// Usage
trackBusinessMetric('orders.processed', 1);
trackBusinessMetric('revenue.generated', 99.99);
trackBusinessMetric('users.active', 1);
```
## ⚙️ Configuration Options
```typescript
interface ProfilerConfig {
enabled?: boolean; // Enable/disable profiling
endpoint?: string; // Remote endpoint for data export
apiKey?: string; // API key for authentication
sampleRate?: number; // Sampling rate (0.0 - 1.0)
bufferSize?: number; // Internal buffer size
flushInterval?: number; // Data flush interval (ms)
debug?: boolean; // Enable debug logging
adaptiveSampling?: boolean; // Enable adaptive sampling
memoryOptimization?: boolean; // Enable memory optimization
maxSpans?: number; // Maximum concurrent spans
exportFormat?: 'json' | 'protobuf'; // Data export format
}
```
## 🔧 Advanced Usage
### Custom Samplers
```typescript
import { ProfilerCore, CustomSampler } from '@stacksleuth/core';
class LoadBasedSampler extends CustomSampler {
shouldSample(): boolean {
const cpuUsage = process.cpuUsage();
const memoryUsage = process.memoryUsage();
// Reduce sampling under high load
if (cpuUsage.user > 80 || memoryUsage.heapUsed > 500 * 1024 * 1024) {
return Math.random() < 0.01; // 1% sampling
}
return Math.random() < 0.1; // 10% sampling
}
}
const profiler = new ProfilerCore({
enabled: true,
customSampler: new LoadBasedSampler()
});
```
### Data Export
```typescript
// Export to external monitoring system
const exportData = profiler.exportData();
// Send to your monitoring service
await fetch('https://your-monitoring-service.com/api/metrics', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
body: JSON.stringify(exportData)
});
```
## 🧪 Testing
StackSleuth Core includes comprehensive testing utilities:
```typescript
import { ProfilerCore, TestUtils } from '@stacksleuth/core';
describe('Application Performance', () => {
let profiler: ProfilerCore;
beforeEach(() => {
profiler = TestUtils.createTestProfiler();
});
it('should track function performance', async () => {
const span = profiler.startSpan('test-function');
await someAsyncFunction();
span.end();
const metrics = profiler.getMetrics();
expect(metrics.spans).toHaveLength(1);
expect(metrics.spans[0].duration).toBeGreaterThan(0);
});
});
```
## 📈 Performance Impact
StackSleuth Core is designed for production use with minimal overhead:
- **CPU Overhead**: < 1% in production environments
- **Memory Overhead**: < 10MB base memory usage
- **Network Overhead**: Configurable batching and compression
- **Disk I/O**: Minimal temporary storage with automatic cleanup
## 🔒 Security
- **No sensitive data collection** by default
- **Configurable data sanitization** for PII protection
- **Secure data transmission** with TLS encryption
- **API key authentication** for remote endpoints
- **Local-first architecture** - no mandatory external dependencies
## 🛠️ Troubleshooting
### Common Issues
**High Memory Usage**
```typescript
// Reduce buffer size and enable memory optimization
const profiler = new ProfilerCore({
bufferSize: 500,
memoryOptimization: true,
flushInterval: 5000
});
```
**Performance Impact**
```typescript
// Reduce sampling rate for production
const profiler = new ProfilerCore({
sampleRate: 0.01, // 1% sampling
adaptiveSampling: true
});
```
**Debug Logging**
```typescript
// Enable debug mode for troubleshooting
const profiler = new ProfilerCore({
debug: true,
enabled: true
});
```
## 📚 Resources
- **[Official Documentation](https://github.com/Jack-GitHub12/StackSleuth#readme)**
- **[API Reference](https://github.com/Jack-GitHub12/StackSleuth/blob/main/docs/api.md)**
- **[Examples Repository](https://github.com/Jack-GitHub12/StackSleuth/tree/main/examples)**
- **[Performance Best Practices](https://github.com/Jack-GitHub12/StackSleuth/blob/main/docs/best-practices.md)**
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](https://github.com/Jack-GitHub12/StackSleuth/blob/main/CONTRIBUTING.md) for details.
### Development Setup
```bash
git clone https://github.com/Jack-GitHub12/StackSleuth.git
cd StackSleuth
npm install
npm run build
npm test
```
### Reporting Issues
Found a bug or have a feature request? Please [open an issue](https://github.com/Jack-GitHub12/StackSleuth/issues) on GitHub.
## 📄 License
MIT License - see the [LICENSE](https://github.com/Jack-GitHub12/StackSleuth/blob/main/LICENSE) file for details.
## 🙏 Acknowledgments
Built with ❤️ by the StackSleuth team and our amazing [contributors](https://github.com/Jack-GitHub12/StackSleuth/graphs/contributors).
---
<div align="center">
**[Website](https://github.com/Jack-GitHub12/StackSleuth)** •
**[Documentation](https://github.com/Jack-GitHub12/StackSleuth#readme)** •
**[NPM Registry](https://www.npmjs.com/package/@stacksleuth/core)** •
**[GitHub](https://github.com/Jack-GitHub12/StackSleuth)**
Made with ⚡ by [StackSleuth](https://github.com/Jack-GitHub12/StackSleuth)
</div>