@voidcli/logging 0.1.0

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./telemetryLogger";
+export * from "./logger";
+export * from "./telemetry";

package/dist/client/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./telemetryLogger"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./telemetry"), exports);

package/dist/client/logger.d.ts

@@ -0,0 +1,9 @@
+import { TelemetryLogger } from "./telemetryLogger";
+export declare class Logger<ProjectFields extends Record<string, unknown>> {
+    private readonly client;
+    constructor(client: TelemetryLogger<ProjectFields>);
+    log(verbosity: number, section: string, raw: Record<string, unknown>, projectFields: ProjectFields): void;
+    info(section: string, raw: Record<string, unknown>, projectFields: ProjectFields): void;
+    warn(section: string, raw: Record<string, unknown>, projectFields: ProjectFields): void;
+    error(section: string, raw: Record<string, unknown>, projectFields: ProjectFields): void;
+}

package/dist/client/logger.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const models_1 = require("../models");
+class Logger {
+    constructor(client) {
+        this.client = client;
+    }
+    log(verbosity, section, raw, projectFields) {
+        this.client.enqueueLog({
+            verbosity,
+            section,
+            raw,
+            ...projectFields,
+        });
+    }
+    info(section, raw, projectFields) {
+        this.log(models_1.Verbosity.info, section, raw, projectFields);
+    }
+    warn(section, raw, projectFields) {
+        this.log(models_1.Verbosity.warn, section, raw, projectFields);
+    }
+    error(section, raw, projectFields) {
+        this.log(models_1.Verbosity.error, section, raw, projectFields);
+    }
+}
+exports.Logger = Logger;

package/dist/client/telemetry.d.ts

@@ -0,0 +1,9 @@
+import { TelemetryLogger } from "./telemetryLogger";
+export declare class Telemetry<ProjectFields extends Record<string, unknown>> {
+    private readonly client;
+    constructor(client: TelemetryLogger<ProjectFields>);
+    gauge(name: string, value: number, projectFields: ProjectFields, opts?: {
+        unit?: string;
+        tags?: Record<string, string>;
+    }): void;
+}

package/dist/client/telemetry.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Telemetry = void 0;
+class Telemetry {
+    constructor(client) {
+        this.client = client;
+    }
+    gauge(name, value, projectFields, opts) {
+        this.client.enqueueMetric({
+            name,
+            value,
+            unit: opts?.unit,
+            tags: opts?.tags,
+            ...projectFields,
+        });
+    }
+}
+exports.Telemetry = Telemetry;

package/dist/client/telemetryLogger.d.ts

@@ -0,0 +1,21 @@
+import type { LogEvent, MetricEvent, TelemetryClientConfig } from "../models";
+export declare class TelemetryLogger<ProjectFields extends Record<string, unknown> = {}> {
+    private readonly config;
+    private static instance;
+    private logsQueue;
+    private metricsQueue;
+    private logVerbosityMask;
+    private flushIntervalSeconds;
+    private timer;
+    private flushing;
+    static init<P extends Record<string, unknown>>(config: TelemetryClientConfig): TelemetryLogger<P>;
+    static get<P extends Record<string, unknown>>(): TelemetryLogger<P>;
+    private constructor();
+    setLogVerbosity(mask: number): void;
+    setFlushIntervalSeconds(seconds: number): void;
+    private applyFlushSchedule;
+    enqueueLog(item: LogEvent<ProjectFields>): void;
+    enqueueMetric(item: MetricEvent<ProjectFields>): void;
+    flush(): void;
+    shutdown(): Promise<void>;
+}

package/dist/client/telemetryLogger.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryLogger = void 0;
+const models_1 = require("../models");
+class TelemetryLogger {
+    static init(config) {
+        const inst = new TelemetryLogger(config);
+        TelemetryLogger.instance = inst;
+        return inst;
+    }
+    static get() {
+        if (!TelemetryLogger.instance) {
+            throw new Error("TelemetryClient not initialized. Call TelemetryClient.init(...) first.");
+        }
+        return TelemetryLogger.instance;
+    }
+    constructor(config) {
+        this.config = config;
+        this.logsQueue = [];
+        this.metricsQueue = [];
+        this.logVerbosityMask = models_1.Verbosity.all;
+        this.timer = null;
+        this.flushing = false;
+        this.flushIntervalSeconds = config.flushIntervalSeconds ?? 10;
+        if (this.config.enabled !== false)
+            this.applyFlushSchedule();
+    }
+    setLogVerbosity(mask) {
+        this.logVerbosityMask = mask;
+    }
+    setFlushIntervalSeconds(seconds) {
+        if (seconds < 0 || !Number.isFinite(seconds)) {
+            throw new Error("flushIntervalSeconds must be a non-negative finite number.");
+        }
+        this.flushIntervalSeconds = seconds;
+        if (this.config.enabled !== false)
+            this.applyFlushSchedule();
+    }
+    applyFlushSchedule() {
+        // stop any existing timer
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        // immediate mode => no timer
+        if (this.flushIntervalSeconds === 0)
+            return;
+        // timer-based mode
+        this.timer = setInterval(() => void this.flush(), this.flushIntervalSeconds * 1000);
+        this.timer?.unref?.();
+    }
+    enqueueLog(item) {
+        if (this.config.enabled === false)
+            return;
+        if ((this.logVerbosityMask & item.verbosity) === 0)
+            return;
+        this.logsQueue.push(item);
+        // immediate mode: flush right away (don’t await)
+        if (this.flushIntervalSeconds === 0)
+            void this.flush();
+    }
+    enqueueMetric(item) {
+        if (this.config.enabled === false)
+            return;
+        this.metricsQueue.push(item);
+        // immediate mode: flush right away (don’t await)
+        if (this.flushIntervalSeconds === 0)
+            void this.flush();
+    }
+    flush() {
+        if (this.config.enabled === false)
+            return;
+        if (this.flushing)
+            return;
+        if (this.logsQueue.length === 0 && this.metricsQueue.length === 0)
+            return;
+        this.flushing = true;
+        const logs = this.logsQueue;
+        const metrics = this.metricsQueue;
+        this.logsQueue = [];
+        this.metricsQueue = [];
+        const batch = {
+            ts: Date.now(),
+            logs,
+            metrics,
+        };
+        void fetch(`${this.config.url}/ingest`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-api-key": this.config.apiKey,
+                "x-ingest-key": this.config.ingestKey,
+            },
+            body: JSON.stringify(batch),
+            keepalive: true,
+        })
+            .then((res) => {
+        })
+            .catch(() => {
+            // drop on network error (do nothing)
+        })
+            .finally(() => {
+            this.flushing = false;
+            // if new items arrived while sending, kick another flush
+            if (this.logsQueue.length || this.metricsQueue.length)
+                this.flush();
+        });
+    }
+    async shutdown() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        await this.flush();
+    }
+}
+exports.TelemetryLogger = TelemetryLogger;
+TelemetryLogger.instance = null;

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";

package/dist/models/index.d.ts

@@ -0,0 +1,34 @@
+export declare const Verbosity: {
+    readonly trace: 2;
+    readonly debug: 4;
+    readonly info: 8;
+    readonly warn: 16;
+    readonly error: 32;
+    readonly fatal: 64;
+    readonly all: number;
+};
+export type Verbosity = (typeof Verbosity)[keyof typeof Verbosity];
+export type TelemetryClientConfig = {
+    url: string;
+    apiKey: string;
+    ingestKey: string;
+    enabled?: boolean;
+    flushIntervalSeconds?: number;
+};
+export type LogEvent<ProjectFields extends Record<string, unknown>> = ProjectFields & {
+    verbosity: number;
+    section: string;
+    raw: Record<string, unknown>;
+};
+export type MetricEvent<ProjectFields extends Record<string, unknown>> = ProjectFields & {
+    name: string;
+    value: number;
+    unit?: string;
+    tags?: Record<string, string>;
+};
+export type TelemetryItem<ProjectFields extends Record<string, unknown>> = LogEvent<ProjectFields> | MetricEvent<ProjectFields>;
+export type IngestBatch<ProjectFields extends Record<string, unknown>> = {
+    ts?: number;
+    logs: Array<LogEvent<ProjectFields>>;
+    metrics: Array<MetricEvent<ProjectFields>>;
+};

package/dist/models/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Verbosity = void 0;
+exports.Verbosity = {
+    trace: 2,
+    debug: 4,
+    info: 8,
+    warn: 16,
+    error: 32,
+    fatal: 64,
+    all: 2 | 4 | 8 | 16 | 32 | 64
+};

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@voidcli/logging",
+  "version": "0.1.0",
+  "description": "VoidCLI Telemetry logging client",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc -p tsconfig.json"
+  },
+  "license": "MIT"
+}