straydog-js

Drop-in API monitoring and observability for Node.js applications

straydog-js is a lightweight, zero-config monitoring solution that provides real-time observability for your Node.js APIs. Track requests, monitor performance, analyze errors, and visualize your API usage through an integrated dashboard—all with a single line of code.

✨ Features

🔍 Automatic Request Monitoring

• Track all incoming HTTP requests with detailed metadata
• Monitor response times, status codes, and error rates
• Capture request/response data including headers, query parameters, and payloads

📊 Built-in Analytics Dashboard

• Real-time dashboard accessible at /straydog
• Visual charts and metrics for API performance
• Request logs with filtering and search capabilities
• Error tracking and debugging tools

📈 Performance Metrics

• Response time analytics (average, min, max)
• Success/failure rate monitoring
• Traffic analysis by endpoint
• Identify slowest and most-used endpoints

🚀 Zero Configuration

• Drop-in integration with single line setup
• Automatic route discovery for Express applications
• Local SQLite database for request storage
• No external dependencies or cloud services required

🛡️ Smart Filtering

• Exclude static files and unwanted routes
• Configurable request filtering options
• Built-in exclusions for development tools and assets

🚀 Quick Start

Installation

npm install straydog-js
# or
yarn add straydog-js

Basic Usage

import express from 'express';
import { ExpressAdapter } from 'straydog-js';

const app = express();

// Initialize straydog monitoring
const straydog = new ExpressAdapter(app);
straydog.observe(); // Start request monitoring

// Define your routes as usual
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.post('/api/users', (req, res) => {
  res.status(201).json({ message: 'User created' });
});

straydog.catch();   // Enable error tracking

app.listen(3000, () => {
  console.log('Server running on port 3000');
  console.log('📊 Straydog dashboard: http://localhost:3000/straydog');
});

adapter.catch()

The catch function must be called after you defined your routes.

Advanced Configuration

import { ExpressAdapter } from 'straydog-js';

const app = express();

// Configure with custom options
const straydog = new ExpressAdapter(app, {
  exclude: ['/health', '/metrics', '/straydog/api', '/static']
});

straydog.observe();
straydog.catch();

📊 Dashboard & Analytics

Once integrated, straydog-js provides a comprehensive dashboard accessible at /straydog:

Dashboard Features

• Request Overview: Real-time request count, success rates, and average response times
• Endpoint Analytics: Traffic analysis for each API endpoint
• Error Monitoring: Failed requests with detailed error information
• Performance Metrics: Response time distributions and latency analysis
• Request History: Searchable log of all API requests

API Endpoints

The dashboard is powered by internal API endpoints:

GET /straydog/api?method=getRequests&days=7   # Get request logs
GET /straydog/api?method=getStats&days=7      # Get analytics
GET /straydog/api?method=getEndpoints         # Get route list
GET /straydog/api?method=getErrorRequests     # Get failed requests

🔧 API Reference

ExpressAdapter

The main class for Express.js integration.

Constructor

new ExpressAdapter(app: Application, options?: Options)

Parameters:

• app - Your Express application instance
• options - Configuration options (optional)

Options

interface Options {
  exclude: string[];  // Routes to exclude from monitoring
}

Default exclusions:

• /straydog/api - Dashboard API endpoints

Methods

observe()

Starts monitoring incoming requests. Call this method to begin tracking API usage.

straydog.observe();

catch()

Enables error tracking for uncaught exceptions and failed requests.

straydog.catch();

📋 Analytics & Metrics

straydog-js automatically calculates comprehensive metrics:

Request Statistics

• Total Requests: Count of all API calls
• Success Rate: Percentage of successful requests (status < 400)
• Average Latency: Mean response time across all requests
• Error Count: Number of failed requests

Endpoint Analysis

• Highest Traffic: Most frequently accessed endpoints
• Slowest Endpoint: Endpoints with highest average response time
• Fastest Endpoint: Most performant endpoints
• Most Failed: Endpoints with highest error rates

Performance Metrics

• Latency Distribution: Min, max, and average response times
• System Metrics: Memory usage, CPU usage, and uptime
• Time-based Analysis: Metrics over configurable time periods (default: 7 days)

🗄️ Data Storage

straydog-js uses a local SQLite database to store request data:

• Location: src/config/data/db.sqlite3
• Tables: request and response with automatic schema creation
• Retention: Configurable via API queries (default: 7 days)

Database Schema

requests table:

CREATE TABLE request (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  method TEXT,
  path TEXT, 
  query TEXT,
  body TEXT,
  headers TEXT,
  start_time DATETIME
);

responses table:

CREATE TABLE response (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  request_id INTEGER,
  body TEXT,
  end_time DATETIME,
  status_code INTEGER,
  error TEXT,
  latency INTEGER,
  error_stack TEXT
);

🛠️ Development

Setup

git clone https://github.com/sheron184/straydog-js.git
cd straydog-js
npm install

Build

npm run build        # Compile TypeScript and copy UI assets
npm run dev          # Watch mode for development
npm run clean        # Clean dist directory

Testing

npm test             # Run test suite

🗺️ Roadmap

• [x] Express.js Support - Full integration with Express applications
• [x] Request/Response Tracking - Complete HTTP lifecycle monitoring
• [x] Analytics Dashboard - Visual metrics and request analysis
• [x] Error Tracking - Automatic error capture and reporting
• [x] SQLite Storage - Local database for request persistence

Upcoming Features

• [ ] Framework Expansion: NestJS and Fastify support
• [ ] Advanced Filtering: Custom request filtering and sampling
• [ ] Export Capabilities: CSV/JSON export of analytics data
• [ ] Alerting System: Configurable alerts for errors and performance
• [ ] Custom Dashboards: User-defined metrics and visualizations
• [ ] API Rate Limiting: Built-in rate limiting with monitoring

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Reporting Issues

• Use GitHub Issues for bug reports and feature requests
• Include detailed reproduction steps for bugs
• Specify your Node.js and framework versions

📄 License

MIT © Sheron Jude

🔗 Links

• GitHub Repository
• npm Package
• Issues & Bug Reports
• Documentation

👨‍💻 Author

Sheron Jude

• GitHub: @sheron184
• Email: Contact via GitHub

⭐ Show Your Support

If straydog-js helps you monitor your APIs effectively, please consider giving it a star on GitHub!

# Try it out in your next project
npm install straydog-js

Happy monitoring! 🐕‍🦺