@redthreadlabs/tracelog 1.6.0 → 1.7.0

package/lib/agent.js

@@ -640,17 +640,25 @@ Agent.prototype.writeError = function (err, opts, cb) {
   //    for a response that hasn't yet completed (no headers, unset status_code,
   //    etc.).
   setImmediate(() => {
-    // Gather `error.context.*`.
-    const errorContext = {
-      user: Object.assign(
-        {},
-        req && parsers.getUserContextFromRequest(req),
-        trans && trans._user,
-        opts.user,
-      ),
-      tags: Object.assign({}, trans && trans._labels, opts.tags, opts.labels),
-      custom: Object.assign({}, trans && trans._custom, opts.custom),
-    };
+    // Gather `error.context.*`. Members without content are omitted
+    // entirely rather than serialized as empty `{}` placeholders.
+    const errorContext = {};
+    const errorUser = Object.assign(
+      {},
+      req && parsers.getUserContextFromRequest(req),
+      trans && trans._user,
+      opts.user,
+    );
+    if (Object.keys(errorUser).length > 0) errorContext.user = errorUser;
+    const errorTags = Object.assign(
+      {},
+      trans && trans._labels,
+      opts.tags,
+      opts.labels,
+    );
+    if (Object.keys(errorTags).length > 0) errorContext.tags = errorTags;
+    const errorCustom = Object.assign({}, trans && trans._custom, opts.custom);
+    if (Object.keys(errorCustom).length > 0) errorContext.custom = errorCustom;
     if (req) {
       errorContext.request = parsers.getContextFromRequest(
         req,
@@ -733,10 +741,11 @@ Agent.prototype.writeError = function (err, opts, cb) {
 //   - `message` {string} - Human-readable description.
 //   - `level` {string} - Severity: 'debug', 'info', 'warn', 'error', 'fatal'.
 //   - `timestamp` {number} - Unix epoch ms. Defaults to Date.now().
+//     (Serialized as epoch-µs, like every other record kind.)
 //   - `duration` {number} - Duration in ms.
-//   - `error` {Error|any} - Error object. Safely extracts message, type, code,
-//     and stack trace into the event record, and also emits a full error record
-//     via captureError.
+//   - `error` {Error|string|Object} - Error to attach. Safely extracts
+//     message, type, code, and stack into `event.error`, including from
+//     error-like plain objects.
 //   - `user` {Object} - End-user identity: { id, email, username }.
 //   - `client` {Object} - Client environment: { name, version, os, device, runtime }.
 //   - `params` {Object} - Arbitrary key-value data.
@@ -764,15 +773,19 @@ Agent.prototype.writeEvent = function (type, opts, cb) {
   }
 
   if (this._apmClient) {
-    const event = this._eventFilters.process(_buildEvent(type, opts));
-    if (event) {
-      this._apmClient.sendEvent(event);
+    const event = _buildEvent(type, opts);
+    // Correlate with the active trace, when there is one. Batch writes
+    // (writeEvents) intentionally do not do this: their events originate
+    // on remote clients, not in the transaction that relayed them.
+    const trans = this.currentTransaction;
+    if (trans) {
+      event.trace_id = trans.traceId;
+      event.transaction_id = trans.id;
+    }
+    const filtered = this._eventFilters.process(event);
+    if (filtered) {
+      this._apmClient.sendEvent(filtered);
     }
-  }
-
-  // If an error was provided, also emit a full error record
-  if (opts.error != null) {
-    this.writeError(opts.error);
   }
 
   if (cb) {
@@ -881,13 +894,16 @@ Channel.prototype.writeEvent = function (type, opts, cb) {
     return;
   }
 
-  const event = this._agent._eventFilters.process(_buildEvent(type, opts));
-  if (event) {
-    this._agent._apmClient.sendToChannel(this._name, 'event', event);
+  const event = _buildEvent(type, opts);
+  // Correlate with the active trace, when there is one (see writeEvent).
+  const trans = this._agent.currentTransaction;
+  if (trans) {
+    event.trace_id = trans.traceId;
+    event.transaction_id = trans.id;
   }
-
-  if (opts.error != null) {
-    this._agent.writeError(opts.error);
+  const filtered = this._agent._eventFilters.process(event);
+  if (filtered) {
+    this._agent._apmClient.sendToChannel(this._name, 'event', filtered);
   }
 
   if (cb) process.nextTick(cb);
@@ -1054,31 +1070,78 @@ function _sanitizeContext(ctx) {
 function _buildEvent(type, opts) {
   const event = {
     type: type || 'custom',
-    timestamp: opts.timestamp || Date.now(),
+    // The API accepts epoch-ms (JS-native, e.g. Date.now()); the record
+    // serializes epoch-µs so every record kind shares one timestamp unit.
+    timestamp:
+      (typeof opts.timestamp === 'number' && isFinite(opts.timestamp)
+        ? opts.timestamp
+        : Date.now()) * 1000,
+    level:
+      typeof opts.level === 'string' && opts.level !== ''
+        ? opts.level
+        : 'info',
   };
   if (opts.message != null) event.message = opts.message;
-  if (opts.level != null) event.level = opts.level;
   if (opts.duration != null) event.duration = opts.duration;
   if (opts.user != null) event.user = opts.user;
   if (opts.client != null) event.client = opts.client;
   if (opts.params != null) event.params = opts.params;
   if (opts.error != null) {
-    const err = opts.error;
-    event.error = {};
-    if (isError(err)) {
-      event.error.message = String(err.message || '');
-      if (err.name) event.error.type = String(err.name);
-      if (err.code) event.error.code = String(err.code);
-      if (err.stack) event.error.stack = String(err.stack);
-    } else if (typeof err === 'string') {
-      event.error.message = err;
-    } else {
-      event.error.message = String(err);
-    }
+    event.error = _extractEventError(opts.error);
   }
   return event;
 }
 
+// Build the `event.error` sub-object from an Error instance, a string, or
+// an error-like plain object. The plain-object case matters: errors that
+// crossed a process boundary (e.g. client errors relayed through a server
+// endpoint, ShareDB op errors) arrive as `{message, code, ...}` objects,
+// and stringifying those yields the useless '[object Object]'.
+function _extractEventError(err) {
+  const out = {};
+  if (isError(err)) {
+    out.message = String(err.message || '');
+    if (err.name) out.type = String(err.name);
+    if (err.code != null) out.code = String(err.code);
+    if (err.stack) out.stack = String(err.stack);
+  } else if (typeof err === 'string') {
+    out.message = err;
+  } else if (err && typeof err === 'object') {
+    out.message =
+      typeof err.message === 'string' && err.message !== ''
+        ? err.message
+        : _safeJson(err);
+    if (err.name != null || err.type != null) {
+      out.type = String(err.name != null ? err.name : err.type);
+    }
+    if (err.code != null) out.code = String(err.code);
+    if (typeof err.stack === 'string' && err.stack !== '') {
+      out.stack = err.stack;
+    }
+  } else {
+    out.message = String(err);
+  }
+  return out;
+}
+
+// Bounded JSON representation for error-like objects without a usable
+// `message`. Falls back to a key listing when JSON.stringify fails or
+// produces nothing informative.
+function _safeJson(obj) {
+  try {
+    const json = JSON.stringify(obj);
+    if (json && json !== '{}') {
+      return json.length > 500 ? json.slice(0, 500) + '…' : json;
+    }
+  } catch (e) {
+    // fall through to the key listing
+  }
+  const keys = Object.keys(obj);
+  return keys.length > 0
+    ? '[object with keys: ' + keys.join(', ') + ']'
+    : Object.prototype.toString.call(obj);
+}
+
 // The optional callback will be called with the error object after the error
 // have been sent to the intake API. If no callback have been provided we will
 // automatically terminate the process, so if you provide a callback you must

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

@@ -44,6 +44,7 @@ function createApmClient(config, agent) {
 
   const client = new JsonlFileClient({
     serviceName: config.serviceName,
+    serviceNodeName: config.serviceNodeName,
     serviceVersion: config.serviceVersion,
     environment: config.environment,
     globalLabels: maybePairsToObject(config.globalLabels),

package/lib/apm-client/channel-writer.js

@@ -55,10 +55,15 @@ class ChannelWriter {
     this._metadata = opts.metadata;
     this._metadataFilters = opts.metadataFilters;
     this._extraMetadata = opts.extraMetadata || null;
+    this._metadataReady = opts.metadataReady || null;
     this._s3Uploader = opts.s3Uploader || null;
     this._clock = opts.clock || (() => new Date());
     this._log = opts.logger || null;
 
+    // How long flush() may hold the first write waiting for asynchronously
+    // fetched metadata (e.g. cloud) before proceeding without it.
+    this._metadataWaitDeadline = this._clock().getTime() + 10 * 1000;
+
     // Rotation schedule
     const schedule = opts.rotationSchedule || 'daily';
     if (typeof schedule === 'string' && ROTATION_SCHEDULES[schedule]) {
@@ -129,9 +134,23 @@ class ChannelWriter {
     }
   }
 
-  flush() {
+  flush(opts) {
     if (this._buffer.length === 0) return;
 
+    // Hold the first write of a file until asynchronously fetched metadata
+    // (cloud) is ready, so the file's metadata line is complete. The wait
+    // is bounded twice over: the fetcher's own timeout flips the readiness
+    // flag, and the hard deadline covers a callback that never fires.
+    if (
+      !(opts && opts.force) &&
+      this._metadataReady &&
+      !this._wroteMetadata &&
+      !this._metadataReady() &&
+      this._clock().getTime() < this._metadataWaitDeadline
+    ) {
+      return;
+    }
+
     try {
       this._checkTimeRotation();
 
@@ -181,7 +200,9 @@ class ChannelWriter {
   destroy() {
     if (this._destroyed) return;
     this._destroyed = true;
-    this.flush();
+    // Force: never hold buffered records back at shutdown, even if
+    // asynchronously fetched metadata never became ready.
+    this.flush({ force: true });
     this.uploadCurrent();
   }
 

package/lib/apm-client/jsonl-file-client.js

@@ -14,6 +14,7 @@ const os = require('os');
 const Filters = require('object-filter-sequence');
 
 const { ChannelWriter } = require('./channel-writer');
+const { normalizeHost } = require('./s3-uploader');
 
 const DEFAULT_FLUSH_INTERVAL_MS = 1000;
 const DEFAULT_ROTATION_SCHEDULE = 'daily';
@@ -61,6 +62,9 @@ class JsonlFileClient extends EventEmitter {
           name: opts.serviceName || 'unknown',
           version: opts.serviceVersion || undefined,
           environment: opts.environment || undefined,
+          ...(opts.serviceNodeName && {
+            node: { configured_name: opts.serviceNodeName },
+          }),
           agent: { name: 'tracelog', version: require('../../package').version },
         },
         process: {
@@ -69,13 +73,18 @@ class JsonlFileClient extends EventEmitter {
           argv: process.argv,
         },
         system: {
-          hostname: os.hostname(),
+          // Normalized the same way as the host in S3 keys, so a viewer
+          // can correlate metadata with key-derived hosts using one rule.
+          hostname: normalizeHost(os.hostname()),
           architecture: os.arch(),
           platform: os.platform(),
         },
         ...(opts.globalLabels && { labels: opts.globalLabels }),
       },
       s3Uploader: opts.s3Uploader || null,
+      // Lets writers hold their first write (bounded) until the async
+      // cloud-metadata fetch resolves, so metadata lines include `cloud`.
+      metadataReady: () => this._cloudMetadataReady,
       maxFileSize: opts.maxFileSize,
       maxBufferSize: opts.maxBufferSize || DEFAULT_MAX_BUFFER_SIZE,
       rotationSchedule: opts.rotationSchedule || DEFAULT_ROTATION_SCHEDULE,
@@ -211,6 +220,9 @@ class JsonlFileClient extends EventEmitter {
     }
 
     for (const writer of this._writers.values()) {
+      // Not forced: while the (bounded) wait for async cloud metadata is
+      // pending, records stay buffered. destroy() is the path that must
+      // never hold records back.
       writer.flush();
     }
 

package/lib/errors.js

@@ -175,7 +175,7 @@ function createAPMError(args, cb) {
       sampled: args.trans.sampled,
     };
   }
-  if (args.errorContext) {
+  if (args.errorContext && Object.keys(args.errorContext).length > 0) {
     error.context = args.errorContext;
   }
 

package/lib/instrumentation/transaction.js

@@ -288,18 +288,31 @@ Transaction.prototype.toJSON = function () {
   };
 
   if (this.sampled) {
-    payload.context = {
-      user: Object.assign(
-        {},
-        this.req && parsers.getUserContextFromRequest(this.req),
-        this._user,
-      ),
-      tags: this._labels || {},
-      custom: this._custom || {},
-      service: this._service || {},
-      cloud: this._cloud || {},
-      message: this._message || {},
-    };
+    // Only include context members that have content — empty placeholder
+    // objects are omitted entirely rather than serialized as `{}`.
+    const context = {};
+    const user = Object.assign(
+      {},
+      this.req && parsers.getUserContextFromRequest(this.req),
+      this._user,
+    );
+    if (Object.keys(user).length > 0) context.user = user;
+    if (this._labels && Object.keys(this._labels).length > 0) {
+      context.tags = this._labels;
+    }
+    if (this._custom && Object.keys(this._custom).length > 0) {
+      context.custom = this._custom;
+    }
+    if (this._service && Object.keys(this._service).length > 0) {
+      context.service = this._service;
+    }
+    if (this._cloud && Object.keys(this._cloud).length > 0) {
+      context.cloud = this._cloud;
+    }
+    if (this._message && Object.keys(this._message).length > 0) {
+      context.message = this._message;
+    }
+
     // Only include dropped count when spans have been dropped.
     if (this._droppedSpans > 0) {
       payload.span_count.dropped = this._droppedSpans;
@@ -307,14 +320,17 @@ Transaction.prototype.toJSON = function () {
 
     var conf = this._agent._conf;
     if (this.req) {
-      payload.context.request = parsers.getContextFromRequest(
+      context.request = parsers.getContextFromRequest(
         this.req,
         conf,
         'transactions',
       );
     }
     if (this.res) {
-      payload.context.response = parsers.getContextFromResponse(this.res, conf);
+      context.response = parsers.getContextFromResponse(this.res, conf);
+    }
+    if (Object.keys(context).length > 0) {
+      payload.context = context;
     }
   }
 
@@ -410,6 +426,19 @@ Transaction.prototype.end = function (result, endTime) {
 
   if (result !== undefined && result !== null) {
     this.result = result;
+
+    // Manually ended transactions never go through
+    // _setOutcomeFromHttpStatusCode, so derive the outcome from an
+    // explicitly passed string result rather than serializing 'unknown'
+    // alongside result 'success'. (The result *default* of 'success' does
+    // not derive: ending without a result means the outcome is unknown.)
+    if (this.outcome === constants.OUTCOME_UNKNOWN && !this._isOutcomeFrozen) {
+      if (result === 'success') {
+        this.outcome = constants.OUTCOME_SUCCESS;
+      } else if (result === 'failure' || result === 'error') {
+        this.outcome = constants.OUTCOME_FAILURE;
+      }
+    }
   }
 
   if (!this._defaultName && this.req) this.setDefaultNameFromRequest();

package/lib/metrics/registry.js

@@ -12,6 +12,7 @@ const { SelfReportingMetricsRegistry } = require('measured-reporting');
 const DimensionAwareMetricsRegistry = require('measured-reporting/lib/registries/DimensionAwareMetricsRegistry');
 
 const MetricsReporter = require('./reporter');
+const { normalizeHost } = require('../apm-client/s3-uploader');
 const createRuntimeMetrics = require('./runtime');
 const createSystemMetrics =
   process.platform === 'linux'
@@ -22,7 +23,8 @@ class MetricsRegistry extends SelfReportingMetricsRegistry {
   constructor(agent, { reporterOptions, registryOptions = {} } = {}) {
     const defaultReporterOptions = {
       defaultDimensions: {
-        hostname: agent._conf.hostname || os.hostname(),
+        // Normalized the same way as the host in S3 keys (see s3-uploader).
+        hostname: normalizeHost(agent._conf.hostname || os.hostname()),
         env: agent._conf.environment || '',
       },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redthreadlabs/tracelog",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Node.js APM instrumentation that writes traces to JSONL files",
   "publishConfig": {
     "access": "public"