blue-watchdog v1.0.2
🛡️ Blue Watchdog
Robust API monitoring and circuit breaker for Node.js, with real-time alerts and analytics
🚀 Introduction
Blue Watchdog is a powerful monitoring tool designed to protect your Node.js applications from unreliable API dependencies. It tracks endpoints for error rates and latency, automatically triggers circuit breakers, and sends alerts to Slack when thresholds are breached. Ideal for microservices and distributed systems.
Key Features:
- 📊 Real-time Metrics: Track error rates & response times for critical endpoints
- ⚡ Circuit Breaking: Automatically block failing endpoints to prevent cascading failures
- 🚨 Slack Alerts: Get notified instantly when thresholds are exceeded
- 🔌 Universal Support: Works with Axios, fetch, and any HTTP client
- 🛠️ Custom Thresholds: Define per-endpoint error/latency limits
- 📈 Smart Analytics: Rolling 5-minute window for accurate health checks
📦 Installation
npm install blue-watchdog
🛠️ Configuration
Create a sentinel instance with your monitoring rules:
import { initAPISentinel } from 'api-sentinel';
const sentinel = initAPISentinel({
endpoints: [
{
url: '/api/payments', // String or RegExp
thresholds: {
errorRate: 10, // Max 10% errors (optional)
latency: 1000 // Max 1s response time (optional)
}
}
],
alert: {
slackWebhook: 'https://hooks.slack.com/services/...' // Optional
},
circuitBreaker: {
threshold: 50, // 50% errors to open circuit (default)
cooldown: 30000 // 30s cooldown (default)
}
});
💻 Usage
Axios (Automatic Monitoring)
import axios from 'axios';
// All Axios requests are automatically instrumented!
axios.get('/api/payments');
Fetch Wrapper
// Replace native fetch with monitored version
const response = await sentinel.wrappedFetch('/api/users', {
method: 'POST',
body: JSON.stringify({ user: 'new' })
});
Manual Request Handling
// Use the circuit breaker directly
const result = await sentinel.handleRequest('/api/orders', async () => {
return await makeOrderRequest();
});
🔧 How It Works
Metrics Collection:
- Tracks all HTTP requests (success/failure)
- Records response times and status codes
- Maintains 5-minute rolling window
Circuit Breaking:
- Opens circuit when error threshold exceeded
- Blocks requests during cooldown period
- Automatically retries after recovery
Alerting:
- Throttled Slack notifications
- Instant visibility into degraded endpoints
⚙️ Configuration Details
EndpointConfig
Property | Type | Description |
---|---|---|
url | string/RegExp | Endpoint to monitor (exact or regex) |
thresholds | object | Error/latency limits (optional) |
thresholds
Property | Type | Default | Description |
---|---|---|---|
errorRate | number | - | Maximum allowed error % (0-100) |
latency | number | - | Maximum avg response time (ms) |
circuitBreaker
Property | Type | Default | Description |
---|---|---|---|
threshold | number | 50 | Error % to trigger circuit open |
cooldown | number | 10000 | Cooldown duration in ms |
📈 Analytics
Blue Watchdog continuously analyzes:
- Error Rate:
(errors / total_requests) * 100
- Latency: Rolling average of response times
- Circuit State: Tracks open/closed/half-open status
Metrics are checked every 60 seconds against your thresholds.
🔌 Supported Libraries
Library | Support | Notes |
---|---|---|
Axios | ✅ Automatic | Uses interceptors |
fetch | ✅ Wrapper | Use wrappedFetch method |
HTTP | 🔜 Coming Soon | |
Express | 🔜 Coming Soon | Middleware support |
🛡️ Requirements
- Node.js
>=16.0
- TypeScript
>=4.0
(recommended)
🤝 Contributing
Contributions welcome!
- Fork the repository
- Clone your fork:
git clone https://github.com/yourusername/api-sentinel.git
- Create a feature branch:
git checkout -b feature-enhancement
- Commit changes and push
- Open a pull request
📄 License
This project is licensed under the MIT License. See the LICENSE file for details.
🌟 Credits
This project was created by Gabriele Meucci.
Keep your APIs healthy and your systems resilient! 🛡️