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.
- 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
- 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
- Response time analytics (average, min, max)
- Success/failure rate monitoring
- Traffic analysis by endpoint
- Identify slowest and most-used endpoints
- 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
- Exclude static files and unwanted routes
- Configurable request filtering options
- Built-in exclusions for development tools and assets
npm install straydog-js
# or
yarn add straydog-jsimport 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');
});The catch function must be called after you defined your routes.
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();Once integrated, straydog-js provides a comprehensive dashboard accessible at /straydog:
- 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
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
The main class for Express.js integration.
new ExpressAdapter(app: Application, options?: Options)Parameters:
app- Your Express application instanceoptions- Configuration options (optional)
interface Options {
exclude: string[]; // Routes to exclude from monitoring
}Default exclusions:
/straydog/api- Dashboard API endpoints
Starts monitoring incoming requests. Call this method to begin tracking API usage.
straydog.observe();Enables error tracking for uncaught exceptions and failed requests.
straydog.catch();straydog-js automatically calculates comprehensive metrics:
- 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
- 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
- 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)
straydog-js uses a local SQLite database to store request data:
- Location:
src/config/data/db.sqlite3 - Tables:
requestandresponsewith automatic schema creation - Retention: Configurable via API queries (default: 7 days)
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
);git clone https://github.com/sheron184/straydog-js.git
cd straydog-js
npm installnpm run build # Compile TypeScript and copy UI assets
npm run dev # Watch mode for development
npm run clean # Clean dist directorynpm test # Run test suite- Express.js Support - Full integration with Express applications
- Request/Response Tracking - Complete HTTP lifecycle monitoring
- Analytics Dashboard - Visual metrics and request analysis
- Error Tracking - Automatic error capture and reporting
- SQLite Storage - Local database for request persistence
- 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
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Use GitHub Issues for bug reports and feature requests
- Include detailed reproduction steps for bugs
- Specify your Node.js and framework versions
MIT © Sheron Jude
Sheron Jude
- GitHub: @sheron184
- Email: Contact via GitHub
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-jsHappy monitoring! 🐕🦺