npm - @redthreadlabs/tracelog-client - Versions diffs - 1.8.0 → 2.1.0 - Mend

@redthreadlabs/tracelog-client 1.8.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/EventBuilder.d.ts CHANGED Viewed

@@ -1,21 +1,19 @@
-import { JsonValue, LogEventItem } from './types';
-export type EventEnqueuer = (event: LogEventItem) => void;
+import { JsonValue, EventRecord } from './types';
+export type EventEnqueuer = (event: EventRecord) => void;
 export declare class EventBuilder {
     private _enqueue;
     private _type;
     private _level;
     private _message;
-    private _duration?;
     private _error?;
-    private _params?;
+    private _labels?;
     constructor(enqueue: EventEnqueuer, type: string);
     info(message: string): this;
     warn(message: string): this;
     error(message: string): this;
     debug(message: string): this;
-    withParam(key: string, value: JsonValue): this;
-    withParams(params: Record<string, JsonValue>): this;
+    withLabel(key: string, value: JsonValue): this;
+    withLabels(labels: Record<string, JsonValue>): this;
     withError(err: any): this;
-    withDuration(ms: number): this;
     send(): void;
 }

package/dist/EventBuilder.js CHANGED Viewed

@@ -29,16 +29,16 @@ class EventBuilder {
         this._message = message;
         return this;
     }
-    withParam(key, value) {
-        if (!this._params)
-            this._params = {};
-        this._params[key] = value;
+    withLabel(key, value) {
+        if (!this._labels)
+            this._labels = {};
+        this._labels[key] = value;
         return this;
     }
-    withParams(params) {
-        if (!this._params)
-            this._params = {};
-        Object.assign(this._params, params);
+    withLabels(labels) {
+        if (!this._labels)
+            this._labels = {};
+        Object.assign(this._labels, labels);
         return this;
     }
     withError(err) {
@@ -73,31 +73,24 @@ class EventBuilder {
         }
         return this;
     }
-    withDuration(ms) {
-        this._duration = ms;
-        return this;
-    }
     send() {
         const event = {
             type: this._type,
-            timestamp: Date.now(),
+            timestamp: Date.now() * 1000, // epoch microseconds (the on-disk unit)
             level: this._level,
             message: this._message,
             tz_offset: (0, util_1.tzOffsetMinutes)(),
         };
-        if (this._duration !== undefined)
-            event.duration = this._duration;
         if (this._error)
             event.error = this._error;
-        if (this._params)
-            event.params = this._params;
+        if (this._labels)
+            event.context = { labels: this._labels };
         this._enqueue(event);
     }
 }
 exports.EventBuilder = EventBuilder;
 // Stringify an error code (ShareDB and Node errors carry one) for the
-// structured `error.code` field. Until 1.4.0 the code was appended to the
-// message text; a dedicated field is facetable downstream.
+// structured `error.code` field — a dedicated field is facetable downstream.
 function extractCode(code) {
     if (typeof code === 'string' || typeof code === 'number') {
         return String(code);

package/dist/LogClient.d.ts CHANGED Viewed

@@ -1,28 +1,43 @@
 import { EventBuilder } from './EventBuilder';
-import { JsonValue, LogClientOptions, PerfToken } from './types';
+import { EndOptions, LogClientOptions, RecordOptions, StartOptions } from './types';
 export declare class LogClient {
     private _opts;
     private _eventBuffer;
-    private _perfBuffer;
-    private _activePerfs;
+    private _transactionBuffer;
+    private _spanBuffer;
+    private _activeSpans;
+    /** Per-launch id; the join key between records and this lifetime's origin. */
+    private readonly _lifetimeId;
+    /** JSON of the last origin sent, to detect changes (null ⇒ not yet sent). */
+    private _lastOriginJson;
     private _flushHandle;
     private _persistHandle;
     private _disposed;
     private _flushing;
     constructor(opts: LogClientOptions);
+    /** This LogClient's lifetime id (one per launch / process run). */
+    get lifetimeId(): string;
     event(type?: string): EventBuilder;
-    startPerf(name: string, parent?: PerfToken): PerfToken;
-    endPerf(token: PerfToken, context?: Record<string, JsonValue>): void;
-    /**
-     * Record a complete perf measurement in one call — for operations timed
-     * elsewhere (a pre-measured duration with no live start/end pair). Buffers a
-     * parent-less, root perf, which the server maps to a `transaction` record.
-     * Reach for startPerf/endPerf instead when you need a live span tree.
-     */
-    recordPerf(name: string, durationMs: number, context?: Record<string, JsonValue>, outcome?: 'success' | 'failure' | 'unknown'): void;
+    /** Start a root timed operation (a trace root). Recorded as a transaction. */
+    startTransaction(name: string, opts?: StartOptions): Transaction;
+    /** Start a sub-operation under a transaction or span. Recorded as a span. */
+    startSpan(name: string, parent: Transaction | Span, opts?: StartOptions): Span;
+    /** Internal: end a live transaction/span by id (called by the handles). */
+    _end(id: string, opts?: EndOptions): void;
+    /** Record a complete root operation timed elsewhere → a transaction. */
+    recordTransaction(name: string, durationMs: number, opts?: RecordOptions): void;
+    /** Record a complete sub-operation timed elsewhere → a span under `parent`. */
+    recordSpan(name: string, durationMs: number, parent: Transaction | Span, opts?: RecordOptions): void;
+    private _belowThreshold;
+    private _buildOneShot;
     flush(): Promise<void>;
     dispose(): void;
     private _enqueueEvent;
+    private _enqueueTransaction;
+    private _enqueueSpan;
+    private _afterEnqueue;
+    /** The origin to attach to this flush, or undefined if unchanged since last sent. */
+    private _takeOriginIfChanged;
     private _sendInChunks;
     private _sendChunkWithRetry;
     private _sendChunk;
@@ -30,3 +45,27 @@ export declare class LogClient {
     private _persistNow;
     private _loadPersistedLogs;
 }
+/** A live root operation. Recorded as a `transaction` when ended. */
+export declare class Transaction {
+    private readonly _client;
+    readonly id: string;
+    readonly traceId: string;
+    readonly type: string;
+    constructor(_client: LogClient, id: string, traceId: string, type: string);
+    /** A transaction is its own trace root. */
+    get transactionId(): string;
+    startSpan(name: string, opts?: StartOptions): Span;
+    end(opts?: EndOptions): void;
+}
+/** A live sub-operation. Recorded as a `span` when ended. */
+export declare class Span {
+    private readonly _client;
+    readonly id: string;
+    readonly traceId: string;
+    readonly transactionId: string;
+    readonly parentId: string;
+    readonly type: string;
+    constructor(_client: LogClient, id: string, traceId: string, transactionId: string, parentId: string, type: string);
+    startSpan(name: string, opts?: StartOptions): Span;
+    end(opts?: EndOptions): void;
+}

package/dist/LogClient.js CHANGED Viewed

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogClient = void 0;
+exports.Span = exports.Transaction = exports.LogClient = void 0;
 const EventBuilder_1 = require("./EventBuilder");
 const util_1 = require("./util");
 // 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 };
+const DEFAULT_TYPE = 'app';
 // Defaults (all overridable via LogClientOptions)
 const DEFAULT_FLUSH_CADENCE_MS = 5000;
 const DEFAULT_MAX_BUFFER_SIZE = 100;
@@ -18,8 +19,13 @@ const PERSIST_DEBOUNCE_MS = 100;
 class LogClient {
     constructor(opts) {
         this._eventBuffer = [];
-        this._perfBuffer = [];
-        this._activePerfs = new Map();
+        this._transactionBuffer = [];
+        this._spanBuffer = [];
+        this._activeSpans = new Map();
+        /** Per-launch id; the join key between records and this lifetime's origin. */
+        this._lifetimeId = randomHex(16);
+        /** JSON of the last origin sent, to detect changes (null ⇒ not yet sent). */
+        this._lastOriginJson = null;
         this._flushHandle = null;
         this._persistHandle = null;
         this._disposed = false;
@@ -28,115 +34,120 @@ class LogClient {
         this._loadPersistedLogs();
         this._flushHandle = setInterval(() => this.flush(), opts.flushCadenceMs ?? DEFAULT_FLUSH_CADENCE_MS);
     }
+    /** This LogClient's lifetime id (one per launch / process run). */
+    get lifetimeId() {
+        return this._lifetimeId;
+    }
     // ---- Fluent event builder ----
     event(type = 'client-log') {
         return new EventBuilder_1.EventBuilder((evt) => this._enqueueEvent(evt), type);
     }
-    // ---- Perf timing ----
-    startPerf(name, parent) {
+    // ---- Live traces: transactions & spans ----
+    /** Start a root timed operation (a trace root). Recorded as a transaction. */
+    startTransaction(name, opts) {
         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, name };
-        const active = {
-            token,
-            startTime: now(),
-            tzOffset: (0, util_1.tzOffsetMinutes)(),
-            parentToken: parent,
-            children: [],
-        };
-        this._activePerfs.set(id, active);
-        // Register as child of parent
-        if (parent) {
-            const parentActive = this._activePerfs.get(parent.id);
-            if (parentActive) {
-                parentActive.children.push(id);
-            }
-        }
-        return token;
+        const trace_id = randomHex(32);
+        const type = opts?.type ?? DEFAULT_TYPE;
+        this._activeSpans.set(id, {
+            kind: 'transaction', id, trace_id, name, type,
+            startTime: now(), tzOffset: (0, util_1.tzOffsetMinutes)(), children: [],
+        });
+        return new Transaction(this, id, trace_id, type);
+    }
+    /** Start a sub-operation under a transaction or span. Recorded as a span. */
+    startSpan(name, parent, opts) {
+        const id = randomHex(16);
+        const type = opts?.type ?? DEFAULT_TYPE;
+        this._activeSpans.set(id, {
+            kind: 'span', id,
+            trace_id: parent.traceId,
+            transaction_id: parent.transactionId,
+            parent_id: parent.id,
+            name, type,
+            startTime: now(), tzOffset: (0, util_1.tzOffsetMinutes)(), children: [],
+        });
+        this._activeSpans.get(parent.id)?.children.push(id);
+        return new Span(this, id, parent.traceId, parent.transactionId, parent.id, type);
     }
-    endPerf(token, context) {
-        const active = this._activePerfs.get(token.id);
+    /** Internal: end a live transaction/span by id (called by the handles). */
+    _end(id, opts) {
+        const active = this._activeSpans.get(id);
         if (!active)
             return;
-        const duration = now() - active.startTime;
-        // Auto-close children that haven't been ended yet
+        // Auto-close any children not yet ended, so a forgotten child can't leak.
         for (const childId of active.children) {
-            const childActive = this._activePerfs.get(childId);
-            if (childActive) {
-                this.endPerf(childActive.token);
-            }
+            if (this._activeSpans.has(childId))
+                this._end(childId);
         }
-        const perf = {
-            id: token.id,
-            trace_id: token.trace_id,
-            root_id: token.root_id,
-            name: token.name,
-            type: 'client-perf',
-            timestamp: Math.round(active.startTime),
+        const duration = Math.max(0, now() - active.startTime);
+        const base = {
+            id: active.id,
+            trace_id: active.trace_id,
+            name: active.name,
+            type: active.type,
+            timestamp: Math.round(active.startTime * 1000), // ms → µs
             duration: Math.round(duration),
-            outcome: 'success',
+            outcome: opts?.outcome ?? 'success',
             tz_offset: active.tzOffset,
+            ...(opts?.labels && Object.keys(opts.labels).length > 0 ? { context: { labels: opts.labels } } : {}),
         };
-        if (active.parentToken) {
-            perf.parent_id = active.parentToken.id;
+        this._activeSpans.delete(id);
+        if (active.kind === 'transaction') {
+            this._enqueueTransaction(base);
         }
-        if (context && Object.keys(context).length > 0) {
-            perf.context = { tags: context };
-        }
-        this._perfBuffer.push(perf);
-        this._activePerfs.delete(token.id);
-        this._schedulePersist();
-        // Force flush if buffer is getting large
-        if (this._perfBuffer.length + this._eventBuffer.length >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE)) {
-            this.flush();
+        else {
+            this._enqueueSpan({ ...base, transaction_id: active.transaction_id, parent_id: active.parent_id });
         }
     }
-    /**
-     * Record a complete perf measurement in one call — for operations timed
-     * elsewhere (a pre-measured duration with no live start/end pair). Buffers a
-     * parent-less, root perf, which the server maps to a `transaction` record.
-     * Reach for startPerf/endPerf instead when you need a live span tree.
-     */
-    recordPerf(name, durationMs, context, outcome = 'success') {
-        if (this._disposed)
+    // ---- One-shot (pre-measured) traces ----
+    /** Record a complete root operation timed elsewhere → a transaction. */
+    recordTransaction(name, durationMs, opts) {
+        if (this._disposed || this._belowThreshold(durationMs, opts))
+            return;
+        const id = randomHex(16);
+        this._enqueueTransaction(this._buildOneShot(id, randomHex(32), name, durationMs, opts));
+    }
+    /** Record a complete sub-operation timed elsewhere → a span under `parent`. */
+    recordSpan(name, durationMs, parent, opts) {
+        if (this._disposed || this._belowThreshold(durationMs, opts))
             return;
-        if (!isFinite(durationMs) || durationMs < 0)
-            durationMs = 0;
         const id = randomHex(16);
-        const end = now();
-        const perf = {
-            id,
-            trace_id: randomHex(32),
-            root_id: id,
-            name,
-            type: 'client-perf',
-            // No live start time, so back-compute it from the measured duration.
-            timestamp: Math.round(end - durationMs),
-            duration: Math.round(durationMs),
-            outcome,
+        const rec = this._buildOneShot(id, parent.traceId, name, durationMs, opts);
+        rec.transaction_id = parent.transactionId;
+        rec.parent_id = parent.id;
+        this._enqueueSpan(rec);
+    }
+    _belowThreshold(durationMs, opts) {
+        return opts?.minDurationMs !== undefined && durationMs < opts.minDurationMs;
+    }
+    _buildOneShot(id, trace_id, name, durationMs, opts) {
+        const d = isFinite(durationMs) && durationMs > 0 ? durationMs : 0;
+        const rec = {
+            id, trace_id, name,
+            type: opts?.type ?? DEFAULT_TYPE,
+            // No live start, so back-compute it from the measured duration.
+            timestamp: Math.round((now() - d) * 1000), // ms → µs
+            duration: Math.round(d),
+            outcome: opts?.outcome ?? 'success',
             tz_offset: (0, util_1.tzOffsetMinutes)(),
         };
-        if (context && Object.keys(context).length > 0) {
-            perf.context = { tags: context };
-        }
-        this._perfBuffer.push(perf);
-        this._schedulePersist();
-        if (this._perfBuffer.length + this._eventBuffer.length >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE)) {
-            this.flush();
-        }
+        if (opts?.labels && Object.keys(opts.labels).length > 0)
+            rec.context = { labels: opts.labels };
+        return rec;
     }
     // ---- Transport ----
     async flush() {
         if (this._disposed || this._flushing)
             return;
-        if (this._eventBuffer.length === 0 && this._perfBuffer.length === 0)
+        if (this._eventBuffer.length === 0 && this._transactionBuffer.length === 0 && this._spanBuffer.length === 0)
             return;
         this._flushing = true;
         try {
             const events = this._eventBuffer.splice(0);
-            const perfs = this._perfBuffer.splice(0);
-            await this._sendInChunks(events, perfs);
+            const transactions = this._transactionBuffer.splice(0);
+            const spans = this._spanBuffer.splice(0);
+            const origin = this._takeOriginIfChanged();
+            await this._sendInChunks(events, transactions, spans, origin);
         }
         finally {
             this._flushing = false;
@@ -155,109 +166,138 @@ class LogClient {
             clearTimeout(this._persistHandle);
             this._persistHandle = null;
         }
-        // Persist anything remaining
         this._persistNow();
     }
-    // ---- Internal: event buffering ----
+    // ---- Internal: buffering ----
     _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).
+        // Level gate: drop events below the host-supplied minimum before buffering.
         const minLevel = this._opts.getMinLevel?.();
         if (minLevel && LEVEL_RANK[event.level] < LEVEL_RANK[minLevel])
             return;
+        if (event.locale === undefined) {
+            const locale = this._opts.getLocale?.();
+            if (locale)
+                event.locale = locale;
+        }
         this._eventBuffer.push(event);
+        this._afterEnqueue();
+    }
+    _enqueueTransaction(rec) {
+        if (this._disposed)
+            return;
+        this._transactionBuffer.push(rec);
+        this._afterEnqueue();
+    }
+    _enqueueSpan(rec) {
+        if (this._disposed)
+            return;
+        this._spanBuffer.push(rec);
+        this._afterEnqueue();
+    }
+    _afterEnqueue() {
         this._schedulePersist();
-        if (this._eventBuffer.length >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE)) {
+        const total = this._eventBuffer.length + this._transactionBuffer.length + this._spanBuffer.length;
+        if (total >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE))
             this.flush();
+    }
+    /** The origin to attach to this flush, or undefined if unchanged since last sent. */
+    _takeOriginIfChanged() {
+        let origin;
+        try {
+            origin = this._opts.getOrigin();
+        }
+        catch {
+            return undefined;
         }
+        const oj = JSON.stringify(origin);
+        if (oj === this._lastOriginJson)
+            return undefined;
+        this._lastOriginJson = oj;
+        return { ...origin, lifetime_id: this._lifetimeId };
     }
     // ---- Internal: chunked sending ----
-    async _sendInChunks(events, perfs) {
+    async _sendInChunks(events, transactions, spans, origin) {
         const maxChunkSize = this._opts.maxChunkSize ?? DEFAULT_MAX_CHUNK_SIZE;
         const maxChunkBytes = this._opts.maxChunkBytes ?? DEFAULT_MAX_CHUNK_BYTES;
-        // Combine events and perfs into chunks that respect size limits
-        let eventIdx = 0;
-        let perfIdx = 0;
-        let isFirstChunk = true;
-        while (eventIdx < events.length || perfIdx < perfs.length) {
-            if (!isFirstChunk) {
+        const work = [
+            ...events.map((rec) => ({ k: 'e', rec })),
+            ...transactions.map((rec) => ({ k: 't', rec })),
+            ...spans.map((rec) => ({ k: 's', rec })),
+        ];
+        let i = 0;
+        let isFirst = true;
+        while (i < work.length || (isFirst && origin)) {
+            if (!isFirst)
                 await delay(INTER_CHUNK_DELAY_MS);
-            }
-            isFirstChunk = false;
-            const chunkEvents = [];
-            const chunkPerfs = [];
-            let estimatedBytes = 200; // base overhead for batch envelope
-            // Fill chunk with events
-            while (eventIdx < events.length && chunkEvents.length + chunkPerfs.length < maxChunkSize) {
-                const itemBytes = estimateJsonSize(events[eventIdx]);
-                if (estimatedBytes + itemBytes > maxChunkBytes && chunkEvents.length > 0)
-                    break;
-                chunkEvents.push(events[eventIdx]);
-                estimatedBytes += itemBytes;
-                eventIdx++;
-            }
-            // 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)
+            const ce = [];
+            const ct = [];
+            const cs = [];
+            let bytes = 200; // base overhead for the batch envelope
+            while (i < work.length && (ce.length + ct.length + cs.length) < maxChunkSize) {
+                const item = work[i];
+                const itemBytes = estimateJsonSize(item.rec);
+                if (bytes + itemBytes > maxChunkBytes && (ce.length + ct.length + cs.length) > 0)
                     break;
-                chunkPerfs.push(perfs[perfIdx]);
-                estimatedBytes += itemBytes;
-                perfIdx++;
+                if (item.k === 'e')
+                    ce.push(item.rec);
+                else if (item.k === 't')
+                    ct.push(item.rec);
+                else
+                    cs.push(item.rec);
+                bytes += itemBytes;
+                i++;
             }
-            if (chunkEvents.length === 0 && chunkPerfs.length === 0)
+            const chunkOrigin = isFirst ? origin : undefined;
+            isFirst = false;
+            if (ce.length === 0 && ct.length === 0 && cs.length === 0 && !chunkOrigin)
                 break;
-            await this._sendChunkWithRetry(chunkEvents, chunkPerfs);
+            await this._sendChunkWithRetry(ce, ct, cs, chunkOrigin);
         }
     }
-    async _sendChunkWithRetry(events, perfs) {
+    async _sendChunkWithRetry(events, transactions, spans, origin) {
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
             try {
-                await this._sendChunk(events, perfs);
+                await this._sendChunk(events, transactions, spans, origin);
                 return;
             }
-            catch (err) {
+            catch {
                 if (attempt < MAX_RETRIES) {
                     await delay(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
                 }
                 else {
-                    // Max retries exceeded — put items back for persistence
+                    // Max retries exceeded — put records back for persistence/retry, and
+                    // re-arm the origin so it ships again on the next successful flush.
                     this._eventBuffer.push(...events);
-                    this._perfBuffer.push(...perfs);
+                    this._transactionBuffer.push(...transactions);
+                    this._spanBuffer.push(...spans);
+                    if (origin)
+                        this._lastOriginJson = null;
                     this._schedulePersist();
                 }
             }
         }
     }
-    async _sendChunk(events, perfs) {
-        const batch = {
-            client: this._opts.client,
-            events,
-            perfs,
-        };
+    async _sendChunk(events, transactions, spans, origin) {
+        const batch = { events, transactions, spans };
+        batch.lifetime_id = this._lifetimeId;
         const userId = this._opts.getUserId?.();
-        const sessionRef = this._opts.getSessionRef?.();
         const deviceId = this._opts.getDeviceId?.();
         if (userId)
             batch.user_id = userId;
-        if (sessionRef)
-            batch.session_ref = sessionRef;
         if (deviceId)
             batch.device_id = deviceId;
+        if (origin)
+            batch.origin = origin;
         const headers = await Promise.resolve(this._opts.getAuthHeaders());
         const response = await fetch(this._opts.endpoint, {
             method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                ...headers,
-            },
+            headers: { 'Content-Type': 'application/json', ...headers },
             body: JSON.stringify(batch),
         });
-        if (!response.ok) {
+        if (!response.ok)
             throw new Error(`Server returned ${response.status}`);
-        }
     }
     // ---- Internal: persistence ----
     _schedulePersist() {
@@ -271,13 +311,14 @@ class LogClient {
     _persistNow() {
         if (!this._opts.persistLogs)
             return;
-        if (this._eventBuffer.length === 0 && this._perfBuffer.length === 0) {
+        if (this._eventBuffer.length === 0 && this._transactionBuffer.length === 0 && this._spanBuffer.length === 0) {
             this._opts.persistLogs('').catch(() => { });
             return;
         }
         const data = JSON.stringify({
             events: this._eventBuffer,
-            perfs: this._perfBuffer,
+            transactions: this._transactionBuffer,
+            spans: this._spanBuffer,
         });
         this._opts.persistLogs(data).catch(() => { });
     }
@@ -289,13 +330,12 @@ class LogClient {
             if (!data)
                 return;
             const parsed = JSON.parse(data);
-            if (Array.isArray(parsed.events)) {
+            if (Array.isArray(parsed.events))
                 this._eventBuffer.push(...parsed.events);
-            }
-            if (Array.isArray(parsed.perfs)) {
-                this._perfBuffer.push(...parsed.perfs);
-            }
-            // Clear persisted data now that it's loaded
+            if (Array.isArray(parsed.transactions))
+                this._transactionBuffer.push(...parsed.transactions);
+            if (Array.isArray(parsed.spans))
+                this._spanBuffer.push(...parsed.spans);
             this._opts.persistLogs?.('').catch(() => { });
         }
         catch {
@@ -304,6 +344,35 @@ class LogClient {
     }
 }
 exports.LogClient = LogClient;
+// ---- Trace handles ----
+/** A live root operation. Recorded as a `transaction` when ended. */
+class Transaction {
+    constructor(_client, id, traceId, type) {
+        this._client = _client;
+        this.id = id;
+        this.traceId = traceId;
+        this.type = type;
+    }
+    /** A transaction is its own trace root. */
+    get transactionId() { return this.id; }
+    startSpan(name, opts) { return this._client.startSpan(name, this, opts); }
+    end(opts) { this._client._end(this.id, opts); }
+}
+exports.Transaction = Transaction;
+/** A live sub-operation. Recorded as a `span` when ended. */
+class Span {
+    constructor(_client, id, traceId, transactionId, parentId, type) {
+        this._client = _client;
+        this.id = id;
+        this.traceId = traceId;
+        this.transactionId = transactionId;
+        this.parentId = parentId;
+        this.type = type;
+    }
+    startSpan(name, opts) { return this._client.startSpan(name, this, opts); }
+    end(opts) { this._client._end(this.id, opts); }
+}
+exports.Span = Span;
 // ---- Helpers ----
 function randomHex(length) {
     const chars = '0123456789abcdef';
@@ -315,8 +384,6 @@ function randomHex(length) {
 }
 function now() {
     if (typeof performance !== 'undefined' && performance.now) {
-        // Use performance.now() for high-res timing, but we need wall-clock for timestamps
-        // Store the offset on first call
         if (!now._offset) {
             now._offset = Date.now() - performance.now();
         }
@@ -328,6 +395,5 @@ function delay(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 function estimateJsonSize(obj) {
-    // Fast estimate — avoid full serialization during chunking
     return JSON.stringify(obj).length;
 }

package/dist/TraceLogClient.d.ts ADDED Viewed

@@ -0,0 +1,71 @@
+import { EventBuilder } from './EventBuilder';
+import { EndOptions, LogClientOptions, RecordOptions, StartOptions } from './types';
+export declare class TracelogClient {
+    private _opts;
+    private _eventBuffer;
+    private _transactionBuffer;
+    private _spanBuffer;
+    private _activeSpans;
+    /** Per-launch id; the join key between records and this lifetime's origin. */
+    private readonly _lifetimeId;
+    /** JSON of the last origin sent, to detect changes (null ⇒ not yet sent). */
+    private _lastOriginJson;
+    private _flushHandle;
+    private _persistHandle;
+    private _disposed;
+    private _flushing;
+    constructor(opts: LogClientOptions);
+    /** This TracelogClient's lifetime id (one per launch / process run). */
+    get lifetimeId(): string;
+    event(type?: string): EventBuilder;
+    /** Start a root timed operation (a trace root). Recorded as a transaction. */
+    startTransaction(name: string, opts?: StartOptions): Transaction;
+    /** Start a sub-operation under a transaction or span. Recorded as a span. */
+    startSpan(name: string, parent: Transaction | Span, opts?: StartOptions): Span;
+    /** Internal: end a live transaction/span by id (called by the handles). */
+    _end(id: string, opts?: EndOptions): void;
+    /** Record a complete root operation timed elsewhere → a transaction. */
+    recordTransaction(name: string, durationMs: number, opts?: RecordOptions): void;
+    /** Record a complete sub-operation timed elsewhere → a span under `parent`. */
+    recordSpan(name: string, durationMs: number, parent: Transaction | Span, opts?: RecordOptions): void;
+    private _belowThreshold;
+    private _buildOneShot;
+    flush(): Promise<void>;
+    dispose(): void;
+    private _enqueueEvent;
+    private _enqueueTransaction;
+    private _enqueueSpan;
+    private _afterEnqueue;
+    /** The origin to attach to this flush, or undefined if unchanged since last sent. */
+    private _takeOriginIfChanged;
+    private _sendInChunks;
+    private _sendChunkWithRetry;
+    private _sendChunk;
+    private _schedulePersist;
+    private _persistNow;
+    private _loadPersistedLogs;
+}
+/** A live root operation. Recorded as a `transaction` when ended. */
+export declare class Transaction {
+    private readonly _client;
+    readonly id: string;
+    readonly traceId: string;
+    readonly type: string;
+    constructor(_client: TracelogClient, id: string, traceId: string, type: string);
+    /** A transaction is its own trace root. */
+    get transactionId(): string;
+    startSpan(name: string, opts?: StartOptions): Span;
+    end(opts?: EndOptions): void;
+}
+/** A live sub-operation. Recorded as a `span` when ended. */
+export declare class Span {
+    private readonly _client;
+    readonly id: string;
+    readonly traceId: string;
+    readonly transactionId: string;
+    readonly parentId: string;
+    readonly type: string;
+    constructor(_client: TracelogClient, id: string, traceId: string, transactionId: string, parentId: string, type: string);
+    startSpan(name: string, opts?: StartOptions): Span;
+    end(opts?: EndOptions): void;
+}

package/dist/TraceLogClient.js ADDED Viewed

@@ -0,0 +1,396 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Span = exports.Transaction = exports.TracelogClient = void 0;
+const EventBuilder_1 = require("./EventBuilder");
+const util_1 = require("./util");
+// 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 };
+const DEFAULT_TYPE = 'app';
+// 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;
+const INTER_CHUNK_DELAY_MS = 200;
+const MAX_RETRIES = 3;
+const BASE_RETRY_DELAY_MS = 1000;
+const PERSIST_DEBOUNCE_MS = 100;
+class TracelogClient {
+    constructor(opts) {
+        this._eventBuffer = [];
+        this._transactionBuffer = [];
+        this._spanBuffer = [];
+        this._activeSpans = new Map();
+        /** Per-launch id; the join key between records and this lifetime's origin. */
+        this._lifetimeId = randomHex(16);
+        /** JSON of the last origin sent, to detect changes (null ⇒ not yet sent). */
+        this._lastOriginJson = null;
+        this._flushHandle = null;
+        this._persistHandle = null;
+        this._disposed = false;
+        this._flushing = false;
+        this._opts = opts;
+        this._loadPersistedLogs();
+        this._flushHandle = setInterval(() => this.flush(), opts.flushCadenceMs ?? DEFAULT_FLUSH_CADENCE_MS);
+    }
+    /** This TracelogClient's lifetime id (one per launch / process run). */
+    get lifetimeId() {
+        return this._lifetimeId;
+    }
+    // ---- Fluent event builder ----
+    event(type = 'client-log') {
+        return new EventBuilder_1.EventBuilder((evt) => this._enqueueEvent(evt), type);
+    }
+    // ---- Live traces: transactions & spans ----
+    /** Start a root timed operation (a trace root). Recorded as a transaction. */
+    startTransaction(name, opts) {
+        const id = randomHex(16);
+        const trace_id = randomHex(32);
+        const type = opts?.type ?? DEFAULT_TYPE;
+        this._activeSpans.set(id, {
+            kind: 'transaction', id, trace_id, name, type,
+            startTime: now(), tzOffset: (0, util_1.tzOffsetMinutes)(), children: [],
+        });
+        return new Transaction(this, id, trace_id, type);
+    }
+    /** Start a sub-operation under a transaction or span. Recorded as a span. */
+    startSpan(name, parent, opts) {
+        const id = randomHex(16);
+        const type = opts?.type ?? DEFAULT_TYPE;
+        this._activeSpans.set(id, {
+            kind: 'span', id,
+            trace_id: parent.traceId,
+            transaction_id: parent.transactionId,
+            parent_id: parent.id,
+            name, type,
+            startTime: now(), tzOffset: (0, util_1.tzOffsetMinutes)(), children: [],
+        });
+        this._activeSpans.get(parent.id)?.children.push(id);
+        return new Span(this, id, parent.traceId, parent.transactionId, parent.id, type);
+    }
+    /** Internal: end a live transaction/span by id (called by the handles). */
+    _end(id, opts) {
+        const active = this._activeSpans.get(id);
+        if (!active)
+            return;
+        // Auto-close any children not yet ended, so a forgotten child can't leak.
+        for (const childId of active.children) {
+            if (this._activeSpans.has(childId))
+                this._end(childId);
+        }
+        const duration = Math.max(0, now() - active.startTime);
+        const base = {
+            id: active.id,
+            trace_id: active.trace_id,
+            name: active.name,
+            type: active.type,
+            timestamp: Math.round(active.startTime * 1000), // ms → µs
+            duration: Math.round(duration),
+            outcome: opts?.outcome ?? 'success',
+            tz_offset: active.tzOffset,
+            ...(opts?.labels && Object.keys(opts.labels).length > 0 ? { context: { labels: opts.labels } } : {}),
+        };
+        this._activeSpans.delete(id);
+        if (active.kind === 'transaction') {
+            this._enqueueTransaction(base);
+        }
+        else {
+            this._enqueueSpan({ ...base, transaction_id: active.transaction_id, parent_id: active.parent_id });
+        }
+    }
+    // ---- One-shot (pre-measured) traces ----
+    /** Record a complete root operation timed elsewhere → a transaction. */
+    recordTransaction(name, durationMs, opts) {
+        if (this._disposed || this._belowThreshold(durationMs, opts))
+            return;
+        const id = randomHex(16);
+        this._enqueueTransaction(this._buildOneShot(id, randomHex(32), name, durationMs, opts));
+    }
+    /** Record a complete sub-operation timed elsewhere → a span under `parent`. */
+    recordSpan(name, durationMs, parent, opts) {
+        if (this._disposed || this._belowThreshold(durationMs, opts))
+            return;
+        const id = randomHex(16);
+        const rec = this._buildOneShot(id, parent.traceId, name, durationMs, opts);
+        rec.transaction_id = parent.transactionId;
+        rec.parent_id = parent.id;
+        this._enqueueSpan(rec);
+    }
+    _belowThreshold(durationMs, opts) {
+        return opts?.minDurationMs !== undefined && durationMs < opts.minDurationMs;
+    }
+    _buildOneShot(id, trace_id, name, durationMs, opts) {
+        const d = isFinite(durationMs) && durationMs > 0 ? durationMs : 0;
+        const rec = {
+            id, trace_id, name,
+            type: opts?.type ?? DEFAULT_TYPE,
+            // No live start, so back-compute it from the measured duration.
+            timestamp: Math.round((now() - d) * 1000), // ms → µs
+            duration: Math.round(d),
+            outcome: opts?.outcome ?? 'success',
+            tz_offset: (0, util_1.tzOffsetMinutes)(),
+        };
+        if (opts?.labels && Object.keys(opts.labels).length > 0)
+            rec.context = { labels: opts.labels };
+        return rec;
+    }
+    // ---- Transport ----
+    async flush() {
+        if (this._disposed || this._flushing)
+            return;
+        if (this._eventBuffer.length === 0 && this._transactionBuffer.length === 0 && this._spanBuffer.length === 0)
+            return;
+        this._flushing = true;
+        try {
+            const events = this._eventBuffer.splice(0);
+            const transactions = this._transactionBuffer.splice(0);
+            const spans = this._spanBuffer.splice(0);
+            const origin = this._takeOriginIfChanged();
+            await this._sendInChunks(events, transactions, spans, origin);
+        }
+        finally {
+            this._flushing = false;
+            this._schedulePersist();
+        }
+    }
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        if (this._flushHandle) {
+            clearInterval(this._flushHandle);
+            this._flushHandle = null;
+        }
+        if (this._persistHandle) {
+            clearTimeout(this._persistHandle);
+            this._persistHandle = null;
+        }
+        this._persistNow();
+    }
+    // ---- Internal: buffering ----
+    _enqueueEvent(event) {
+        if (this._disposed)
+            return;
+        // Level gate: drop events below the host-supplied minimum before buffering.
+        const minLevel = this._opts.getMinLevel?.();
+        if (minLevel && LEVEL_RANK[event.level] < LEVEL_RANK[minLevel])
+            return;
+        if (event.locale === undefined) {
+            const locale = this._opts.getLocale?.();
+            if (locale)
+                event.locale = locale;
+        }
+        this._eventBuffer.push(event);
+        this._afterEnqueue();
+    }
+    _enqueueTransaction(rec) {
+        if (this._disposed)
+            return;
+        this._transactionBuffer.push(rec);
+        this._afterEnqueue();
+    }
+    _enqueueSpan(rec) {
+        if (this._disposed)
+            return;
+        this._spanBuffer.push(rec);
+        this._afterEnqueue();
+    }
+    _afterEnqueue() {
+        this._schedulePersist();
+        const total = this._eventBuffer.length + this._transactionBuffer.length + this._spanBuffer.length;
+        if (total >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE))
+            this.flush();
+    }
+    /** The origin to attach to this flush, or undefined if unchanged since last sent. */
+    _takeOriginIfChanged() {
+        let origin;
+        try {
+            origin = this._opts.getOrigin();
+        }
+        catch {
+            return undefined;
+        }
+        const oj = JSON.stringify(origin);
+        if (oj === this._lastOriginJson)
+            return undefined;
+        this._lastOriginJson = oj;
+        return { ...origin, lifetime_id: this._lifetimeId };
+    }
+    // ---- Internal: chunked sending ----
+    async _sendInChunks(events, transactions, spans, origin) {
+        const maxChunkSize = this._opts.maxChunkSize ?? DEFAULT_MAX_CHUNK_SIZE;
+        const maxChunkBytes = this._opts.maxChunkBytes ?? DEFAULT_MAX_CHUNK_BYTES;
+        const work = [
+            ...events.map((rec) => ({ k: 'e', rec })),
+            ...transactions.map((rec) => ({ k: 't', rec })),
+            ...spans.map((rec) => ({ k: 's', rec })),
+        ];
+        let i = 0;
+        let isFirst = true;
+        while (i < work.length || (isFirst && origin)) {
+            if (!isFirst)
+                await delay(INTER_CHUNK_DELAY_MS);
+            const ce = [];
+            const ct = [];
+            const cs = [];
+            let bytes = 200; // base overhead for the batch envelope
+            while (i < work.length && (ce.length + ct.length + cs.length) < maxChunkSize) {
+                const item = work[i];
+                const itemBytes = estimateJsonSize(item.rec);
+                if (bytes + itemBytes > maxChunkBytes && (ce.length + ct.length + cs.length) > 0)
+                    break;
+                if (item.k === 'e')
+                    ce.push(item.rec);
+                else if (item.k === 't')
+                    ct.push(item.rec);
+                else
+                    cs.push(item.rec);
+                bytes += itemBytes;
+                i++;
+            }
+            const chunkOrigin = isFirst ? origin : undefined;
+            isFirst = false;
+            if (ce.length === 0 && ct.length === 0 && cs.length === 0 && !chunkOrigin)
+                break;
+            await this._sendChunkWithRetry(ce, ct, cs, chunkOrigin);
+        }
+    }
+    async _sendChunkWithRetry(events, transactions, spans, origin) {
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                await this._sendChunk(events, transactions, spans, origin);
+                return;
+            }
+            catch {
+                if (attempt < MAX_RETRIES) {
+                    await delay(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                }
+                else {
+                    // Max retries exceeded — put records back for persistence/retry, and
+                    // re-arm the origin so it ships again on the next successful flush.
+                    this._eventBuffer.push(...events);
+                    this._transactionBuffer.push(...transactions);
+                    this._spanBuffer.push(...spans);
+                    if (origin)
+                        this._lastOriginJson = null;
+                    this._schedulePersist();
+                }
+            }
+        }
+    }
+    async _sendChunk(events, transactions, spans, origin) {
+        const batch = { events, transactions, spans };
+        batch.lifetime_id = this._lifetimeId;
+        const userId = this._opts.getUserId?.();
+        if (userId)
+            batch.user_id = userId;
+        if (origin)
+            batch.origin = origin;
+        const headers = await Promise.resolve(this._opts.getAuthHeaders());
+        const response = await fetch(this._opts.endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: JSON.stringify(batch),
+        });
+        if (!response.ok)
+            throw new Error(`Server returned ${response.status}`);
+    }
+    // ---- Internal: persistence ----
+    _schedulePersist() {
+        if (this._persistHandle || !this._opts.persistLogs)
+            return;
+        this._persistHandle = setTimeout(() => {
+            this._persistHandle = null;
+            this._persistNow();
+        }, PERSIST_DEBOUNCE_MS);
+    }
+    _persistNow() {
+        if (!this._opts.persistLogs)
+            return;
+        if (this._eventBuffer.length === 0 && this._transactionBuffer.length === 0 && this._spanBuffer.length === 0) {
+            this._opts.persistLogs('').catch(() => { });
+            return;
+        }
+        const data = JSON.stringify({
+            events: this._eventBuffer,
+            transactions: this._transactionBuffer,
+            spans: this._spanBuffer,
+        });
+        this._opts.persistLogs(data).catch(() => { });
+    }
+    async _loadPersistedLogs() {
+        if (!this._opts.loadPersistedLogs)
+            return;
+        try {
+            const data = await this._opts.loadPersistedLogs();
+            if (!data)
+                return;
+            const parsed = JSON.parse(data);
+            if (Array.isArray(parsed.events))
+                this._eventBuffer.push(...parsed.events);
+            if (Array.isArray(parsed.transactions))
+                this._transactionBuffer.push(...parsed.transactions);
+            if (Array.isArray(parsed.spans))
+                this._spanBuffer.push(...parsed.spans);
+            this._opts.persistLogs?.('').catch(() => { });
+        }
+        catch {
+            // Ignore parse errors from corrupted persisted data
+        }
+    }
+}
+exports.TracelogClient = TracelogClient;
+// ---- Trace handles ----
+/** A live root operation. Recorded as a `transaction` when ended. */
+class Transaction {
+    constructor(_client, id, traceId, type) {
+        this._client = _client;
+        this.id = id;
+        this.traceId = traceId;
+        this.type = type;
+    }
+    /** A transaction is its own trace root. */
+    get transactionId() { return this.id; }
+    startSpan(name, opts) { return this._client.startSpan(name, this, opts); }
+    end(opts) { this._client._end(this.id, opts); }
+}
+exports.Transaction = Transaction;
+/** A live sub-operation. Recorded as a `span` when ended. */
+class Span {
+    constructor(_client, id, traceId, transactionId, parentId, type) {
+        this._client = _client;
+        this.id = id;
+        this.traceId = traceId;
+        this.transactionId = transactionId;
+        this.parentId = parentId;
+        this.type = type;
+    }
+    startSpan(name, opts) { return this._client.startSpan(name, this, opts); }
+    end(opts) { this._client._end(this.id, opts); }
+}
+exports.Span = Span;
+// ---- Helpers ----
+function randomHex(length) {
+    const chars = '0123456789abcdef';
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += chars[Math.floor(Math.random() * 16)];
+    }
+    return result;
+}
+function now() {
+    if (typeof performance !== 'undefined' && performance.now) {
+        if (!now._offset) {
+            now._offset = Date.now() - performance.now();
+        }
+        return now._offset + performance.now();
+    }
+    return Date.now();
+}
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function estimateJsonSize(obj) {
+    return JSON.stringify(obj).length;
+}

package/dist/index.d.ts CHANGED Viewed

@@ -1,3 +1,3 @@
-export { LogClient } from './LogClient';
+export { TracelogClient, Transaction, Span } from './TracelogClient';
 export { EventBuilder } from './EventBuilder';
-export { LogBatch, LogEventItem, LogPerfItem, ClientInfo, PerfToken, LogClientOptions, LogLevel, JsonValue, } from './types';
+export { RecordBatch, EventRecord, TransactionRecord, SpanRecord, RecordContext, RecordOrigin, RecordKind, Outcome, StartOptions, EndOptions, RecordOptions, LogClientOptions, LogLevel, JsonValue, } from './types';

package/dist/index.js CHANGED Viewed

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventBuilder = exports.LogClient = void 0;
-var LogClient_1 = require("./LogClient");
-Object.defineProperty(exports, "LogClient", { enumerable: true, get: function () { return LogClient_1.LogClient; } });
+exports.EventBuilder = exports.Span = exports.Transaction = exports.TracelogClient = void 0;
+var TracelogClient_1 = require("./TracelogClient");
+Object.defineProperty(exports, "TracelogClient", { enumerable: true, get: function () { return TracelogClient_1.TracelogClient; } });
+Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return TracelogClient_1.Transaction; } });
+Object.defineProperty(exports, "Span", { enumerable: true, get: function () { return TracelogClient_1.Span; } });
 var EventBuilder_1 = require("./EventBuilder");
 Object.defineProperty(exports, "EventBuilder", { enumerable: true, get: function () { return EventBuilder_1.EventBuilder; } });

package/dist/types.d.ts CHANGED Viewed

@@ -1,45 +1,56 @@
-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 perf tree) */
-    trace_id: string;
-    /** ID of the root perf in this trace */
-    root_id: string;
-    /** Name of the operation being measured */
-    name: string;
+import type { JsonValue, LogLevel, RecordOrigin } from '@redthreadlabs/tracelog-schema';
+export type { JsonValue, LogLevel, RecordBatch, EventRecord, TransactionRecord, SpanRecord, RecordContext, RecordOrigin, RecordKind, } from '@redthreadlabs/tracelog-schema';
+export type Outcome = 'success' | 'failure' | 'unknown';
+/** Options when starting a live transaction or span. */
+export interface StartOptions {
+    /** Span/transaction type, e.g. 'db', 'app'. Default: 'app'. */
+    type?: string;
+}
+/** Options when ending a live transaction or span. */
+export interface EndOptions {
+    labels?: Record<string, JsonValue>;
+    outcome?: Outcome;
+}
+/** Options when recording a pre-measured transaction or span in one call. */
+export interface RecordOptions {
+    type?: string;
+    labels?: Record<string, JsonValue>;
+    outcome?: Outcome;
+    /** Drop the record if its duration is below this (ms). */
+    minDurationMs?: number;
 }
 export interface LogClientOptions {
     /** Server endpoint URL for log submission */
     endpoint: string;
     /** Returns auth headers (e.g. { Authorization: 'Bearer ...' }) */
     getAuthHeaders: () => Promise<Record<string, string>> | Record<string, string>;
-    /** Static client/device info, sent once per batch */
-    client: ClientInfo;
-    /** Returns current user ID, if logged in */
+    /**
+     * The current RecordOrigin (service + environment). The SDK sends it as a
+     * `metadata` record on the first batch of this lifetime and again whenever it
+     * changes; it fills in `lifetime_id`.
+     */
+    getOrigin: () => RecordOrigin;
+    /** Returns current user ID, if logged in (→ batch.user_id). */
     getUserId?: () => string | undefined;
-    /** Returns current session reference */
-    getSessionRef?: () => string | undefined;
-    /** Returns native device identifier */
-    getDeviceId?: () => string | undefined;
+    /** Returns the UI locale at event time; stamped onto each event. */
+    getLocale?: () => string | undefined;
     /**
      * 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.
+     * Omit to emit every level (default). Transactions/spans are unaffected.
      */
     getMinLevel?: () => LogLevel;
     /** Flush cadence in ms. Default: 5000 */
     flushCadenceMs?: number;
-    /** Max events buffered before forced flush. Default: 100 */
+    /** Max records buffered before forced flush. Default: 100 */
     maxBufferSize?: number;
-    /** Max events per HTTP request. Default: 50 */
+    /** Max records per HTTP request. Default: 50 */
     maxChunkSize?: number;
     /** Max bytes per HTTP request. Default: 524288 (512KB) */
     maxChunkBytes?: number;
-    /** Persist pending logs (e.g. to AsyncStorage). Called with JSON string. */
+    /** Persist pending records (e.g. to AsyncStorage). Called with JSON string. */
     persistLogs?: (data: string) => Promise<void>;
-    /** Load previously persisted logs. Returns JSON string or null. */
+    /** Load previously persisted records. Returns JSON string or null. */
     loadPersistedLogs?: () => Promise<string | null>;
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@redthreadlabs/tracelog-client",
-  "version": "1.8.0",
+  "version": "2.1.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.3.0"
+    "@redthreadlabs/tracelog-schema": "^0.5.0"
   }
 }