vibex.sh Node.js SDK

Fail-safe logging handler for sending logs to vibex.sh.

Features

• Fail-Safe: Silently disables if configuration is missing or invalid
• Kill Switch: Permanently disables on 401/403 errors (expired/invalid tokens)
• Easy Integration: Drop-in Winston transport
• Zero Dependencies (except winston)

Installation

npm install vibex-sdk winston

Authentication

Before using the SDK, you need to get your authentication token. Run this command in your terminal:

npx vibex-sh login

This will generate your VIBEX_TOKEN that you'll use in the environment variables below.

Quick Start

1. Set environment variables:

export VIBEX_TOKEN=vb_live_your_token_here
export VIBEX_SESSION_ID=my-production-app

2. Use in your Node.js application:

const winston = require('winston');
const { VibexHandler } = require('vibex-sdk');

// Create logger
const logger = winston.createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console(),
    new VibexHandler({ verbose: true }), // verbose shows status messages
  ],
});

// Use normally - only JSON logs are sent to Vibex
logger.info(JSON.stringify({ cpu: 45, memory: 78, status: 'healthy' }));
logger.info(JSON.stringify({ error: 'connection_failed', retry_count: 3 }));

Configuration

The SDK reads configuration from environment variables:

• VIBEX_TOKEN (required): Your Vibex API token
• VIBEX_SESSION_ID (required): Your session ID

Fail-Safe Behavior

The SDK is designed to be fail-safe:

1. Missing Config: If VIBEX_TOKEN or VIBEX_SESSION_ID is missing, the handler silently disables itself
2. Invalid Token: On 401/403 responses, the handler permanently disables for the process lifetime
3. Network Errors: All network errors are silently handled - your application continues normally
4. Rate Limits: On 429 (rate limit), logs are dropped but the handler remains enabled. Logs are still written to console by default (passthroughConsole: true)

Console Passthrough Options

By default, logs are forwarded to Vibex and also written to stderr (console), ensuring you can always see your logs locally while they're sent to Vibex.

passthroughConsole (default: true)

When enabled (default), logs are always written to stderr in addition to being sent to Vibex. This provides visibility into your logs while forwarding them to Vibex.

// Default behavior - logs written to console and sent to Vibex
const handler = new VibexHandler(); // passthroughConsole: true by default

// To disable console output (logs only sent to Vibex)
const handler = new VibexHandler({ passthroughConsole: false });

passthroughOnFailure (default: false)

When enabled, logs are written to stderr when sending to Vibex fails (rate limits, network errors, etc.). This is useful as an additional safety net, but with passthroughConsole: true by default, it's typically not needed.

// Write logs to console only when sending fails
const handler = new VibexHandler({ passthroughConsole: false, passthroughOnFailure: true });

Supported Log Types

The SDK supports multiple log types for different use cases. By default, the handler auto-detects JSON vs text logs and sends them appropriately.

JSON Logs (Default)

JSON logs are sent with a hybrid structure that includes message, level, metrics, and context:

// ✅ Good - JSON logs are sent with hybrid structure
logger.info(JSON.stringify({ cpu: 45, memory: 78, status: 'healthy' }));
logger.info(JSON.stringify({ error: 'connection_failed', retry_count: 3 }));

// ✅ Also works - Plain text logs are sent as text type
logger.info('Application started');
logger.info('High memory usage: 85%');

Specifying Log Types

You can specify a log type when creating the handler or when using the client directly:

// Handler with specific log type
const handler = new VibexHandler({ logType: 'web-server' });

// Direct client usage with different types
await client.sendLog('json', { cpu: 45, memory: 78 });
await client.sendLog('text', 'GET /api/users 200 150ms');
await client.sendLog('web-server', '127.0.0.1 - - [25/Dec/2024:10:00:00 +0000] "GET /path HTTP/1.1" 200');
await client.sendLog('stacktrace', 'Error: Connection failed\n  at file.js:10:5');

Available Log Types

• json (default): Structured JSON logs with hybrid structure (object payload)
• text: Plain text logs (string payload)
• web-server: Web server access logs (Nginx, Apache) - string payload
• loadbalancer: Load balancer logs (HAProxy, AWS ALB) - string payload
• stacktrace: Stack trace logs - string payload
• firewall: Firewall logs (iptables, pfSense, Cisco ASA) - string payload
• kubernetes: Kubernetes pod/container logs - string payload
• docker: Docker container logs - string payload
• network: Network logs (tcpdump, wireshark) - string payload
• keyvalue: Key-value pair logs - string payload
• json-in-text: JSON embedded in text - string payload
• smart-pattern: Smart pattern logs (multi-language) - string payload
• raw: Raw logs (fallback) - string payload

Advanced Usage

Direct Client Usage

const { VibexClient, VibexConfig } = require('vibex-sdk');

const config = new VibexConfig();
const client = new VibexClient(config);

// Send JSON log (default behavior)
await client.sendLog('json', { cpu: 45, memory: 78 });

// Send text log
await client.sendLog('text', 'Application started successfully');

// Send web server log
await client.sendLog('web-server', '127.0.0.1 - - [25/Dec/2024:10:00:00 +0000] "GET /api/users HTTP/1.1" 200 1234');

// Send stack trace
await client.sendLog('stacktrace', 'Error: Connection failed\n  at file.js:10:5\n  at main.js:25:3');

Check if Enabled

const { VibexHandler } = require('vibex-sdk');

const handler = new VibexHandler();
if (handler.isEnabled()) {
  console.log('Vibex is active');
} else {
  console.log('Vibex is disabled (missing config or expired token)');
}

Get Status

const handler = new VibexHandler();
const status = handler.getStatus();
console.log(status);
// {
//   enabled: true,
//   disabled: false,
//   disabledPermanently: false,
//   configValid: true,
//   reason: 'Enabled and ready',
//   apiUrl: 'https://vibex.sh/api/v1/ingest',
//   sessionId: 'my-product...',
//   tokenPrefix: 'vb_live_y...'
// }

Verbose Mode

Enable verbose mode to see status messages when the handler initializes or encounters errors:

const handler = new VibexHandler({ verbose: true });

Node.js Version Compatibility

• Node.js 18+: Uses native fetch API
• Node.js 14-17: Uses built-in http/https modules as fallback

License

MIT