Syslog Client Plugin

Send BSB logs to remote syslog servers via UDP, TCP, or TLS.

Overview

The Syslog Client Observable plugin forwards application logs to remote syslog servers, enabling integration with existing syslog infrastructure for centralized log management. This plugin implements both RFC 3164 (BSD syslog) and RFC 5424 (modern syslog) for maximum compatibility.

Features

• Multiple Protocols: Support for UDP, TCP, and TLS transport protocols
• RFC Compliance: RFC 3164 and RFC 5424 syslog format support
• Level Filtering: Configure which log levels are sent to the syslog server
• Configurable Facility: Set syslog facility codes (0-23) for proper categorization
• Custom Application Name: Identify your application in syslog messages
• Automatic Formatting: BSB logs are automatically formatted and mapped to syslog severity levels

Installation

npm install @bsb/syslog

Configuration

Add the plugin to your BSB configuration file:

plugins:
  observables:
    - plugin: "@bsb/syslog"
      observable: "observable-syslog"
      enabled: true
      config:
        host: "localhost"
        port: 514
        protocol: "udp"
        facility: 16
        appName: "my-app"
        rfc: "5424"
        levels:
          debug: true
          info: true
          warn: true
          error: true

Configuration Options

Facility Codes

Common syslog facility codes:

• 0-7: System facilities (kern, user, mail, daemon, auth, syslog, lpr, news)
• 16-23: Local use (local0-local7) - Recommended for applications

Local facilities (16-23) are typically used for custom applications. The default value of 16 (local0) is a safe choice for most BSB applications.

Protocol Selection

UDP (User Datagram Protocol)

• Fast, connectionless delivery
• Fire-and-forget semantics
• No delivery guarantee (messages may be lost)
• Good for high-volume logging where occasional message loss is acceptable
• Lowest overhead and latency

TCP (Transmission Control Protocol)

• Reliable, connection-oriented delivery
• Guaranteed message delivery
• Connection management overhead
• Use when every log message must be delivered
• Slightly higher latency than UDP

TLS (Transport Layer Security)

• Encrypted TCP connection
• Authentication and security
• Higher overhead than plain TCP
• Use for secure log transmission over untrusted networks
• Requires additional TLS configuration

Usage

Once configured, the plugin automatically forwards logs to the syslog server. No additional code is required in your services:

import { BSBService, BSBServiceConstructor } from "@bsb/base";

export class MyService extends BSBService {
  constructor(context: BSBServiceConstructor) {
    super(context);
  }

  async init(): Promise<void> {
    // Logs are automatically sent to syslog server
    this.log.info("Service initialized");
    this.log.warn("Low memory warning");
    this.log.error("Failed to connect", new Error("Connection timeout"));
  }
}

Log Level Mapping

BSB log levels are automatically mapped to syslog severity levels:

Testing

Using a Local Syslog Server

Linux (rsyslog)

# View syslog messages
sudo tail -f /var/log/syslog

# Or filter by application name
sudo grep "my-app" /var/log/syslog

macOS (system log)

# View logs for your application
log stream --predicate 'process == "my-app"'

Using Logger Command

Test your syslog server using the logger command:

# Send a test message
logger -n localhost -P 514 "Test message from logger"

# Or use netcat to send raw syslog messages
echo "<134>Test syslog message" | nc -u localhost 514

Using BSB Syslog Server

For testing and development, use the Syslog Server plugin included in this package:

import { BSBService, BSBServiceConstructor } from "@bsb/base";
import { Client as SyslogServerClient } from "@bsb/syslog/lib/plugins/service-syslog-server";

export class TestService extends BSBService {
  private syslogClient!: SyslogServerClient;

  constructor(context: BSBServiceConstructor) {
    super(context);
  }

  async init(): Promise<void> {
    this.syslogClient = new SyslogServerClient(this);

    // Subscribe to received syslog messages
    await this.syslogClient.events.onEvent("onMessage", this.obs, async (obs, message) => {
      obs.log.info("Received syslog: {message}", {
        message: message.message,
        host: message.host
      });
    });
  }
}

Troubleshooting

Connection Errors

If you see connection errors, verify:

1. Syslog server is running and accessible
2. Firewall rules allow traffic on the configured port
3. The host and port configuration are correct

Messages Not Appearing

Check that:

1. Log level filtering is not too restrictive
2. The syslog server is configured to accept messages from your facility
3. UDP messages may be dropped on congested networks (try TCP)

TLS Connection Issues

For TLS connections:

1. Verify certificates are valid and properly formatted
2. Check that the CA certificate matches the server's certificate chain
3. Ensure the server supports TLS on the configured port

Related Plugins

• Syslog Server: Receive syslog messages from network devices and applications
• @bsb/logging-default: Default console logging for BSB

License

(AGPL-3.0-only OR Commercial)

See the LICENSE file for details.