@redthreadlabs/tracelog-client 1.8.0 → 2.0.0

package/dist/EventBuilder.d.ts

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -0,0 +1,399 @@
+"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?.();
+        const deviceId = this._opts.getDeviceId?.();
+        if (userId)
+            batch.user_id = userId;
+        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 },
+            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

@@ -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

@@ -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

@@ -1,45 +1,58 @@
-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 */
+    /** Returns the consumer's opaque device/installation id (→ batch.device_id). */
     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

@@ -1,6 +1,6 @@
 {
   "name": "@redthreadlabs/tracelog-client",
-  "version": "1.8.0",
+  "version": "2.0.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.4.0"
   }
 }