JavaScript/TypeScript
LogBull JavaScript/TypeScript library provides multiple integration options for sending logs to your LogBull server.
GitHub Repository: logbull-js
Installation
npm install logbull
This single package includes everything you need: the standalone logger, Winston transport, and Pino transport.
Quick Start
The fastest way to start using LogBull is with the standalone logger:
import { LogBullLogger, LogLevel } from 'logbull';
const logger = new LogBullLogger({
host: 'http://LOGBULL_HOST',
projectId: 'LOGBULL_PROJECT_ID',
apiKey: 'YOUR_API_KEY', // optional
logLevel: LogLevel.INFO,
});
logger.info('User logged in successfully', {
user_id: '12345',
username: 'john_doe',
ip: '192.168.1.100',
});
// Ensure all logs are sent before exiting
logger.flush();
await new Promise((resolve) => setTimeout(resolve, 5000));
Usage Examples
1. Standalone Logger
import { LogBullLogger, LogLevel } from 'logbull';
// Initialize logger
const logger = new LogBullLogger({
host: 'http://LOGBULL_HOST',
projectId: 'LOGBULL_PROJECT_ID',
apiKey: 'YOUR_API_KEY',
logLevel: LogLevel.INFO,
});
// Basic logging
logger.info('User logged in successfully', {
user_id: '12345',
username: 'john_doe',
ip: '192.168.1.100',
});
logger.error('Database connection failed', {
database: 'users_db',
error_code: 500,
});
// Context management
const sessionLogger = logger.withContext({
session_id: 'sess_abc123',
user_id: 'user_456',
});
sessionLogger.info('Processing request', {
action: 'purchase',
});
// Ensure all logs are sent before exiting
logger.flush();
await new Promise((resolve) => setTimeout(resolve, 5000));
Context Management
// Attach persistent context to all subsequent logs
const sessionLogger = logger.withContext({
session_id: 'sess_abc123',
user_id: 'user_456',
request_id: 'req_789',
});
// All logs from sessionLogger include the context automatically
sessionLogger.info('User started checkout process', {
cart_items: 3,
total_amount: 149.99,
});
// Output includes: session_id, user_id, request_id + cart_items, total_amount
sessionLogger.error('Payment processing failed', {
payment_method: 'credit_card',
error_code: 'DECLINED',
});
// Context can be chained
const transactionLogger = sessionLogger.withContext({
transaction_id: 'txn_xyz789',
merchant_id: 'merchant_123',
});
transactionLogger.info('Transaction completed', {
amount: 149.99,
currency: 'USD',
});
// Includes all previous context + new transaction context
// Ensure all logs are sent before exiting
logger.flush();
await new Promise((resolve) => setTimeout(resolve, 5000));
2. Winston Integration
import { LogBullTransport } from 'logbull';
import winston from 'winston';
// Create Winston logger with LogBull transport
const logger = winston.createLogger({
level: 'info',
format: winston.format.json(),
transports: [
new winston.transports.Console(),
new LogBullTransport({
host: 'http://LOGBULL_HOST',
projectId: 'LOGBULL_PROJECT_ID',
apiKey: 'YOUR_API_KEY',
}),
],
});
// Use standard Winston logging
logger.info('User action', {
user_id: '12345',
action: 'login',
ip: '192.168.1.100',
});
logger.error('Payment failed', {
order_id: 'ord_123',
amount: 99.99,
currency: 'USD',
});
// Winston child logger (context)
const requestLogger = logger.child({
request_id: 'req_789',
session_id: 'sess_456',
});
requestLogger.info('Request started');
requestLogger.info('Request completed', { duration_ms: 250 });
// Ensure all logs are sent before exiting
logger.flush();
await new Promise((resolve) => setTimeout(resolve, 5000));
3. Pino Integration
import { createPinoTransport } from 'logbull';
import pino from 'pino';
// Create Pino logger with LogBull transport
const transport = createPinoTransport({
host: 'http://LOGBULL_HOST',
projectId: 'LOGBULL_PROJECT_ID',
apiKey: 'YOUR_API_KEY',
});
const logger = pino({ level: 'info' }, transport);
// Use standard Pino logging
logger.info(
{
user_id: '12345',
action: 'login',
ip: '192.168.1.100',
},
'User action',
);
logger.error(
{
order_id: 'ord_123',
amount: 99.99,
currency: 'USD',
},
'Payment failed',
);
// Pino child logger (context)
const requestLogger = logger.child({
request_id: 'req_789',
session_id: 'sess_456',
});
requestLogger.info('Request started');
requestLogger.info({ duration_ms: 250 }, 'Request completed');
// Ensure all logs are sent before exiting
logger.flush();
await new Promise((resolve) => setTimeout(resolve, 5000));
Configuration Options
LogBullLogger Parameters
projectId
(required): Your LogBull project ID (UUID format)host
(required): LogBull server URLapiKey
(optional): API key for authenticationlogLevel
(optional): Minimum log level to process (default:INFO
)
Available Log Levels
enum LogLevel {
DEBUG = 'DEBUG',
INFO = 'INFO',
WARNING = 'WARNING',
ERROR = 'ERROR',
CRITICAL = 'CRITICAL',
}
API Reference
LogBullLogger Methods
debug(message: string, fields?: Record<string, any>)
: Log debug messageinfo(message: string, fields?: Record<string, any>)
: Log info messagewarning(message: string, fields?: Record<string, any>)
: Log warning messageerror(message: string, fields?: Record<string, any>)
: Log error messagecritical(message: string, fields?: Record<string, any>)
: Log critical messagewithContext(context: Record<string, any>): LogBullLogger
: Create new logger with additional contextflush()
: Immediately send all queued logsshutdown(): Promise<void>
: Stop background processing and send remaining logs
LogBullTransport (Winston)
Methods
log(info: any, callback: () => void)
: Winston log method (called automatically)flush()
: Immediately send all queued logsclose()
: Close the transportshutdown(): Promise<void>
: Stop and send remaining logs
LogBullPinoTransport (Pino)
Methods
flush()
: Immediately send all queued logsshutdown(): Promise<void>
: Stop and send remaining logs
Functions
createPinoTransport(config: Config)
: Create a Pino transport stream
Features
- Multiple integration options: Standalone logger, Winston transport, and Pino transport
- Context support: Attach persistent context to logs (session_id, user_id, etc.)
- Type-safe: Full TypeScript support with comprehensive type definitions
- Framework integration: Easy integration with Express.js, Fastify, and other Node.js frameworks
Requirements
- Node.js: 16.0.0 or higher
- TypeScript: 5.0.0 or higher (for TypeScript projects)
For Node.js 18+, native fetch
is used. For older versions, the built-in https
module is used.
Last updated on