@logtape/syslog/dist/syslog.d.ts

Syslog sink for LogTape

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

//#region syslog.d.ts

/**
 * Syslog protocol type.
 * @since 0.12.0
 */
type SyslogProtocol = "udp" | "tcp";
/**
 * Syslog facility codes as defined in RFC 5424.
 * @since 0.12.0
 */
type SyslogFacility = "kernel" | "user" | "mail" | "daemon" | "security" | "syslog" | "lpr" | "news" | "uucp" | "cron" | "authpriv" | "ftp" | "ntp" | "logaudit" | "logalert" | "clock" | "local0" | "local1" | "local2" | "local3" | "local4" | "local5" | "local6" | "local7";
/**
 * Options for the syslog sink.
 * @since 0.12.0
 */
interface SyslogSinkOptions {
  /**
   * The hostname or IP address of the syslog server.
   * @default "localhost"
   */
  readonly hostname?: string;
  /**
   * The port number of the syslog server.
   * @default 514
   */
  readonly port?: number;
  /**
   * The protocol to use for sending syslog messages.
   * @default "udp"
   */
  readonly protocol?: SyslogProtocol;
  /**
   * The syslog facility to use for all messages.
   * @default "local0"
   */
  readonly facility?: SyslogFacility;
  /**
   * The application name to include in syslog messages.
   * @default "logtape"
   */
  readonly appName?: string;
  /**
   * The hostname to include in syslog messages.
   * If not provided, the system hostname will be used.
   */
  readonly syslogHostname?: string;
  /**
   * The process ID to include in syslog messages.
   * If not provided, the current process ID will be used.
   */
  readonly processId?: string;
  /**
   * Connection timeout in milliseconds.
   * @default 5000
   */
  readonly timeout?: number;
  /**
   * Whether to include structured data in syslog messages.
   * @default `false`
   */
  readonly includeStructuredData?: boolean;
  /**
   * The structured data ID to use for log properties.
   * Should follow the format "name@private-enterprise-number".
   * @default "logtape@32473"
   */
  readonly structuredDataId?: string;
}
/**
 * Base interface for syslog connections.
 * @since 0.12.0
 */

/**
 * Creates a syslog sink that sends log messages to a syslog server using the
 * RFC 5424 syslog protocol format.
 *
 * This sink supports both UDP and TCP protocols for reliable log transmission
 * to centralized logging systems. It automatically formats log records according
 * to RFC 5424 specification, including structured data support for log properties.
 *
 * ## Features
 *
 * - **RFC 5424 Compliance**: Full implementation of the RFC 5424 syslog protocol
 * - **Cross-Runtime Support**: Works with Deno, Node.js, Bun, and browsers
 * - **Multiple Protocols**: Supports both UDP (fire-and-forget) and TCP (reliable) delivery
 * - **Structured Data**: Automatically includes log record properties as RFC 5424 structured data
 * - **Facility Support**: All standard syslog facilities (kern, user, mail, daemon, local0-7, etc.)
 * - **Automatic Escaping**: Proper escaping of special characters in structured data values
 * - **Connection Management**: Automatic connection handling with configurable timeouts
 *
 * ## Protocol Differences
 *
 * - **UDP**: Fast, connectionless delivery suitable for high-throughput logging.
 *   Messages may be lost during network issues but has minimal performance impact.
 * - **TCP**: Reliable, connection-based delivery that ensures message delivery.
 *   Higher overhead but guarantees that log messages reach the server.
 *
 * @param options Configuration options for the syslog sink
 * @returns A sink function that sends log records to the syslog server, implementing AsyncDisposable for proper cleanup
 *
 * @example Basic usage with default options
 * ```typescript
 * import { configure } from "@logtape/logtape";
 * import { getSyslogSink } from "@logtape/syslog";
 *
 * await configure({
 *   sinks: {
 *     syslog: getSyslogSink(),  // Sends to localhost:514 via UDP
 *   },
 *   loggers: [
 *     { category: [], sinks: ["syslog"], lowestLevel: "info" },
 *   ],
 * });
 * ```
 *
 * @example Custom syslog server configuration
 * ```typescript
 * import { configure } from "@logtape/logtape";
 * import { getSyslogSink } from "@logtape/syslog";
 *
 * await configure({
 *   sinks: {
 *     syslog: getSyslogSink({
 *       hostname: "log-server.example.com",
 *       port: 1514,
 *       protocol: "tcp",
 *       facility: "mail",
 *       appName: "my-application",
 *       timeout: 10000,
 *     }),
 *   },
 *   loggers: [
 *     { category: [], sinks: ["syslog"], lowestLevel: "debug" },
 *   ],
 * });
 * ```
 *
 * @example Using structured data for log properties
 * ```typescript
 * import { configure, getLogger } from "@logtape/logtape";
 * import { getSyslogSink } from "@logtape/syslog";
 *
 * await configure({
 *   sinks: {
 *     syslog: getSyslogSink({
 *       includeStructuredData: true,
 *       structuredDataId: "myapp@12345",
 *     }),
 *   },
 *   loggers: [
 *     { category: [], sinks: ["syslog"], lowestLevel: "info" },
 *   ],
 * });
 *
 * const logger = getLogger();
 * // This will include userId and action as structured data
 * logger.info("User action completed", { userId: 123, action: "login" });
 * // Results in: <134>1 2024-01-01T12:00:00.000Z hostname myapp 1234 - [myapp@12345 userId="123" action="login"] User action completed
 * ```
 *
 * @since 0.12.0
 * @see {@link https://tools.ietf.org/html/rfc5424} RFC 5424 - The Syslog Protocol
 * @see {@link SyslogSinkOptions} for detailed configuration options
 */
declare function getSyslogSink(options?: SyslogSinkOptions): Sink & AsyncDisposable;
//# sourceMappingURL=syslog.d.ts.map
//#endregion
export { SyslogFacility, SyslogProtocol, SyslogSinkOptions, getSyslogSink };
//# sourceMappingURL=syslog.d.ts.map