LogFlow Node.js SDK

Simple, schema-less logging SDK for the LogFlow platform.

Installation

``bash
npm install logflowclient
`

Quick Start

`typescript
import { Logger } from 'logflowclient';

// Initialize the logger with just your API key
const logger = new Logger({
api_key: 'lf_your_api_key_here'
});

// Send a log - that's it!
logger.log('user_activity', {
event: 'profile_view',
user_id: '123',
profile_id: '456'
});
`

No need to call close() - cleanup happens automatically!

Features

- Non-blocking: Logs are queued and sent asynchronously in the background
- Automatic batching: Logs are batched to reduce HTTP overhead
- Fail-safe: Won't crash your application if logging fails
- Retry logic: Automatic retries with exponential backoff
- Zero schema: Send any JSON-serializable data structure
- TypeScript support: Full TypeScript definitions included

Configuration

`typescript
const logger = new Logger({
api_key: 'lf_your_api_key_here', // Required: Your LogFlow API key (project auto-detected)
api_url: 'https://...', // Optional: API URL (default: production URL)
batch_size: 10, // Optional: Logs to batch before sending (default: 10)
flush_interval: 5.0, // Optional: Seconds to wait before flushing (default: 5.0)
max_retries: 3, // Optional: Max retry attempts (default: 3)
debug: false // Optional: Enable debug logging (default: false)
});
`

Usage Examples

$3

`typescript
import { Logger } from 'logflowclient';

const logger = new Logger({ api_key: 'lf_...' });

// Log user activity
logger.log('user_activity', {
event: 'button_click',
button_id: 'submit_form',
user_id: 'user_123',
timestamp: new Date().toISOString()
});

// That's it! Logs are sent automatically in the background
// Cleanup happens automatically when your program exits
`

$3

`typescript
import { Logger } from 'logflowclient';

const logger = new Logger({ api_key: 'lf_...' });

try {
// Your code
riskyOperation();
} catch (e: any) {
logger.log('errors', {
error: e.message,
type: e.constructor.name,
stack: e.stack,
context: 'user_signup'
}, 'error');
}

await logger.close();
`

$3

`typescript
import { Logger } from 'logflowclient';
import axios from 'axios';

const logger = new Logger({ api_key: 'lf_...' });

const start = Date.now();
const response = await axios.get('https://api.example.com/users');
const duration = Date.now() - start;

logger.log('api_calls', {
endpoint: '/users',
method: 'GET',
status: response.status,
duration_ms: duration,
response_size: response.data.length
});

await logger.close();
`

$3

`typescript
import { Logger } from 'logflowclient';

const logger = new Logger({ api_key: 'lf_...' });

// Track page views
logger.log('user_activity', {
event: 'page_view',
page: '/dashboard',
user_id: 'user_123',
session_id: 'sess_xyz',
referrer: 'https://google.com'
});

// Track feature usage
logger.log('user_activity', {
event: 'feature_used',
feature: 'export_data',
user_id: 'user_123',
format: 'csv'
});

await logger.close();
`

$3

`typescript
import { Logger } from 'logflowclient';

const logger = new Logger({ api_key: 'lf_...' });

// Info log (default)
logger.log('events', { message: 'User logged in' });

// Error log
logger.log('errors', { error: 'Something went wrong' }, 'error');

// Warning log
logger.log('warnings', { warning: 'Deprecated API used' }, 'warning');

// Test log
logger.log('tests', { test: 'Unit test passed' }, 'test');

await logger.close();
`

Framework Integration

$3

`typescript
import express from 'express';
import { Logger } from 'logflowclient';

const app = express();
const logger = new Logger({ api_key: 'lf_...' });

app.use((req, res, next) => {
const start = Date.now();

res.on('finish', () => {
const duration = Date.now() - start;
logger.log('requests', {
path: req.path,
method: req.method,
status: res.statusCode,
duration_ms: duration
});
});

next();
});

// Graceful shutdown
process.on('SIGTERM', async () => {
await logger.close();
process.exit(0);
});
`

$3

`typescript
// lib/logger.ts
import { Logger } from 'logflowclient';

let loggerInstance: Logger | null = null;

export function getLogger(): Logger {
if (!loggerInstance) {
loggerInstance = new Logger({
api_key: process.env.LOGFLOW_API_KEY!
});
}
return loggerInstance;
}

// pages/api/[...route].ts
import { getLogger } from '../../lib/logger';

export default async function handler(req: any, res: any) {
const logger = getLogger();

logger.log('api_calls', {
endpoint: req.url,
method: req.method
});

// Your API logic
}
`

Best Practices

$3

Create one logger instance and reuse it:

`typescript
// Good ✅
const logger = new Logger({ api_key: 'lf_...' });

for (let i = 0; i < 100; i++) {
logger.log('events', { count: i });
}

await logger.close();

// Bad ❌
for (let i = 0; i < 100; i++) {
const logger = new Logger({ api_key: 'lf_...' });
logger.log('events', { count: i });
await logger.close();
}
`

$3

Organize logs into logical buckets:

`typescript
logger.log('errors', { ... }); // Application errors
logger.log('user_activity', { ... }); // User interactions
logger.log('api_calls', { ... }); // External API tracking
logger.log('performance', { ... }); // Performance metrics
`

$3

Always flush logs before shutting down:

`typescript
// In your shutdown handler
process.on('SIGTERM', async () => {
await logger.flush();
await logger.close();
process.exit(0);
});
`

API Reference

$3

Create a new Logger instance.

Parameters:
- options.api_key (string): Your LogFlow API key (required)
- options.api_url (string, optional): API URL (default: production URL)
- options.batch_size (number, optional): Logs per batch (default: 10)
- options.flush_interval (number, optional): Seconds between flushes (default: 5.0)
- options.max_retries (number, optional): Max retry attempts (default: 3)
- options.debug (boolean, optional): Enable debug output (default: false)

$3

Send a log entry.

Parameters:
- bucket (string): Log category/bucket name
- data (object): JSON-serializable log data
- log_type (string, optional): Type of log - 'info', 'error', 'warning', or 'test' (default: 'info')

$3

Force flush all pending logs immediately.

$3

Close the logger, flush pending logs, and stop background worker.

Troubleshooting

$3

1. Check your API key: Ensure it's valid and active
2. Enable debug mode: Set debug: true to see what's happening
3. Check network: Ensure your app can reach the LogFlow API
4. Flush logs: Call await logger.flush() or await logger.close() before exiting

$3

`typescript
const logger = new Logger({
api_key: 'lf_...',
debug: true // Enable debug output
});

// Will print:
// [LogFlow] Background worker started
// [LogFlow] Queued log: user_activity (type: info)
// [LogFlow] Sending batch of 1 logs
// [LogFlow] Batch sent successfully
``

License

MIT License - see LICENSE file for details