From 4a40b895061c12feb101f7f384a2e8bdcc33a40d Mon Sep 17 00:00:00 2001 From: Hexagon Date: Mon, 18 Mar 2024 20:08:22 +0000 Subject: [PATCH] Docs --- README.md | 52 +++++++++++++++++++++--------- deno.json | 2 +- src/transport.ts | 73 +++++++++++++++++++++---------------------- src/types.ts | 28 ++++++++--------- transports/console.ts | 9 ++---- transports/file.ts | 4 +-- transports/splunk.ts | 4 +-- 7 files changed, 91 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 86913a4..d7fb73f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ **@cross/log - Generic logger for Node.js, Deno, and Bun** -**Installation** +## Installation Instructions are available at [https://jsr.io/@cross/log](https://jsr.io/@cross/log). Here's the quick @@ -17,9 +17,7 @@ npx jsr add @cross/log bunx jsr add @cross/log ``` -**Getting Started** - -**Simplest Use Case** +## Getting Started ```javascript import { Log } from "@cross/log"; @@ -44,16 +42,9 @@ logger.info("Hello log!"); - **Global and Transport Filtering:** Set log levels globally or configure fine-grained filtering per transport. -**Core Classes** - -- **Log:** Central class for managing log transports and dispatching log - messages. - - `debug(message: string)` - - `info(message: string)` - - `warn(message: string)` - - `error(message: string)` +### Example Usage -**Example Usage (with Custom Transports)** +#### Console + File Transport ```javascript import { ConsoleLogger, FileLogger, Log, Severity } from "./mod.ts"; @@ -61,13 +52,44 @@ import { ConsoleLogger, FileLogger, Log, Severity } from "./mod.ts"; const myLogger = new Log([ new ConsoleLogger({ // Only write severity Info and higher to console - minimumSeverity: Severity.Info + minimumSeverity: Severity.Info, // Also possible to select individual severities // severities: [Severity.Info, Severity.Error] }), new FileLogger({ filePath: "./app.log", - fileFormat: "txt" + fileFormat: "txt", + }), +]); + +myLogger.debug("Initializing application..."); +myLogger.warn("Received a potentially invalid request"); +try { + // ... code that might fail +} catch (error) { + myLogger.error("Critical failure!", error); +} +``` + +#### Splunk HEC Transport + +1. **Obtain Splunk HEC endpoint and token:** + - Log into your Splunk instance. + - Navigate to **Settings > Data Inputs > HTTP Event Collector**. + - Create a new input or locate an existing one, noting its endpoint URL and + token. + +2. **Integrate the Splunk HEC Transport:** + +```javascript +import { ConsoleLogger, Log, Severity, SplunkHecClient } from "@cross/log"; + +const myLogger = new Log([ + new ConsoleLogger({ minimumSeverity: Severity.Info }), + new SplunkHecClient({ + hecEndpoint: "https://splunk-server:8088/services/collector", + hecToken: "your-splunk-hec-token", + sourceType: "my_app_logs", // Adjust as needed }), ]); diff --git a/deno.json b/deno.json index 2e5e8ec..c1c1423 100644 --- a/deno.json +++ b/deno.json @@ -1,6 +1,6 @@ { "name": "@cross/log", - "version": "0.10.0", + "version": "0.10.1", "exports": { ".": "./mod.ts", "./console": "./transports/console.ts", diff --git a/src/transport.ts b/src/transport.ts index ef80e36..cfde708 100644 --- a/src/transport.ts +++ b/src/transport.ts @@ -1,4 +1,4 @@ -import { Severity, NumericSeverity } from "./types.ts"; +import { NumericSeverity, Severity } from "./types.ts"; export interface LogTransportBaseOptions { /** @@ -10,7 +10,7 @@ export interface LogTransportBaseOptions { * Takes precedence over minimumSeverity */ severities?: Severity[]; -}; +} /** * Interface for defining the core functionality of a Log Transport. @@ -36,40 +36,39 @@ export interface LogTransport { * Base class for Log Transports. */ export abstract class LogTransportBase implements LogTransport { - protected options: LogTransportBaseOptions; - protected defaults: LogTransportBaseOptions; - constructor() { - this.defaults = { - minimumSeverity: Severity.Info, - }; - this.options = this.defaults; - } - - /** - * Abstract method for logging events. To be implemented by specific transports - */ - abstract log( - severity: Severity, - scope: string, - data: unknown[], - timestamp: Date, - ): void; - - /** - * Determines if the message should be logged based on its severity and the configured log level. - * @param level - The severity level of the message. - * @returns True if the message should be logged, false otherwise. - */ - protected shouldLog(severity: Severity): boolean { - // Check severities list first (if present) - if (this.options.severities) { - return this.options.severities.includes(severity); - } else { - // Fallback to minimum severity check - const minimumLevel = this.options.minimumSeverity ?? Severity.Debug; - return NumericSeverity.get(severity)! >= - NumericSeverity.get(minimumLevel)!; - } + protected options: LogTransportBaseOptions; + protected defaults: LogTransportBaseOptions; + constructor() { + this.defaults = { + minimumSeverity: Severity.Info, + }; + this.options = this.defaults; + } + + /** + * Abstract method for logging events. To be implemented by specific transports + */ + abstract log( + severity: Severity, + scope: string, + data: unknown[], + timestamp: Date, + ): void; + + /** + * Determines if the message should be logged based on its severity and the configured log level. + * @param level - The severity level of the message. + * @returns True if the message should be logged, false otherwise. + */ + protected shouldLog(severity: Severity): boolean { + // Check severities list first (if present) + if (this.options.severities) { + return this.options.severities.includes(severity); + } else { + // Fallback to minimum severity check + const minimumLevel = this.options.minimumSeverity ?? Severity.Debug; + return NumericSeverity.get(severity)! >= + NumericSeverity.get(minimumLevel)!; } } - \ No newline at end of file +} diff --git a/src/types.ts b/src/types.ts index ad7bbb2..9f2a027 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,23 +1,21 @@ - /** * Map for convenient comparison of log levels by numeric value. */ export const NumericSeverity: Map = new Map([ - ["DEBUG", 100], - ["INFO", 200], - ["LOG", 300], - ["WARN", 400], - ["ERROR", 500], - ]); - - + ["DEBUG", 100], + ["INFO", 200], + ["LOG", 300], + ["WARN", 400], + ["ERROR", 500], +]); + /** * Enumeration of available log levels. */ export enum Severity { - Debug = "DEBUG", - Info = "INFO", - Log = "LOG", - Warn = "WARN", - Error = "ERROR", -} \ No newline at end of file + Debug = "DEBUG", + Info = "INFO", + Log = "LOG", + Warn = "WARN", + Error = "ERROR", +} diff --git a/transports/console.ts b/transports/console.ts index 965262e..ed97cb9 100644 --- a/transports/console.ts +++ b/transports/console.ts @@ -1,13 +1,8 @@ // deno-lint-ignore-file import { Colors } from "@cross/utils"; import { deepMerge } from "@cross/deepmerge"; -import { - LogTransportBase, - LogTransportBaseOptions, -} from "../src/transport.ts"; -import { - Severity, -} from "../src/types.ts"; +import { LogTransportBase, LogTransportBaseOptions } from "../src/transport.ts"; +import { Severity } from "../src/types.ts"; interface ConsoleLoggerOptions extends LogTransportBaseOptions { minimumSeverity?: Severity; diff --git a/transports/file.ts b/transports/file.ts index 9204abd..79a634c 100644 --- a/transports/file.ts +++ b/transports/file.ts @@ -4,9 +4,7 @@ import { LogTransportBase, LogTransportBaseOptions, } from "../src/transport.ts"; -import { - Severity, -} from "../src/types.ts"; +import { Severity } from "../src/types.ts"; import { deepMerge } from "@cross/deepmerge"; diff --git a/transports/splunk.ts b/transports/splunk.ts index 0dcef3e..c834017 100644 --- a/transports/splunk.ts +++ b/transports/splunk.ts @@ -3,9 +3,7 @@ import { LogTransportBase, LogTransportBaseOptions, } from "../src/transport.ts"; -import { - Severity, -} from "../src/types.ts"; +import { Severity } from "../src/types.ts"; import { deepMerge } from "@cross/deepmerge"; interface SplunkHecClientOptions extends LogTransportBaseOptions {