oluso
v2.2.0
Published
AI-powered error monitoring library for Node.js applications with automatic error reporting, context tracking, and intelligent error grouping
Maintainers
Readme
Oluso
AI-powered error monitoring library for Node.js applications with automatic error reporting, context tracking, and intelligent error grouping.
Installation
npm install olusoFeatures
- Framework Support: Seamless integration with Express and NestJS.
- Automatic Context: Captures headers, body, query, and params (sanitized).
- Breadcrumbs: Tracks events leading to an error for better debugging.
- User Context: Tie errors to specific users.
- Deduplication: Intelligent fingerprinting groups similar errors together.
- Offline Reliability: Queues reports when the API is unreachable.
- Global Capture: Handles uncaught exceptions, unhandled rejections, and worker errors.
- Rate Limiting: Protects your API from being flooded by repetitive errors.
Usage with Express
olusoExpress() returns two middlewares that must be mounted at different
points in your app -- Express dispatches request vs. error middleware based
on each function's parameter count, so one function can't do both jobs.
import express from 'express';
import { olusoExpress } from 'oluso';
const app = express();
app.use(express.json());
const oluso = olusoExpress({
apiKey: 'your-api-key',
environment: 'production',
sensitiveKeys: ['password', 'card_number'] // Optional custom sanitization
});
// requestHandler first, before your routes
app.use(oluso.requestHandler);
app.get('/api/test', (req, res) => {
throw new Error('Something went wrong!');
});
// errorHandler last, after all your routes -- Express only routes an
// error to handlers registered after the route that produced it.
app.use(oluso.errorHandler);
app.listen(3000);Note: Express 4 does not automatically forward a rejected promise from an
async route handler into error-handling middleware. For async routes,
either catch and call next(err) yourself, or use a wrapper like
express-async-errors/Express 5 -- otherwise a thrown/rejected error in an
async handler never reaches oluso.errorHandler at all.
Cron jobs, queue workers, and other non-request code
requestHandler/errorHandler only see errors that pass through Express's
request/response cycle. A node-cron/BullMQ job, a setInterval loop, or a
message-queue consumer is invisible to both of them -- and invisible to
uncaught-exception reporting too, if that code catches its own errors (even
just to log them) rather than letting them throw. The object olusoExpress()
returns also exposes captureException (and addBreadcrumb/setUserContext/
setCustomContext/flush) on the same instance, for exactly this case:
const oluso = olusoExpress({ apiKey: 'your-api-key' });
cron.schedule('0 21 * * *', async () => {
try {
await deleteStaleRecords();
} catch (err) {
oluso.captureException(err); // otherwise this failure is invisible
}
});Usage with NestJS
Use the OlusoExceptionFilter to capture errors globally across HTTP, WebSockets, and RPC.
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { OlusoExceptionFilter } from 'oluso';
@Module({
providers: [
{
provide: APP_FILTER,
useClass: OlusoExceptionFilter({
apiKey: 'your-api-key',
environment: 'production',
tags: ['nest-api']
})
}
]
})
export class AppModule {}Manual Reporting & Context
import { Oluso } from 'oluso';
const oluso = new Oluso({ apiKey: 'your-api-key' });
// Add breadcrumbs for debugging trails
oluso.addBreadcrumb({
message: 'User started checkout',
category: 'action',
data: { cartId: '123' }
});
// Set user context
oluso.setUserContext({
id: 'user_456',
email: '[email protected]'
});
try {
doWork();
} catch (error) {
oluso.captureException(error, { custom_meta: 'extra-info' });
}Advanced Configuration
const oluso = new Oluso({
apiKey: 'your-api-key',
environment: 'staging',
defaultSeverity: 'medium',
maxBreadcrumbs: 50,
maxErrorsPerMinute: 100,
enableOfflineQueue: true,
sensitiveKeys: ['ssn', 'api_key'],
shouldReport: (err, req) => {
// Don't report 404s
if (req?.res?.statusCode === 404) return false;
return true;
}
});Process monitors
The same Oluso instance exposes heartbeat(url, options), assertOutcome(options), and workflow(reference, runId?). They report missing, wrong, slow, stuck, failed, and unavailable processes even when no exception occurs. See the complete monitor guide.
Error Report Structure
Reports sent to the API include:
- Metadata: Title, message, stack trace, severity, tags.
- Context: Request details (URL, method, headers, etc.), Server details (hostname, node version, memory).
- History: Breadcrumbs leading up to the error.
- Identification: Fingerprint for deduplication and User ID.
License
MIT
