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