LogFlow Node.js SDK

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

Installation

npm install logflowclient

Quick Start

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

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

Basic Logging

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

Error Logging

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();

API Call Tracking

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();

User Activity Tracking

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();

Log Types

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

Express.js

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);
});

Next.js

// 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

1. Reuse Logger Instance

Create one logger instance and reuse it:

// 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();
}

2. Use Descriptive Bucket Names

Organize logs into logical buckets:

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

3. Graceful Shutdown

Always flush logs before shutting down:

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

API Reference

new Logger(options: LoggerOptions)

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)

logger.log(bucket: string, data: Record<string, any>, log_type?: LogType): void

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')

logger.flush(): Promise<void>

Force flush all pending logs immediately.

logger.close(): Promise<void>

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

Troubleshooting

Logs Not Appearing?

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

Debug Mode

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