observable-default

Overview

The observable-default plugin is BSB's built-in observability solution that provides console-based logging with colored output, basic metrics tracking, and distributed tracing support. It's automatically enabled and requires no additional configuration for basic use.

Note: This plugin replaced the previous separate logging-default and metrics-default plugins. Observability (logs, metrics, traces) is now unified under the Observable system.

Key Features

• Colored Console Output - Easy-to-read log levels with color coding
• Structured Logging - JSON-formatted metadata and context
• Log Levels - Debug, info, warn, error with filtering
• Metrics Tracking - Basic counters and timers via Observable API
• Distributed Tracing - Trace context propagation across services
• Zero Configuration - Works out of the box for development

Usage in Plugins

The Observable API is available on all services, events, and plugins via this.log and this.metrics:

import { BSBService, BSBServiceConstructor } from "@bettercorp/service-base";

export class Plugin extends BSBService<null> {
  constructor(context: BSBServiceConstructor) {
    super(context);
  }

  async init(): Promise<void> {
    // Logging
    this.log.info("Service initialized");
    this.log.debug("Debug info", { userId: 123 });
    this.log.warn("Warning message");
    this.log.error("Error occurred", new Error("Something failed"));

    // Metrics
    const counter = this.metrics.counter("requests_total", "Total requests", "Count of all requests");
    counter.increment(1);

    const gauge = this.metrics.gauge("queue_size", "Queue size", "Current queue size");
    gauge.set(42);
  }
}

Usage with Client Classes

When creating client classes, instantiate them in the constructor and pass trace context during method calls:

import { BSBService, BSBServiceConstructor, Observable, DTrace } from "@bettercorp/service-base";

// Client class that receives trace context per operation
export class DatabaseClient {
  constructor() {
    // No observable needed in constructor
  }

  async query(trace: DTrace, sql: string): Promise<any> {
    // Client methods receive trace context, not full Observable
    // The plugin creates Observable from trace when needed
    return [];
  }
}

export class Plugin extends BSBService<null> {
  private dbClient: DatabaseClient;

  constructor(context: BSBServiceConstructor) {
    super(context);
    // Create clients in constructor, not in init/run
    this.dbClient = new DatabaseClient();
  }

  async init(obs: Observable): Promise<void> {
    this.log.info("Service initialized");
  }

  async run(obs: Observable): Promise<void> {
    // Pass obs.trace to client methods, not the full Observable
    const results = await this.dbClient.query(obs.trace, "SELECT * FROM users");
  }
}

Log Levels

BSB supports four log levels with color-coded console output:

Level	Color	When to Use
debug	Cyan	Detailed diagnostic information for troubleshooting
info	Green	Normal operational messages and state changes
warn	Yellow	Warning messages for potentially problematic situations
error	Red	Error conditions and exceptions

Advanced Observable Plugins

For production environments, consider replacing observable-default with specialized plugins:

• Pino - High-performance JSON logging with minimal overhead
• Winston - Flexible logging with multiple transports
• OpenTelemetry - Full observability stack with traces, metrics, and logs
• Graylog (GELF) - Centralized log management
• Syslog - Standard syslog protocol support

Browse the Plugin Marketplace for all available observable plugins.

Configuration

The default observable plugin requires no configuration but respects the NODE_ENV environment variable:

# Development mode (default) - shows all log levels including debug
NODE_ENV=development

# Production mode - hides debug logs
NODE_ENV=production

For advanced configuration and filtering, use specialized observable plugins like Pino or Winston.