From b5cda8bf6589024a87d621b450618edb18942bc8 Mon Sep 17 00:00:00 2001 From: Hexagon Date: Thu, 21 Mar 2024 00:40:11 +0100 Subject: [PATCH] Cleanup. Docs. --- .github/workflows/bun.yml | 14 -------- .github/workflows/deno.yml | 32 ----------------- .github/workflows/jsr.yml | 12 ++----- .github/workflows/node.yml | 22 ------------ .github/workflows/tests.yml | 23 ++++++++++++ src/log.ts | 4 +++ transports/base.ts | 22 ++++++++++-- transports/console.ts | 22 ++++++++++-- transports/file.ts | 9 ++++- transports/newrelic.ts | 71 ++++++++++++++++++++++++++++++++++--- transports/splunk.ts | 49 +++++++++++++++++++++++-- 11 files changed, 190 insertions(+), 90 deletions(-) delete mode 100644 .github/workflows/bun.yml delete mode 100644 .github/workflows/deno.yml delete mode 100644 .github/workflows/node.yml create mode 100644 .github/workflows/tests.yml diff --git a/.github/workflows/bun.yml b/.github/workflows/bun.yml deleted file mode 100644 index 6511a03..0000000 --- a/.github/workflows/bun.yml +++ /dev/null @@ -1,14 +0,0 @@ -name: Bun CI - -on: [push, pull_request] - -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: antongolub/action-setup-bun@v1.12.8 - with: - bun-version: v1.x # Uses latest bun 1 - - run: bun x jsr add @cross/test @std/assert @cross/deepmerge @cross/utils # Installs dependencies - - run: bun test # Runs the tests \ No newline at end of file diff --git a/.github/workflows/deno.yml b/.github/workflows/deno.yml deleted file mode 100644 index 36b845c..0000000 --- a/.github/workflows/deno.yml +++ /dev/null @@ -1,32 +0,0 @@ -name: Deno CI - -on: - push: - branches: [main] - pull_request: - branches: [main] - -jobs: - test: - runs-on: ubuntu-latest - - steps: - - name: Setup repo - uses: actions/checkout@v4 - - - name: Setup Deno - uses: denoland/setup-deno@v1 - with: - deno-version: v1.x - - - name: Verify formatting - run: deno fmt --check - - - name: Run linter - run: deno lint - - - name: Check types - run: deno check mod.ts - - - name: Run tests - run: deno test \ No newline at end of file diff --git a/.github/workflows/jsr.yml b/.github/workflows/jsr.yml index dd38b00..0bdfc88 100644 --- a/.github/workflows/jsr.yml +++ b/.github/workflows/jsr.yml @@ -1,20 +1,12 @@ -name: Publish to jsr +name: Publish to jsr.io on: release: types: [released] - workflow_dispatch: jobs: publish: - runs-on: ubuntu-latest - permissions: contents: read id-token: write - - steps: - - uses: actions/checkout@v4 - - - name: Publish package - run: npx jsr publish \ No newline at end of file + uses: cross-org/workflows/.github/workflows/jsr-publish.yml@main \ No newline at end of file diff --git a/.github/workflows/node.yml b/.github/workflows/node.yml deleted file mode 100644 index 5d4acd6..0000000 --- a/.github/workflows/node.yml +++ /dev/null @@ -1,22 +0,0 @@ -name: Node.js CI - -on: - push: - branches: [ main ] - pull_request: - branches: [ main ] - -jobs: - build: - - runs-on: ubuntu-latest - - strategy: - matrix: - node-version: [18.x, 21.x] - - steps: - - uses: actions/checkout@v3 - - run: npx jsr add @cross/test @std/assert @cross/deepmerge @cross/utils - - run: "echo '{ \"type\": \"module\" }' > package.json" # Needed for tsx to work - - run: npx --yes tsx --test *.test.ts \ No newline at end of file diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..0853cff --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,23 @@ +name: Testing CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + workflow_dispatch: # Allow manual runs + +jobs: + deno_ci: + uses: cross-org/workflows/.github/workflows/deno-ci.yml@main + with: + entrypoint: mod.ts + bun_ci: + uses: cross-org/workflows/.github/workflows/bun-ci.yml@main + with: + jsr_dependencies: "@cross/test @std/assert @cross/deepmerge @cross/utils" + node_ci: + uses: cross-org/workflows/.github/workflows/node-ci.yml@main + with: + jsr_dependencies: "@cross/test @std/assert @cross/deepmerge @cross/utils" + test_target: "*.test.ts" \ No newline at end of file diff --git a/src/log.ts b/src/log.ts index 7dfdfc6..390fc10 100644 --- a/src/log.ts +++ b/src/log.ts @@ -11,6 +11,10 @@ export class Log { */ transports: LogTransport[] = []; + /** + * Constructs a new Log instansce + * @param transports - An array of transports, defaults to [new ConsoleLogger()] + */ constructor(transports?: LogTransport[]) { if (!transports) { this.transports.push(new ConsoleLogger()); // Default diff --git a/transports/base.ts b/transports/base.ts index 8142e11..afa1e08 100644 --- a/transports/base.ts +++ b/transports/base.ts @@ -1,13 +1,20 @@ import { NumericSeverity, Severity } from "../src/types.ts"; +/** + * Base configuration options for a LogTransport instance. + */ export interface LogTransportBaseOptions { /** - * Minimum severity to be logged, can be overridden with severities + * The minimum severity level for a message to be logged. If a message's severity + * is lower than this value, it will be ignored. This option is overridden if + * the `severities` option is provided. */ minimumSeverity?: Severity; /** - * Takes precedence over minimumSeverity + * An array of specific severity levels to log. Messages with severity levels + * not included in this array will be ignored. This option takes precedence over + * `minimumSeverity`. */ severities?: Severity[]; } @@ -33,10 +40,19 @@ export interface LogTransport { } /** - * Base class for Log Transports. + * Base class for Log Transports. Provides core logging functionality and + * configuration management. Extend this to build custom transports. */ export abstract class LogTransportBase implements LogTransport { + + /** Options to be used, will be initialized with defaults */ protected options: LogTransportBaseOptions; + + /** + * Default configuration options for LogTransportBase. Intended for typical + * logging scenarios where all messages with 'Info' severity or higher should + * be recorded. + */ protected defaults: LogTransportBaseOptions; constructor() { this.defaults = { diff --git a/transports/console.ts b/transports/console.ts index 1850213..0c841ba 100644 --- a/transports/console.ts +++ b/transports/console.ts @@ -4,13 +4,31 @@ import { deepMerge } from "@cross/deepmerge"; import { LogTransportBase, LogTransportBaseOptions } from "./base.ts"; import { Severity } from "../src/types.ts"; -interface ConsoleLoggerOptions extends LogTransportBaseOptions { +/** + * Configuration options for the ConsoleLogger transport. Extends the + * base logging options for all log transports. + */ +export interface ConsoleLoggerOptions extends LogTransportBaseOptions { + /** + * The minimum severity level for a message to be logged to the console. + * If a message's severity is lower than this value, it will not be displayed. + * This option is overridden if the `severities` option is provided. + */ minimumSeverity?: Severity; + + /** + * An array of specific severity levels to log to the console. Messages + * with severity levels not included in this array will be ignored. This + * option takes precedence over `minimumSeverity`. + */ severities?: Severity[]; } export class ConsoleLogger extends LogTransportBase { - options: ConsoleLoggerOptions; + /** + * Options for the ConsoleLogger transport + */ + public options: ConsoleLoggerOptions; /** * Constructs a ConsoleLogger instance. diff --git a/transports/file.ts b/transports/file.ts index 83ebdff..d38f230 100644 --- a/transports/file.ts +++ b/transports/file.ts @@ -7,7 +7,7 @@ import { import { Severity } from "../src/types.ts"; import { deepMerge } from "@cross/deepmerge"; -interface FileLoggerOptions extends LogTransportBaseOptions { +export interface FileLoggerOptions extends LogTransportBaseOptions { minimumSeverity?: Severity; severities?: Severity[]; @@ -21,7 +21,13 @@ interface FileLoggerOptions extends LogTransportBaseOptions { fileFormat?: "json" | "txt"; } +/** + * File Logger Transport. Supports logging to files using txt or json format. + */ export class FileLogger extends LogTransportBase implements LogTransport { + /** + * Options for the file logger transport + */ options: FileLoggerOptions; /** @@ -41,6 +47,7 @@ export class FileLogger extends LogTransportBase implements LogTransport { options, )!; } + /** * Logs a message to the configured file if the severity is at or above the transport's log level. * diff --git a/transports/newrelic.ts b/transports/newrelic.ts index 1962a1b..5b3c80f 100644 --- a/transports/newrelic.ts +++ b/transports/newrelic.ts @@ -6,17 +6,55 @@ import { import { Severity } from "../src/types.ts"; import { deepMerge } from "@cross/deepmerge"; -interface NewRelicLoggerOptions extends LogTransportBaseOptions { - apiKey: string; // The user's New Relic API key - region?: string; // The New Relic region (e.g., 'US', 'EU') +/** + * Configuration options for the New Relic logger. Extends the base logging options. + */ +export interface NewRelicLoggerOptions extends LogTransportBaseOptions { + /** + * Your New Relic Insights Insert API key. This is required for sending logs. + */ + apiKey: string; + + /** + * The New Relic region where your data is stored. + * Valid values: 'US', 'EU', 'FedRamp'. Defaults to 'US'. + */ + region?: string; + + /** + * An attribute name to identify the service generating the logs. + * Will be added to log events in New Relic. + */ serviceAttribute?: string; + + /** + * An attribute name to categorize the log type. Will be added to + * log events in New Relic. + */ logtypeAttribute?: string; + + /** + * An attribute name to specify the hostname of the machine generating the logs. + * Will be added to log events in New Relic. + */ hostnameAttribute?: string; } +/** + * A Log Transport implementation that sends log events to New Relic Insights. + */ export class NewRelicLogger extends LogTransportBase implements LogTransport { + + /** + * Options for the NewRelicLogger Transport + */ options: NewRelicLoggerOptions; + /** + * Creates a new NewRelicLogger instance. + * + * @param options - Configuration options for the New Relic logger. + */ constructor(options: NewRelicLoggerOptions) { super(); this.options = deepMerge( @@ -25,6 +63,14 @@ export class NewRelicLogger extends LogTransportBase implements LogTransport { )!; } + /** + * Logs a message to New Relic Insights. Used as an entrypoint for each log into this transport. + * + * @param severity - The severity level of the message. + * @param scope - An optional scope to categorize or group the log message. + * @param data - An array of data to be logged. + * @param timestamp - The timestamp of the log entry. + */ log(severity: Severity, scope: string, data: unknown[], timestamp: Date) { if (this.shouldLog(severity)) { const serializedData = this.serializeToText(data); @@ -38,6 +84,15 @@ export class NewRelicLogger extends LogTransportBase implements LogTransport { } } + /** + * Formats a log event in a structure suitable for New Relic Insights. + * + * @param severity - The severity level of the message. + * @param scope - The scope of the log message. + * @param data - The serialized log data. + * @param timestamp - The timestamp of the log entry. + * @returns A formatted event object ready to be sent to New Relic. + */ private formatEvent( severity: Severity, scope: string, @@ -55,6 +110,11 @@ export class NewRelicLogger extends LogTransportBase implements LogTransport { }; } + /** + * Sends a log event to New Relic Insights. Handles potential errors. + * + * @param event - The formatted log event object. + */ private async sendToNewRelic(event: object) { const endpoint = this.getEndpoint(); try { @@ -77,7 +137,10 @@ export class NewRelicLogger extends LogTransportBase implements LogTransport { console.error("Network error sending log event to New Relic:", error); } } - + /** + * Determines the correct New Relic Insights API endpoint based on the configured region. + * @returns The API endpoint URL as a string. + */ private getEndpoint(): string { if (this.options.region === "US") { return "https://log-api.newrelic.com/log/v1"; diff --git a/transports/splunk.ts b/transports/splunk.ts index 17f5c06..0e19210 100644 --- a/transports/splunk.ts +++ b/transports/splunk.ts @@ -6,16 +6,44 @@ import { import { Severity } from "../src/types.ts"; import { deepMerge } from "@cross/deepmerge"; -interface SplunkHecClientOptions extends LogTransportBaseOptions { +/** + * Configuration options for the Splunk HEC (HTTP Event Collector) logger. + * Extends the base LogTransportBaseOptions. + */ +export interface SplunkHecClientOptions extends LogTransportBaseOptions { minimumSeverity?: Severity; severities?: Severity[]; + + /** + * The HTTP Event Collector endpoint for your Splunk instance. + */ hecEndpoint?: string; + + /** + * The authorization token for sending events to Splunk HEC. + */ hecToken?: string; + + /** + * The source type to be associated with the log events in Splunk. + */ sourceType?: string; } +/** + * A Log Transport implementation that sends log events to Splunk's HTTP Event Collector (HEC). + */ export class SplunkHecLogger extends LogTransportBase implements LogTransport { - options: SplunkHecClientOptions; + /** + * Options for the Splunk HEC Transport + */ + public options: SplunkHecClientOptions; + + /** + * Creates a new SplunkHecLogger instance. + * + * @param options - Configuration options for the Splunk HEC logger. + */ constructor(options: SplunkHecClientOptions) { super(); this.options = deepMerge( @@ -26,6 +54,15 @@ export class SplunkHecLogger extends LogTransportBase implements LogTransport { options, )!; } + + /** + * Logs a message to Splunk HEC. Used as an entrypoint for each log into this transport. + * + * @param severity - The severity level of the message. + * @param scope - An optional scope to categorize or group the log message. + * @param data - An array of data to be logged. + * @param timestamp - The timestamp of the log entry. + */ log(level: Severity, scope: string, data: unknown[], timestamp: Date) { if (this.shouldLog(level)) { const serializedData = this.serializeToText(data); @@ -34,6 +71,9 @@ export class SplunkHecLogger extends LogTransportBase implements LogTransport { } } + /** + * Transforms this event into a format suitable for Splunk HEC + */ private formatEvent( level: Severity, scope: string, @@ -51,6 +91,11 @@ export class SplunkHecLogger extends LogTransportBase implements LogTransport { }; } + /** + * Sends a log event to Splunk's HTTP Event Collector. Handles potential errors. + * + * @param event - The formatted log event object. + */ private async sendToHec(event: object) { if (this.options.hecEndpoint && this.options.hecToken) { try {