@redthreadlabs/tracelog-client 1.5.0 → 1.7.0

package/dist/LogClient.d.ts

@@ -1,18 +1,18 @@
 import { EventBuilder } from './EventBuilder';
-import { JsonValue, LogClientOptions, TimerToken } from './types';
+import { JsonValue, LogClientOptions, PerfToken } from './types';
 export declare class LogClient {
     private _opts;
     private _eventBuffer;
-    private _timerBuffer;
-    private _activeTimers;
-    private _flushTimer;
-    private _persistTimer;
+    private _perfBuffer;
+    private _activePerfs;
+    private _flushHandle;
+    private _persistHandle;
     private _disposed;
     private _flushing;
     constructor(opts: LogClientOptions);
     event(type?: string): EventBuilder;
-    startTimer(name: string, parent?: TimerToken): TimerToken;
-    endTimer(token: TimerToken, context?: Record<string, JsonValue>): void;
+    startPerf(name: string, parent?: PerfToken): PerfToken;
+    endPerf(token: PerfToken, context?: Record<string, JsonValue>): void;
     flush(): Promise<void>;
     dispose(): void;
     private _enqueueEvent;

package/dist/LogClient.js

@@ -3,8 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LogClient = void 0;
 const EventBuilder_1 = require("./EventBuilder");
 const util_1 = require("./util");
-// Default constants (matching the original AppLogRecorder)
-const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+// Level ordering for the optional getMinLevel gate. An event is dropped when
+// its level ranks below the host-supplied minimum.
+const LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+// Defaults (all overridable via LogClientOptions)
+const DEFAULT_FLUSH_CADENCE_MS = 5000;
 const DEFAULT_MAX_BUFFER_SIZE = 100;
 const DEFAULT_MAX_CHUNK_SIZE = 50;
 const DEFAULT_MAX_CHUNK_BYTES = 512 * 1024;
@@ -15,26 +18,26 @@ const PERSIST_DEBOUNCE_MS = 100;
 class LogClient {
     constructor(opts) {
         this._eventBuffer = [];
-        this._timerBuffer = [];
-        this._activeTimers = new Map();
-        this._flushTimer = null;
-        this._persistTimer = null;
+        this._perfBuffer = [];
+        this._activePerfs = new Map();
+        this._flushHandle = null;
+        this._persistHandle = null;
         this._disposed = false;
         this._flushing = false;
         this._opts = opts;
         this._loadPersistedLogs();
-        this._flushTimer = setInterval(() => this.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS);
+        this._flushHandle = setInterval(() => this.flush(), opts.flushCadenceMs ?? DEFAULT_FLUSH_CADENCE_MS);
     }
     // ---- Fluent event builder ----
     event(type = 'client-log') {
         return new EventBuilder_1.EventBuilder((evt) => this._enqueueEvent(evt), type);
     }
     // ---- Perf timing ----
-    startTimer(name, parent) {
+    startPerf(name, parent) {
         const id = randomHex(16);
         const trace_id = parent ? parent.trace_id : randomHex(32);
         const root_id = parent ? parent.root_id : id;
-        const token = { id, trace_id, root_id, key: name };
+        const token = { id, trace_id, root_id, name };
         const active = {
             token,
             startTime: now(),
@@ -42,33 +45,33 @@ class LogClient {
             parentToken: parent,
             children: [],
         };
-        this._activeTimers.set(id, active);
+        this._activePerfs.set(id, active);
         // Register as child of parent
         if (parent) {
-            const parentActive = this._activeTimers.get(parent.id);
+            const parentActive = this._activePerfs.get(parent.id);
             if (parentActive) {
                 parentActive.children.push(id);
             }
         }
         return token;
     }
-    endTimer(token, context) {
-        const active = this._activeTimers.get(token.id);
+    endPerf(token, context) {
+        const active = this._activePerfs.get(token.id);
         if (!active)
             return;
         const duration = now() - active.startTime;
         // Auto-close children that haven't been ended yet
         for (const childId of active.children) {
-            const childActive = this._activeTimers.get(childId);
+            const childActive = this._activePerfs.get(childId);
             if (childActive) {
-                this.endTimer(childActive.token);
+                this.endPerf(childActive.token);
             }
         }
-        const timer = {
+        const perf = {
             id: token.id,
             trace_id: token.trace_id,
             root_id: token.root_id,
-            name: token.key,
+            name: token.name,
             type: 'client-perf',
             timestamp: Math.round(active.startTime),
             duration: Math.round(duration),
@@ -76,16 +79,16 @@ class LogClient {
             tz_offset: active.tzOffset,
         };
         if (active.parentToken) {
-            timer.parent_id = active.parentToken.id;
+            perf.parent_id = active.parentToken.id;
         }
         if (context && Object.keys(context).length > 0) {
-            timer.context = { tags: context };
+            perf.context = { tags: context };
         }
-        this._timerBuffer.push(timer);
-        this._activeTimers.delete(token.id);
+        this._perfBuffer.push(perf);
+        this._activePerfs.delete(token.id);
         this._schedulePersist();
         // Force flush if buffer is getting large
-        if (this._timerBuffer.length + this._eventBuffer.length >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE)) {
+        if (this._perfBuffer.length + this._eventBuffer.length >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE)) {
             this.flush();
         }
     }
@@ -93,13 +96,13 @@ class LogClient {
     async flush() {
         if (this._disposed || this._flushing)
             return;
-        if (this._eventBuffer.length === 0 && this._timerBuffer.length === 0)
+        if (this._eventBuffer.length === 0 && this._perfBuffer.length === 0)
             return;
         this._flushing = true;
         try {
             const events = this._eventBuffer.splice(0);
-            const timers = this._timerBuffer.splice(0);
-            await this._sendInChunks(events, timers);
+            const perfs = this._perfBuffer.splice(0);
+            await this._sendInChunks(events, perfs);
         }
         finally {
             this._flushing = false;
@@ -110,13 +113,13 @@ class LogClient {
         if (this._disposed)
             return;
         this._disposed = true;
-        if (this._flushTimer) {
-            clearInterval(this._flushTimer);
-            this._flushTimer = null;
+        if (this._flushHandle) {
+            clearInterval(this._flushHandle);
+            this._flushHandle = null;
         }
-        if (this._persistTimer) {
-            clearTimeout(this._persistTimer);
-            this._persistTimer = null;
+        if (this._persistHandle) {
+            clearTimeout(this._persistHandle);
+            this._persistHandle = null;
         }
         // Persist anything remaining
         this._persistNow();
@@ -125,6 +128,11 @@ class LogClient {
     _enqueueEvent(event) {
         if (this._disposed)
             return;
+        // Level gate: drop events below the host-supplied minimum before they ever
+        // buffer, persist, or ship. No callback ⇒ emit everything (back-compat).
+        const minLevel = this._opts.getMinLevel?.();
+        if (minLevel && LEVEL_RANK[event.level] < LEVEL_RANK[minLevel])
+            return;
         this._eventBuffer.push(event);
         this._schedulePersist();
         if (this._eventBuffer.length >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE)) {
@@ -132,23 +140,23 @@ class LogClient {
         }
     }
     // ---- Internal: chunked sending ----
-    async _sendInChunks(events, timers) {
+    async _sendInChunks(events, perfs) {
         const maxChunkSize = this._opts.maxChunkSize ?? DEFAULT_MAX_CHUNK_SIZE;
         const maxChunkBytes = this._opts.maxChunkBytes ?? DEFAULT_MAX_CHUNK_BYTES;
-        // Combine events and timers into chunks that respect size limits
+        // Combine events and perfs into chunks that respect size limits
         let eventIdx = 0;
-        let timerIdx = 0;
+        let perfIdx = 0;
         let isFirstChunk = true;
-        while (eventIdx < events.length || timerIdx < timers.length) {
+        while (eventIdx < events.length || perfIdx < perfs.length) {
             if (!isFirstChunk) {
                 await delay(INTER_CHUNK_DELAY_MS);
             }
             isFirstChunk = false;
             const chunkEvents = [];
-            const chunkTimers = [];
+            const chunkPerfs = [];
             let estimatedBytes = 200; // base overhead for batch envelope
             // Fill chunk with events
-            while (eventIdx < events.length && chunkEvents.length + chunkTimers.length < maxChunkSize) {
+            while (eventIdx < events.length && chunkEvents.length + chunkPerfs.length < maxChunkSize) {
                 const itemBytes = estimateJsonSize(events[eventIdx]);
                 if (estimatedBytes + itemBytes > maxChunkBytes && chunkEvents.length > 0)
                     break;
@@ -156,24 +164,24 @@ class LogClient {
                 estimatedBytes += itemBytes;
                 eventIdx++;
             }
-            // Fill chunk with timers
-            while (timerIdx < timers.length && chunkEvents.length + chunkTimers.length < maxChunkSize) {
-                const itemBytes = estimateJsonSize(timers[timerIdx]);
-                if (estimatedBytes + itemBytes > maxChunkBytes && (chunkEvents.length + chunkTimers.length) > 0)
+            // Fill chunk with perfs
+            while (perfIdx < perfs.length && chunkEvents.length + chunkPerfs.length < maxChunkSize) {
+                const itemBytes = estimateJsonSize(perfs[perfIdx]);
+                if (estimatedBytes + itemBytes > maxChunkBytes && (chunkEvents.length + chunkPerfs.length) > 0)
                     break;
-                chunkTimers.push(timers[timerIdx]);
+                chunkPerfs.push(perfs[perfIdx]);
                 estimatedBytes += itemBytes;
-                timerIdx++;
+                perfIdx++;
             }
-            if (chunkEvents.length === 0 && chunkTimers.length === 0)
+            if (chunkEvents.length === 0 && chunkPerfs.length === 0)
                 break;
-            await this._sendChunkWithRetry(chunkEvents, chunkTimers);
+            await this._sendChunkWithRetry(chunkEvents, chunkPerfs);
         }
     }
-    async _sendChunkWithRetry(events, timers) {
+    async _sendChunkWithRetry(events, perfs) {
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
             try {
-                await this._sendChunk(events, timers);
+                await this._sendChunk(events, perfs);
                 return;
             }
             catch (err) {
@@ -183,17 +191,17 @@ class LogClient {
                 else {
                     // Max retries exceeded — put items back for persistence
                     this._eventBuffer.push(...events);
-                    this._timerBuffer.push(...timers);
+                    this._perfBuffer.push(...perfs);
                     this._schedulePersist();
                 }
             }
         }
     }
-    async _sendChunk(events, timers) {
+    async _sendChunk(events, perfs) {
         const batch = {
             client: this._opts.client,
             events,
-            timers,
+            perfs,
         };
         const userId = this._opts.getUserId?.();
         const sessionRef = this._opts.getSessionRef?.();
@@ -219,23 +227,23 @@ class LogClient {
     }
     // ---- Internal: persistence ----
     _schedulePersist() {
-        if (this._persistTimer || !this._opts.persistLogs)
+        if (this._persistHandle || !this._opts.persistLogs)
             return;
-        this._persistTimer = setTimeout(() => {
-            this._persistTimer = null;
+        this._persistHandle = setTimeout(() => {
+            this._persistHandle = null;
             this._persistNow();
         }, PERSIST_DEBOUNCE_MS);
     }
     _persistNow() {
         if (!this._opts.persistLogs)
             return;
-        if (this._eventBuffer.length === 0 && this._timerBuffer.length === 0) {
+        if (this._eventBuffer.length === 0 && this._perfBuffer.length === 0) {
             this._opts.persistLogs('').catch(() => { });
             return;
         }
         const data = JSON.stringify({
             events: this._eventBuffer,
-            timers: this._timerBuffer,
+            perfs: this._perfBuffer,
         });
         this._opts.persistLogs(data).catch(() => { });
     }
@@ -250,8 +258,8 @@ class LogClient {
             if (Array.isArray(parsed.events)) {
                 this._eventBuffer.push(...parsed.events);
             }
-            if (Array.isArray(parsed.timers)) {
-                this._timerBuffer.push(...parsed.timers);
+            if (Array.isArray(parsed.perfs)) {
+                this._perfBuffer.push(...parsed.perfs);
             }
             // Clear persisted data now that it's loaded
             this._opts.persistLogs?.('').catch(() => { });

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { LogClient } from './LogClient';
 export { EventBuilder } from './EventBuilder';
-export { LogBatch, LogEventItem, TimerItem, ClientInfo, TimerToken, LogClientOptions, LogLevel, JsonValue, } from './types';
+export { LogBatch, LogEventItem, LogPerfItem, ClientInfo, PerfToken, LogClientOptions, LogLevel, JsonValue, } from './types';

package/dist/types.d.ts

@@ -1,14 +1,14 @@
-import type { ClientInfo } from '@redthreadlabs/tracelog-schema';
-export type { JsonValue, LogLevel, LogBatch, LogEventItem, TimerItem, ClientInfo, } from '@redthreadlabs/tracelog-schema';
-export interface TimerToken {
-    /** 16-char hex ID for this timer */
+import type { ClientInfo, LogLevel } from '@redthreadlabs/tracelog-schema';
+export type { JsonValue, LogLevel, LogBatch, LogEventItem, LogPerfItem, ClientInfo, } from '@redthreadlabs/tracelog-schema';
+export interface PerfToken {
+    /** 16-char hex ID for this perf */
     id: string;
-    /** 32-char hex trace ID (shared across the entire timer tree) */
+    /** 32-char hex trace ID (shared across the entire perf tree) */
     trace_id: string;
-    /** ID of the root timer in this trace */
+    /** ID of the root perf in this trace */
     root_id: string;
-    /** Key/name of the operation being timed */
-    key: string;
+    /** Name of the operation being measured */
+    name: string;
 }
 export interface LogClientOptions {
     /** Server endpoint URL for log submission */
@@ -23,8 +23,15 @@ export interface LogClientOptions {
     getSessionRef?: () => string | undefined;
     /** Returns native device identifier */
     getDeviceId?: () => string | undefined;
-    /** Flush interval in ms. Default: 5000 */
-    flushIntervalMs?: number;
+    /**
+     * Returns the minimum level to emit. Events whose level ranks below this
+     * (debug < info < warn < error) are dropped before buffering — they never
+     * persist or ship. Called once per event, so keep it cheap and synchronous.
+     * Omit to emit every level (default). Perfs are unaffected.
+     */
+    getMinLevel?: () => LogLevel;
+    /** Flush cadence in ms. Default: 5000 */
+    flushCadenceMs?: number;
     /** Max events buffered before forced flush. Default: 100 */
     maxBufferSize?: number;
     /** Max events per HTTP request. Default: 50 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redthreadlabs/tracelog-client",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Lightweight logging client for tracelog — works in React Native and browsers",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -21,6 +21,6 @@
     "typescript": "latest"
   },
   "dependencies": {
-    "@redthreadlabs/tracelog-schema": "^0.1.0"
+    "@redthreadlabs/tracelog-schema": "^0.3.0"
   }
 }