@redthreadlabs/tracelog 1.10.0 → 1.12.0

package/lib/agent.js

@@ -650,13 +650,13 @@ Agent.prototype.writeError = function (err, opts, cb) {
       opts.user,
     );
     if (Object.keys(errorUser).length > 0) errorContext.user = errorUser;
-    const errorTags = Object.assign(
+    const errorLabels = Object.assign(
       {},
       trans && trans._labels,
       opts.tags,
       opts.labels,
     );
-    if (Object.keys(errorTags).length > 0) errorContext.tags = errorTags;
+    if (Object.keys(errorLabels).length > 0) errorContext.labels = errorLabels;
     const errorCustom = Object.assign({}, trans && trans._custom, opts.custom);
     if (Object.keys(errorCustom).length > 0) errorContext.custom = errorCustom;
     if (req) {
@@ -951,6 +951,28 @@ Channel.prototype.writeSpan = function (input) {
   }
 };
 
+// Forward client-originated event records as-is (validated + bounded). Distinct
+// from writeEvents, which builds events from the server's own ms-based API.
+Channel.prototype.writeClientEvents = function (events) {
+  if (!this._agent._apmClient || !Array.isArray(events)) return;
+  for (const input of events) {
+    const event = _validateClientEvent(input);
+    if (event) {
+      this._agent._apmClient.sendToChannel(this._name, 'event', event);
+    }
+  }
+};
+
+// Write a client's RecordOrigin (service + environment) as a `metadata` record,
+// keyed by its lifetime_id — the in-stream origin that records join to.
+Channel.prototype.writeRecordOrigin = function (origin) {
+  if (!this._agent._apmClient) return;
+  const validated = _validateRecordOrigin(origin);
+  if (validated) {
+    this._agent._apmClient.sendToChannel(this._name, 'metadata', validated);
+  }
+};
+
 // --- Write transaction/span on the default channel ---
 
 // Write a validated transaction record to the default channel.
@@ -1003,6 +1025,7 @@ function _validateTransaction(input) {
   if (typeof input.duration === 'number' && isFinite(input.duration)) transaction.duration = input.duration;
   if (typeof input.result === 'string') transaction.result = input.result.slice(0, 1024);
   if (typeof input.parent_id === 'string' && HEX_16.test(input.parent_id)) transaction.parent_id = input.parent_id;
+  if (typeof input.lifetime_id === 'string' && HEX_16.test(input.lifetime_id)) transaction.lifetime_id = input.lifetime_id;
   if (input.context && typeof input.context === 'object') {
     const ctx = _sanitizeContext(input.context);
     if (ctx) transaction.context = ctx;
@@ -1033,6 +1056,7 @@ function _validateSpan(input) {
   if (typeof input.duration === 'number' && isFinite(input.duration)) span.duration = input.duration;
   if (typeof input.subtype === 'string') span.subtype = input.subtype.slice(0, 1024);
   if (typeof input.action === 'string') span.action = input.action.slice(0, 1024);
+  if (typeof input.lifetime_id === 'string' && HEX_16.test(input.lifetime_id)) span.lifetime_id = input.lifetime_id;
   if (input.context && typeof input.context === 'object') {
     const ctx = _sanitizeContext(input.context);
     if (ctx) span.context = ctx;
@@ -1046,14 +1070,14 @@ function _validateSpan(input) {
 function _sanitizeContext(ctx) {
   const result = {};
 
-  if (ctx.tags && typeof ctx.tags === 'object') {
-    const tags = {};
-    for (const [k, v] of Object.entries(ctx.tags)) {
+  if (ctx.labels && typeof ctx.labels === 'object') {
+    const labels = {};
+    for (const [k, v] of Object.entries(ctx.labels)) {
       if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
-        tags[k] = v;
+        labels[k] = v;
       }
     }
-    if (Object.keys(tags).length > 0) result.tags = tags;
+    if (Object.keys(labels).length > 0) result.labels = labels;
   }
 
   if (ctx.user && typeof ctx.user === 'object') {
@@ -1067,6 +1091,91 @@ function _sanitizeContext(ctx) {
   return Object.keys(result).length > 0 ? result : undefined;
 }
 
+const VALID_EVENT_LEVELS = ['debug', 'info', 'warn', 'error'];
+
+// Validate a client-originated event record, forwarded as-is to the channel
+// (the server has already stamped user/lifetime_id). Untrusted input, so every
+// string is length-bounded and only known fields survive. Unlike _buildEvent
+// (the server's own ms API) this carries the record's epoch-µs timestamp as-is.
+function _validateClientEvent(input) {
+  if (!input || typeof input !== 'object') return null;
+  const event = {
+    type:
+      typeof input.type === 'string' && input.type
+        ? input.type.slice(0, 256)
+        : 'client-log',
+    timestamp:
+      typeof input.timestamp === 'number' && isFinite(input.timestamp)
+        ? Math.floor(input.timestamp)
+        : Date.now() * 1000,
+    level: VALID_EVENT_LEVELS.includes(input.level) ? input.level : 'info',
+  };
+  if (typeof input.message === 'string') event.message = input.message.slice(0, 10000);
+  if (typeof input.locale === 'string' && input.locale) event.locale = input.locale.slice(0, 64);
+  if (typeof input.tz_offset === 'number' && isFinite(input.tz_offset)) event.tz_offset = input.tz_offset;
+  if (typeof input.lifetime_id === 'string' && HEX_16.test(input.lifetime_id)) event.lifetime_id = input.lifetime_id;
+  if (input.context && typeof input.context === 'object') {
+    const ctx = _sanitizeContext(input.context);
+    if (ctx) event.context = ctx;
+  }
+  if (input.error && typeof input.error === 'object') {
+    const err = {};
+    if (typeof input.error.message === 'string') err.message = input.error.message.slice(0, 10000);
+    if (typeof input.error.type === 'string') err.type = input.error.type.slice(0, 1024);
+    if (typeof input.error.code === 'string' || typeof input.error.code === 'number') {
+      err.code = String(input.error.code).slice(0, 1024);
+    }
+    if (typeof input.error.stack === 'string') err.stack = input.error.stack.slice(0, 10000);
+    if (Object.keys(err).length > 0) event.error = err;
+  }
+  return event;
+}
+
+// Validate a client RecordOrigin (service + environment) for a `metadata`
+// record. Untrusted input: bound strings, keep only known fields.
+function _validateRecordOrigin(input) {
+  if (!input || typeof input !== 'object') return null;
+  const str = (v) => (typeof v === 'string' ? v.slice(0, 256) : undefined);
+  const nameVer = (o) => {
+    if (!o || typeof o !== 'object') return undefined;
+    const r = {};
+    if (str(o.name) !== undefined) r.name = str(o.name);
+    if (str(o.version) !== undefined) r.version = str(o.version);
+    return Object.keys(r).length > 0 ? r : undefined;
+  };
+  const origin = {};
+  if (typeof input.lifetime_id === 'string' && HEX_16.test(input.lifetime_id)) origin.lifetime_id = input.lifetime_id;
+  const service = nameVer(input.service);
+  if (service) origin.service = service;
+  const runtime = nameVer(input.runtime);
+  if (runtime) origin.runtime = runtime;
+  const os = nameVer(input.os);
+  if (os) origin.os = os;
+  if (input.host && typeof input.host === 'object' && str(input.host.name) !== undefined) {
+    origin.host = { name: str(input.host.name) };
+  }
+  if (input.device && typeof input.device === 'object') {
+    const d = {};
+    if (str(input.device.model) !== undefined) d.model = str(input.device.model);
+    if (str(input.device.brand) !== undefined) d.brand = str(input.device.brand);
+    if (str(input.device.type) !== undefined) d.type = str(input.device.type);
+    if (typeof input.device.year_class === 'number' && isFinite(input.device.year_class)) {
+      d.year_class = input.device.year_class;
+    }
+    if (input.device.screen && typeof input.device.screen === 'object') {
+      const sc = {};
+      for (const k of ['width', 'height', 'pixel_ratio']) {
+        if (typeof input.device.screen[k] === 'number' && isFinite(input.device.screen[k])) {
+          sc[k] = input.device.screen[k];
+        }
+      }
+      if (Object.keys(sc).length > 0) d.screen = sc;
+    }
+    if (Object.keys(d).length > 0) origin.device = d;
+  }
+  return Object.keys(origin).length > 0 ? origin : null;
+}
+
 function _buildEvent(type, opts) {
   const event = {
     type: type || 'custom',

package/lib/apm-client/s3-uploader.js

@@ -18,6 +18,15 @@ const {
   PutObjectCommand,
   DeleteObjectCommand,
 } = require('@aws-sdk/client-s3');
+// The S3 key layout, the sidecar shape, and the histogram-deriving
+// MetaAccumulator are the shared contract — owned by tracelog-schema so the
+// agent (writer) and the viewer (reader) can never drift.
+const {
+  buildKey,
+  normalizeHost,
+  MetaAccumulator,
+  sidecarKey,
+} = require('@redthreadlabs/tracelog-schema');
 
 // S3 key layout is FIXED (not configurable): it is the contract between
 // tracelog and the in-browser log viewer, which scans the bucket with
@@ -47,22 +56,6 @@ const {
 // not a truthful description of its contents. The viewer reads these into its
 // size ledger for deterministic memory/cache accounting and factual rollups,
 // and falls back to estimation for files written before sidecars existed.
-const SIDECAR_VERSION = 1;
-const SIDECAR_SUFFIX = '.meta.json';
-
-function _pad2(n) {
-  return String(n).padStart(2, '0');
-}
-
-/** epoch-ms → UTC hour-bucket label 'YYYY-MM-DDTHH' (matches the viewer). */
-function _hourBucket(ms) {
-  const d = new Date(ms);
-  return (
-    `${d.getUTCFullYear()}-${_pad2(d.getUTCMonth() + 1)}-${_pad2(d.getUTCDate())}` +
-    `T${_pad2(d.getUTCHours())}`
-  );
-}
-
 function _safeSize(p) {
   try {
     return fs.statSync(p).size;
@@ -71,107 +64,6 @@ function _safeSize(p) {
   }
 }
 
-/**
- * Derives a log file's sidecar histogram by parsing its NDJSON lines. The file
- * on disk is the source of truth: counts come from the exact bytes being
- * uploaded, so they cannot drift from the object, and a restart (which wipes
- * any in-memory write-time counters) or an orphaned file from a crashed run is
- * handled for free — we just re-derive from the file.
- *
- * Tolerant by design: an unparseable line is skipped (not a record); a record
- * with a missing/garbage timestamp is counted as `malformed` rather than
- * forced into an interval. Append-only safe: addChunk may be fed successive
- * tails of a growing current file, since every line is newline-terminated so
- * chunk/offset boundaries always land between lines.
- */
-class MetaAccumulator {
-  constructor() {
-    this.offset = 0; // bytes consumed so far (for incremental current parsing)
-    this.records = 0;
-    this.malformed = 0;
-    this.intervals = Object.create(null); // { 'YYYY-MM-DDTHH': { kind: count } }
-    this._partial = '';
-  }
-
-  addChunk(text) {
-    if (!text) return;
-    const s = this._partial + text;
-    let start = 0;
-    let nl;
-    while ((nl = s.indexOf('\n', start)) !== -1) {
-      this._addLine(s.slice(start, nl));
-      start = nl + 1;
-    }
-    this._partial = s.slice(start);
-  }
-
-  flushPartial() {
-    if (this._partial) {
-      this._addLine(this._partial);
-      this._partial = '';
-    }
-  }
-
-  _addLine(line) {
-    const t = line.trim();
-    if (!t) return;
-    let obj;
-    try {
-      obj = JSON.parse(t);
-    } catch (e) {
-      return; // corrupt line — not a countable record (the viewer skips it too)
-    }
-    if (!obj || typeof obj !== 'object') return;
-    const kind = Object.keys(obj)[0];
-    if (!kind || kind === 'metadata') return; // the file's metadata line
-    this.records++;
-    const body = obj[kind];
-    const tsUs =
-      body &&
-      typeof body.timestamp === 'number' &&
-      isFinite(body.timestamp) &&
-      body.timestamp > 0
-        ? body.timestamp
-        : 0;
-    if (!tsUs) {
-      this.malformed++;
-      return;
-    }
-    const bucket = _hourBucket(tsUs / 1000); // serialized timestamps are epoch-µs
-    const byKind =
-      this.intervals[bucket] || (this.intervals[bucket] = Object.create(null));
-    byKind[kind] = (byKind[kind] || 0) + 1;
-  }
-
-  /**
-   * The sidecar object for this file. records === malformed + Σ(intervals).
-   *
-   * Keys are emitted in a fixed, sorted order at every level — top-level fields
-   * in schema order, interval buckets and their kinds sorted lexically — so the
-   * same contents always serialize to byte-identical JSON regardless of the
-   * order records arrived in. That makes a sidecar's ETag a reliable
-   * sameness check.
-   */
-  toMeta(interval, bytes, compressed) {
-    const intervals = Object.create(null);
-    for (const hour of Object.keys(this.intervals).sort()) {
-      const src = this.intervals[hour];
-      const sorted = Object.create(null);
-      for (const kind of Object.keys(src).sort()) sorted[kind] = src[kind];
-      intervals[hour] = sorted;
-    }
-    return {
-      v: SIDECAR_VERSION,
-      interval,
-      bytes,
-      compressed,
-      records: this.records,
-      malformed: this.malformed,
-      intervals,
-    };
-  }
-}
-
 class S3Uploader {
   /**
    * @param {Object} opts
@@ -378,7 +270,7 @@ class S3Uploader {
     this._currentAccs.delete(key);
 
     // Delete the snapshot object and its sidecar (best-effort, both).
-    for (const k of [key, key + SIDECAR_SUFFIX]) {
+    for (const k of [key, sidecarKey(key)]) {
       this._pendingUploads++;
       this._s3
         .send(new DeleteObjectCommand({ Bucket: this._bucket, Key: k }))
@@ -538,13 +430,13 @@ class S3Uploader {
     this._s3
       .send(new PutObjectCommand({
         Bucket: this._bucket,
-        Key: objectKey + SIDECAR_SUFFIX,
+        Key: sidecarKey(objectKey),
         Body: body,
         ContentType: 'application/json',
       }))
       .then(() => {
         if (this._log) {
-          this._log.debug('Uploaded sidecar s3://%s/%s%s', this._bucket, objectKey, SIDECAR_SUFFIX);
+          this._log.debug('Uploaded sidecar s3://%s/%s', this._bucket, sidecarKey(objectKey));
         }
       })
       .catch((err) => {
@@ -567,14 +459,8 @@ class S3Uploader {
    *   - {boolean} [current] - True for the live (incomplete) file snapshot
    */
   _buildKey(vars) {
-    let basename = this._host;
-    if (vars.seq > 0) {
-      basename += `_${vars.seq}`;
-    }
-    if (vars.current) {
-      basename += '_current';
-    }
-    return `${vars.channel}/${vars.interval}/${basename}.jsonl`;
+    // the layout is the shared contract; host comes from this uploader
+    return buildKey({ ...vars, host: this._host });
   }
 
   _logError(fmt, ...args) {
@@ -584,18 +470,6 @@ class S3Uploader {
   }
 }
 
-/**
- * Normalize a hostname into the host label used in S3 keys. EC2 internal
- * hostnames (ip-A-B-C-D or ip-A-B-C-D.ec2.internal etc.) become the dotted
- * IP address, which avoids embedding hyphens in the basename; any other
- * hostname is used as-is.
- */
-function normalizeHost(hostname) {
-  const m = /^ip-(\d{1,3})-(\d{1,3})-(\d{1,3})-(\d{1,3})(\..*)?$/.exec(hostname);
-  if (m) {
-    return `${m[1]}.${m[2]}.${m[3]}.${m[4]}`;
-  }
-  return hostname;
-}
-
+// normalizeHost + MetaAccumulator are re-exported from tracelog-schema (the
+// shared contract) so existing importers keep working.
 module.exports = { S3Uploader, normalizeHost, MetaAccumulator };

package/lib/instrumentation/span.js

@@ -508,7 +508,7 @@ Span.prototype._encode = function (cb) {
     haveContext = true;
   }
   if (self._labels) {
-    context.tags = self._labels;
+    context.labels = self._labels;
     haveContext = true;
   }
   if (haveContext) {

package/lib/instrumentation/transaction.js

@@ -298,7 +298,7 @@ Transaction.prototype.toJSON = function () {
     );
     if (Object.keys(user).length > 0) context.user = user;
     if (this._labels && Object.keys(this._labels).length > 0) {
-      context.tags = this._labels;
+      context.labels = this._labels;
     }
     if (this._custom && Object.keys(this._custom).length > 0) {
       context.custom = this._custom;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redthreadlabs/tracelog",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Node.js APM instrumentation that writes traces to JSONL files",
   "publishConfig": {
     "access": "public"
@@ -50,6 +50,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.0.0",
     "@elastic/ecs-pino-format": "^1.5.0",
+    "@redthreadlabs/tracelog-schema": "^0.3.0",
     "after-all-results": "^2.0.0",
     "async-value-promise": "^1.1.1",
     "basic-auth": "^2.0.1",