Syslog sink

This API is available since LogTape 0.12.0.

If you have a syslog server running, you can use the syslog sink to send log messages to the server using RFC 5424 format via @logtape/syslog package:

Deno

deno add jsr:@logtape/syslog

npm

npm add @logtape/syslog

pnpm

pnpm add @logtape/syslog

Yarn

yarn add @logtape/syslog

Bun

bun add @logtape/syslog

The quickest way to get started is to use the getSyslogSink() function without any arguments:

import {  } from "@logtape/logtape";
import {  } from "@logtape/syslog";

await ({
  : {
    : (),
  },
  : [
    { : [], : ["syslog"], : "debug" },
  ],
});

This will send log messages to a syslog server running on localhost:514 using UDP protocol with the default facility local0 and application name derived from the process.

You can customize the syslog configuration by passing options to the getSyslogSink() function:

import {  } from "@logtape/logtape";
import {  } from "@logtape/syslog";

await ({
  : {
    : ({
      : "syslog.example.com",
      : 1514,
      : "tcp",
      : "mail",
      : "my-application",
      : 5000,
    }),
  },
  : [
    { : [], : ["syslog"], : "info" },
  ],
});

Structured data

RFC 5424 syslog supports structured data, which allows you to include key–value pairs in log messages. LogTape automatically includes log record properties as structured data when the includeStructuredData option is enabled:

import {  } from "@logtape/logtape";
import {  } from "@logtape/syslog";

await ({
  : {
    : ({
      : true,
      : "myapp@12345",
    }),
  },
  : [
    { : [], : ["syslog"], : "debug" },
  ],
});

With this configuration, log records with properties will include them as structured data in the syslog message:

import { ,  } from "@logtape/logtape";
import {  } from "@logtape/syslog";

await ({
  : {
    : ({
      : true,
      : "myapp@12345",
    }),
  },
  : [
    { : [], : ["syslog"], : "debug" },
  ],
});

const  = ();
.("User login successful", { : 12345, : "oauth" });

This will generate a syslog message like:

<134>1 2024-01-01T12:00:00.000Z hostname myapp 1234 - [myapp@12345 userId="12345" method="oauth"] User login successful

Only properties whose keys are valid RFC 5424 SD-NAME values are included: keys must be 1 to 32 printable US-ASCII characters and must not contain spaces, =, ], or ". Properties with invalid keys are skipped. Control characters in structured data values are replaced with printable #NNN sequences before the message is sent.

Message escaping

Control characters in the log message are replaced with printable #NNN sequences before the message is sent, in the same way as in structured data values. This matters most for TCP, which delimits syslog messages with a newline (non-transparent framing, as RFC 6587 calls it): a newline left in the message would terminate the frame, and whatever followed it would be received as a separate syslog record. If log messages can contain input from outside the application, such a record can be forged at will.

Supported facilities

The syslog sink supports all standard RFC 5424 facilities:

• kern, user, mail, daemon, auth, syslog, lpr, news
• uucp, cron, authpriv, ftp
• local0, local1, local2, local3, local4, local5, local6, local7

Protocol support

The syslog sink supports both UDP and TCP protocols:

UDP (default)

Fire-and-forget delivery, suitable for high-throughput logging where occasional message loss is acceptable.

TCP

Reliable delivery with connection management, suitable for critical log messages that must not be lost.

For more details, see the getSyslogSink() function and SyslogSinkOptions interface in the API reference.