@redthreadlabs/tracelog-schema 0.3.0 → 0.5.0

package/dist/keys.d.ts

@@ -15,7 +15,7 @@
  * for the live snapshot. `buildKey` and `parseKey` are exact inverses so the
  * agent and viewer never drift on this layout.
  */
-export interface KeyVars {
+export interface ObjectKeyVars {
     channel: string;
     interval: string;
     host: string;
@@ -24,7 +24,7 @@ export interface KeyVars {
     /** the live, still-being-written snapshot */
     current?: boolean;
 }
-export interface ParsedKey {
+export interface ParsedObjectKey {
     key: string;
     channel: string;
     interval: string;
@@ -37,12 +37,12 @@ export interface ParsedKey {
     etag?: string;
 }
 /** Build a log object's key. Pass `gzip` to append the `.gz` suffix. */
-export declare function buildKey(vars: KeyVars, gzip?: boolean): string;
+export declare function buildKey(vars: ObjectKeyVars, gzip?: boolean): string;
 /**
  * Parse a log object's key back into its parts, or null if it is not a log
  * file in the known grammar (e.g. a sidecar `.meta.json`, or anything else).
  */
-export declare function parseKey(key: string, size?: number, lastModified?: Date, etag?: string): ParsedKey | null;
+export declare function parseKey(key: string, size?: number, lastModified?: Date, etag?: string): ParsedObjectKey | null;
 /**
  * The UTC time span an interval label covers: daily `YYYY-MM-DD` → 24 h,
  * hourly `YYYY-MM-DDTHH` → 1 h. Unknown grammar → null (callers should be
@@ -50,14 +50,14 @@ export declare function parseKey(key: string, size?: number, lastModified?: Date
  */
 export declare function intervalSpan(interval: string): [number, number] | null;
 /** Whether a file's interval overlaps [startMs, endMs]. Unknown layout → kept. */
-export declare function overlapsRange(file: Pick<ParsedKey, 'interval'>, startMs: number, endMs: number): boolean;
+export declare function overlapsRange(file: Pick<ParsedObjectKey, 'interval'>, startMs: number, endMs: number): boolean;
 /**
  * Drop `_current` snapshots shadowed by their finalized file: if the finalized
  * key exists, ignore the (briefly surviving) `_current`. A `_current` with no
  * finalized sibling is kept — it is either live (today) or a dead host's only
  * copy.
  */
-export declare function dedupeCurrents<T extends Pick<ParsedKey, 'channel' | 'interval' | 'host' | 'seq' | 'current'>>(files: T[]): T[];
+export declare function dedupeCurrents<T extends Pick<ParsedObjectKey, 'channel' | 'interval' | 'host' | 'seq' | 'current'>>(files: T[]): T[];
 /**
  * Normalize a hostname into the host label used in keys. EC2 internal
  * hostnames (`ip-A-B-C-D[.…]`) become the dotted IP — which avoids embedding

package/dist/kinds.d.ts

@@ -1,9 +1,17 @@
 /**
- * The record kinds that appear as the single top-level key of every NDJSON
- * line tracelog writes: `{ "<kind>": { ...fields... } }`. `metadata` is the
- * once-per-file header line, not a data record, so it is not a RecordKind.
+ * The DATA record kinds — the single top-level key of a data NDJSON line:
+ * `{ "<kind>": { ...fields... } }`. These are what the sidecar histogram counts.
+ * `metadata` is deliberately NOT here: it's a dimension/context record, not data
+ * (see {@link METADATA_KIND}).
  */
 export type RecordKind = 'transaction' | 'span' | 'error' | 'event' | 'metricset';
 export declare const RECORD_KINDS: readonly RecordKind[];
-/** The header line's kind. Every file's first line is `{ "metadata": {...} }`. */
+/**
+ * The `metadata` line's kind: `{ "metadata": <RecordOrigin> }` — it carries a
+ * RecordOrigin (service + environment), not data. It appears in two scopes:
+ *   - the per-file header (file-scoped — the writer's origin), and
+ *   - in-stream (lifetime-scoped — a client's per-launch origin, keyed by
+ *     `lifetime_id`), which records join to.
+ * Excluded from RECORD_KINDS and the sidecar histogram (it isn't a data record).
+ */
 export declare const METADATA_KIND = "metadata";

package/dist/kinds.js

@@ -12,5 +12,12 @@ exports.RECORD_KINDS = [
     'event',
     'metricset',
 ];
-/** The header line's kind. Every file's first line is `{ "metadata": {...} }`. */
+/**
+ * The `metadata` line's kind: `{ "metadata": <RecordOrigin> }` — it carries a
+ * RecordOrigin (service + environment), not data. It appears in two scopes:
+ *   - the per-file header (file-scoped — the writer's origin), and
+ *   - in-stream (lifetime-scoped — a client's per-launch origin, keyed by
+ *     `lifetime_id`), which records join to.
+ * Excluded from RECORD_KINDS and the sidecar histogram (it isn't a data record).
+ */
 exports.METADATA_KIND = 'metadata';

package/dist/wire.d.ts

@@ -1,30 +1,63 @@
 /**
  * The wire format for the `POST /logs` ingest endpoint: what a remote client
- * (browser, React Native) sends and what the server parses. The server maps
- * these into the on-disk record kinds (see kinds.ts). Defined here so the
- * client SDK, the server, and the viewer all share one definition.
+ * (browser, React Native) sends. Defined here so the client SDK, the server, and
+ * the viewer all share one definition.
+ *
+ * The wire records ARE (modulo a few server-stamped fields) the on-disk records,
+ * in the same units — timestamps are epoch MICROSECONDS, durations are
+ * MILLISECONDS — so the ingest endpoint forwards them as-is rather than
+ * unwrapping and re-wrapping each one. The server's only per-record job is to
+ * stamp batch-level facts it owns (lifetime_id, context.user from the JWT, the
+ * source IP) and write to the channel.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-export interface LogBatch {
-    client: ClientInfo;
+export interface RecordBatch {
     user_id?: string;
-    session_ref?: string;
-    device_id?: string;
-    events: LogEventItem[];
-    perfs: LogPerfItem[];
+    /**
+     * Id for this SDK lifetime (one app launch / process run), generated by the
+     * SDK. The join key between records and the once-per-lifetime `metadata`
+     * record that carries this launch's RecordOrigin.
+     */
+    lifetime_id?: string;
+    /**
+     * This lifetime's RecordOrigin (service + environment). Sent on the first
+     * batch of a launch and again when it changes; the server writes it as an
+     * in-stream `metadata` record keyed by `lifetime_id`.
+     */
+    origin?: RecordOrigin;
+    events: EventRecord[];
+    transactions: TransactionRecord[];
+    spans: SpanRecord[];
+}
+/**
+ * Per-record context, shared by every record kind. `labels` is the arbitrary
+ * key-value attribute bag; `user` is the identity the record is attributed to.
+ * Mirrors the agent's native `context.labels` / `context.user`.
+ */
+export interface RecordContext {
+    /** Arbitrary key-value attributes. */
+    labels?: Record<string, JsonValue>;
+    /** The user this record is attributed to. */
+    user?: {
+        id?: string;
+    };
 }
-export interface LogEventItem {
+/**
+ * A discrete log entry — something that happened at an instant: a log line or a
+ * behavioral event, carrying a level, message, and context labels. Events are
+ * NOT timed: a timed operation is a transaction/span, never an event with a
+ * duration.
+ */
+export interface EventRecord {
     /** Event category, e.g. 'auth', 'billing', 'startup'. Default: 'client-log' */
     type: string;
-    /** Epoch milliseconds */
+    /** Epoch microseconds */
     timestamp: number;
     level: LogLevel;
     message: string;
-    /** Duration in milliseconds (for timed events that aren't span-shaped) */
-    duration?: number;
     /** Serialized error info. `code` is the structured error code. */
     error?: {
         message: string;
@@ -32,8 +65,10 @@ export interface LogEventItem {
         code?: string;
         stack?: string;
     };
-    /** Arbitrary key-value event data */
-    params?: Record<string, JsonValue>;
+    /** UI locale at record time, e.g. 'en-US'. Can change mid-launch, so per-event. */
+    locale?: string;
+    /** Labels + user (see RecordContext). */
+    context?: RecordContext;
     /**
      * Minutes east of UTC at the moment the event was recorded (ISO-8601 sign:
      * `localWallClock = UTC + tz_offset`). Captured per-event because buffered
@@ -42,55 +77,106 @@ export interface LogEventItem {
      */
     tz_offset?: number;
 }
-export interface LogPerfItem {
-    /** 16-char hex ID, generated client-side */
+/**
+ * A root timed operation — the top of a trace (a request, a job, an agent run).
+ * Recorded as a `transaction`. Child work hangs off it as {@link SpanRecord}s.
+ */
+export interface TransactionRecord {
+    /** 16-char hex ID, generated client-side. Also the trace's root id. */
     id: string;
-    /** 32-char hex trace ID, shared by parent + children */
+    /** 32-char hex trace ID, shared by the whole trace */
     trace_id: string;
-    /** ID of the root perf in this trace */
-    root_id: string;
-    /** 16-char hex ID of parent perf (absent for root perfs) */
-    parent_id?: string;
-    /** Operation name, e.g. 'content-store-startup' */
+    /** Operation name, e.g. 'parallel-search' */
     name: string;
-    /** Perf category. Default: 'client-perf' */
+    /** Transaction type, e.g. 'request', 'agent', 'app'. Default: 'app' */
     type: string;
-    /** Start time, epoch milliseconds */
+    /** Start time, epoch microseconds */
     timestamp: number;
     /** Duration in milliseconds */
     duration: number;
     outcome: 'success' | 'failure' | 'unknown';
-    context?: {
-        tags?: Record<string, JsonValue>;
-    };
-    /** Minutes east of UTC at record time (see LogEventItem.tz_offset). */
+    /** Labels + user (see RecordContext). */
+    context?: RecordContext;
+    /** Minutes east of UTC at record time (see EventRecord.tz_offset). */
     tz_offset?: number;
 }
-export interface ClientInfo {
-    /** Application name, e.g. 'duiduidui-app' */
+/**
+ * A timed sub-operation within a transaction — recorded as a `span`. Always has
+ * a parent (its transaction, or another span) and belongs to one transaction.
+ */
+export interface SpanRecord {
+    /** 16-char hex ID, generated client-side */
+    id: string;
+    /** 32-char hex trace ID, shared by the whole trace */
+    trace_id: string;
+    /** ID of the transaction (trace root) this span belongs to */
+    transaction_id: string;
+    /** 16-char hex ID of the immediate parent (the transaction or another span) */
+    parent_id: string;
+    /** Operation name, e.g. 'search:hanzi' */
     name: string;
-    /** Application version */
-    version: string;
-    os: {
+    /** Span type, e.g. 'db', 'external', 'app'. Default: 'app' */
+    type: string;
+    /** Start time, epoch microseconds */
+    timestamp: number;
+    /** Duration in milliseconds */
+    duration: number;
+    outcome: 'success' | 'failure' | 'unknown';
+    /** Labels + user (see RecordContext). */
+    context?: RecordContext;
+    /** Minutes east of UTC at record time (see EventRecord.tz_offset). */
+    tz_offset?: number;
+}
+/**
+ * Describes who/what produced records — a service and its environment. Carried
+ * by a `metadata` record in two scopes: the per-file header (the writer's
+ * origin, file-scoped) and, for a client, in-stream once per launch keyed by
+ * `lifetime_id`. Records don't carry the origin; they carry `lifetime_id` (or,
+ * server-side, sit in the file) and join to it.
+ *
+ * `service` + `runtime` are the common core; `host` is server-flavored; `device`
+ * is client-flavored. (locale/timezone are NOT here — they can change mid-launch,
+ * so they live per-record: `EventRecord.locale` and `tz_offset`.)
+ */
+export interface RecordOrigin {
+    /** The SDK lifetime (app launch / process run) this RecordOrigin describes. Join key. */
+    lifetime_id?: string;
+    /** Application / service name + version. */
+    service: {
         name: string;
         version: string;
     };
-    device: {
-        model?: string;
-        brand?: string;
-        type: string;
-    };
+    /** Runtime, e.g. 'react-native', 'node', 'browser'. */
     runtime: {
         name: string;
         version: string;
     };
-    screen?: {
-        width: number;
-        height: number;
-        pixel_ratio: number;
+    os?: {
+        name: string;
+        version: string;
+    };
+    /** Server-flavored: the host the service runs on. */
+    host?: {
+        name?: string;
+    };
+    /** Client-flavored: the device the app runs on. */
+    device?: {
+        /**
+         * Opaque, consumer-defined identifier for the device or installation — an
+         * app's own id, a hardware id, whatever the consumer chooses. The framework
+         * treats it as an opaque string and never interprets it. Stable across this
+         * device's launches, so records join to it through the origin (lifetime_id).
+         */
+        id?: string;
+        model?: string;
+        brand?: string;
+        type?: string;
+        /** Device performance tier. */
+        year_class?: number;
+        screen?: {
+            width: number;
+            height: number;
+            pixel_ratio: number;
+        };
     };
-    locale?: string;
-    /** IANA timezone name for the session, e.g. 'America/New_York'. */
-    timezone?: string;
-    device_year_class?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redthreadlabs/tracelog-schema",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared contract for the tracelog suite: record kinds, S3 key layout, metadata sidecar, and the /logs wire format",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",