@stacksleuth/backend-agent

StackSleuth Backend Agent

🚀 What is StackSleuth Backend Agent?

Comprehensive backend performance monitoring agent for Node.js applications - HTTP request tracing, database query optimization, memory profiling, and real-time metrics collection with WebSocket integration.

✨ Key Features

• 🚀 HTTP Request Monitoring: Automatic request/response tracking
• 📊 Database Query Optimization: Real-time query performance analysis
• 💾 Memory Profiling: Advanced memory leak detection and optimization
• 🔄 Real-time Metrics: Live performance data with WebSocket integration
• 🎯 Custom Middleware: Easy integration with existing applications
• 📈 Performance Analytics: Comprehensive performance data collection
• 🔧 Framework Agnostic: Works with Express, Koa, Fastify, and more
• ⚡ Production Ready: Minimal overhead, battle-tested implementation

📦 Installation

# npm
npm install @stacksleuth/backend-agent

# yarn
yarn add @stacksleuth/backend-agent

# pnpm
pnpm add @stacksleuth/backend-agent

yarn add @stacksleuth/backend-agent

pnpm add @stacksleuth/backend-agent

🏁 Quick Start

import express from 'express';
import { BackendAgent } from '@stacksleuth/backend-agent';

const app = express();
const agent = new BackendAgent({
  enabled: true,
  sampleRate: 0.1
});

// Start monitoring
agent.startMonitoring();

// Middleware integration
app.use(agent.middleware());

app.get('/api/users', async (req, res) => {
  // Your route logic
  const users = await User.find();
  res.json(users);
});

app.listen(3000, () => {
  console.log('Server running with StackSleuth monitoring');
});

📖 Comprehensive Examples

Express.js Integration

import express from 'express';
import { BackendAgent } from '@stacksleuth/backend-agent';

const app = express();
const agent = new BackendAgent({
  enabled: true,
  projectId: 'your-project-id',
  sampleRate: 0.1
});

// Start monitoring
agent.startMonitoring();

// Add middleware (must be first)
app.use(agent.middleware());

app.get('/api/users', async (req, res) => {
  const users = await getUsersFromDatabase();
  res.json(users);
});

app.listen(3000, () => {
  console.log('Server running with StackSleuth monitoring');
});

Custom Error Tracking

// Track custom errors
app.use((error, req, res, next) => {
  agent.recordError(error, {
    userId: req.user?.id,
    path: req.path,
    method: req.method
  });
  
  res.status(500).json({ error: 'Internal server error' });
});

🎯 Real-World Usage

Production Configuration

const agent = new BackendAgent({
  enabled: process.env.NODE_ENV === 'production',
  projectId: process.env.STACKSLEUTH_PROJECT_ID,
  apiKey: process.env.STACKSLEUTH_API_KEY,
  sampleRate: process.env.NODE_ENV === 'production' ? 0.01 : 0.1,
  bufferSize: 1000,
  flushInterval: 10000
});

Monitoring Best Practices

• Sampling Rate: Use lower sampling rates (1-5%) in production
• Buffer Management: Configure appropriate buffer sizes for your traffic
• Error Handling: Always include error context in your monitoring
• Security: Never log sensitive data like passwords or API keys
• Performance: Monitor the monitoring - track agent overhead

🛠️ Troubleshooting

Common Issues

Agent Not Starting

// Enable debug mode
const agent = new BackendAgent({
  enabled: true,
  debug: true
});

High Memory Usage

// Optimize memory usage
const agent = new BackendAgent({
  bufferSize: 500,
  flushInterval: 5000,
  sampleRate: 0.01
});

Missing Metrics

• Check that the agent is enabled
• Verify your API key and project ID
• Ensure sampling rate allows data through
• Check network connectivity to StackSleuth API

Debug Mode

DEBUG=stacksleuth:* node your-app.js

📚 Resources

• Official Documentation
• API Reference
• Examples Repository

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see the LICENSE file for details.

Website • Documentation • NPM Registry • GitHub

Made with ⚡ by StackSleuth