@redthreadlabs/tracelog 1.5.1 → 1.7.0

package/README.md

@@ -19,12 +19,16 @@ require('tracelog').start({
   serviceName: 'my-api',
   serviceVersion: '1.0.0',
   logDir: '/var/log/myapp',
+  defaultChannel: 'server',
   s3Bucket: 'my-traces',
   s3Region: 'us-east-1',
-  s3KeyTemplate: '{serviceName}/{environment}/{date}/{hostname}-{pid}-{timestamp}.jsonl',
 });
 ```
 
+S3 keys follow a fixed layout designed for prefix scans and per-channel
+lifecycle rules: `{channel}/{interval}/{host}[_{seq}][_current].jsonl[.gz]`
+(see CONFIG.md).
+
 Or use the auto-start entry point with environment variables:
 
 ```bash

package/index.d.ts

@@ -318,10 +318,16 @@ declare namespace apm {
     maxLocalRetentionDays?: number;
     maxBufferSize?: number;
 
-    // Tracelog: S3 upload
+    /**
+     * Name of the default channel — the first segment of local filenames
+     * and S3 keys for records not routed elsewhere. Default: 'default'.
+     */
+    defaultChannel?: string;
+
+    // Tracelog: S3 upload. The S3 key layout is fixed:
+    // {channel}/{interval}/{host}[_{seq}][_current].jsonl[.gz]
     s3Bucket?: string;
     s3Region?: string;
-    s3KeyTemplate?: string;
     s3UploadIntervalMs?: number;
     s3GzipCompleted?: boolean;
     s3GzipCurrent?: boolean;

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

@@ -31,9 +31,6 @@ function createApmClient(config, agent) {
   if (config.s3Bucket) {
     s3Uploader = new S3Uploader({
       bucket: config.s3Bucket,
-      keyTemplate:
-        config.s3KeyTemplate ||
-        '{serviceName}/{environment}/{hostname}-{channel}-{interval}.jsonl',
       region: config.s3Region,
       accessKeyId: config.s3AccessKeyId,
       secretAccessKey: config.s3SecretAccessKey,
@@ -41,14 +38,13 @@ function createApmClient(config, agent) {
       s3Client: config.s3Client, // optional: inject a mock for testing
       gzipCompleted: config.s3GzipCompleted,
       gzipCurrent: config.s3GzipCurrent,
-      serviceName: config.serviceName,
-      environment: config.environment,
       logger: config.logger,
     });
   }
 
   const client = new JsonlFileClient({
     serviceName: config.serviceName,
+    serviceNodeName: config.serviceNodeName,
     serviceVersion: config.serviceVersion,
     environment: config.environment,
     globalLabels: maybePairsToObject(config.globalLabels),
@@ -60,6 +56,7 @@ function createApmClient(config, agent) {
     // JSONL file options
     logDir: config.logDir,
     logFilePrefix: config.logFilePrefix,
+    defaultChannel: config.defaultChannel,
     maxFileSize: config.logMaxFileSize,
     flushIntervalMs: config.logFlushIntervalMs,
     rotationSchedule: config.logRotationSchedule,

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();
 
@@ -170,14 +189,20 @@ class ChannelWriter {
 
   uploadCurrent() {
     if (this._s3Uploader) {
-      this._s3Uploader.uploadCurrent(this._currentFilePath, { channel: this._channel });
+      this._s3Uploader.uploadCurrent(this._currentFilePath, {
+        channel: this._channel,
+        interval: this._currentPeriodLabel,
+        seq: this._currentSeqNum,
+      });
     }
   }
 
   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();
   }
 
@@ -217,7 +242,11 @@ class ChannelWriter {
     this._wroteMetadata = false;
 
     if (this._s3Uploader && fs.existsSync(completedFilePath)) {
-      this._s3Uploader.uploadCompleted(completedFilePath, { channel: this._channel, interval: this._currentPeriodLabel });
+      this._s3Uploader.uploadCompleted(completedFilePath, {
+        channel: this._channel,
+        interval: this._currentPeriodLabel,
+        seq: this._currentSeqNum,
+      });
     }
 
     if (this._maxLocalRetentionDays > 0) {
@@ -317,10 +346,15 @@ class ChannelWriter {
 
         const withoutPrefix = file.slice(prefix.length);
         const withoutExt = withoutPrefix.slice(0, withoutPrefix.length - this._ext.length);
+        const seqMatch = /\.(\d+)$/.exec(withoutExt);
         const periodLabel = withoutExt.replace(/\.\d+$/, '');
 
         if (periodLabel < this._currentPeriodLabel) {
-          this._s3Uploader.uploadCompleted(filePath, { channel: this._channel, interval: periodLabel });
+          this._s3Uploader.uploadCompleted(filePath, {
+            channel: this._channel,
+            interval: periodLabel,
+            seq: seqMatch ? parseInt(seqMatch[1], 10) : 0,
+          });
         }
       }
     } catch (e) { /* ignore */ }

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

@@ -14,18 +14,20 @@ 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';
 const DEFAULT_MAX_LOCAL_RETENTION_DAYS = 0;
 const DEFAULT_MAX_BUFFER_SIZE = 10000;
 
-const DEFAULT_CHANNEL = 'default';
+const DEFAULT_CHANNEL = 'default';  // used when opts.defaultChannel is not set
 
 /**
  * A channel-aware JSONL file client. Routes records to ChannelWriter instances
  * based on channel name. Each channel gets its own file, buffer, and rotation
- * lifecycle. The default channel is 'default'.
+ * lifecycle. The default channel is named 'default' unless overridden via
+ * opts.defaultChannel.
  */
 class JsonlFileClient extends EventEmitter {
   constructor(opts) {
@@ -33,6 +35,7 @@ class JsonlFileClient extends EventEmitter {
 
     this._baseDir = opts.logDir || process.cwd();
     this._baseName = opts.logFilePrefix || 'tracelog';
+    this._defaultChannel = opts.defaultChannel || DEFAULT_CHANNEL;
     this._clock = opts.clock || (() => new Date());
     this._log = opts.logger || null;
     this._destroyed = false;
@@ -59,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: {
@@ -67,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,
@@ -105,7 +116,7 @@ class JsonlFileClient extends EventEmitter {
     }
 
     // Create the default channel eagerly.
-    this._getWriter(DEFAULT_CHANNEL);
+    this._getWriter(this._defaultChannel);
 
     // Start periodic flush of all channels.
     const flushIntervalMs = opts.flushIntervalMs || DEFAULT_FLUSH_INTERVAL_MS;
@@ -173,23 +184,23 @@ class JsonlFileClient extends EventEmitter {
   lambdaRegisterTransaction(trans, awsRequestId) {}
 
   sendTransaction(transaction, cb) {
-    this._getWriter(DEFAULT_CHANNEL).send('transaction', transaction, cb);
+    this._getWriter(this._defaultChannel).send('transaction', transaction, cb);
   }
 
   sendSpan(span, cb) {
-    this._getWriter(DEFAULT_CHANNEL).send('span', span, cb);
+    this._getWriter(this._defaultChannel).send('span', span, cb);
   }
 
   sendError(error, cb) {
-    this._getWriter(DEFAULT_CHANNEL).send('error', error, cb);
+    this._getWriter(this._defaultChannel).send('error', error, cb);
   }
 
   sendMetricSet(metricset, cb) {
-    this._getWriter(DEFAULT_CHANNEL).send('metricset', metricset, cb);
+    this._getWriter(this._defaultChannel).send('metricset', metricset, cb);
   }
 
   sendEvent(event, cb) {
-    this._getWriter(DEFAULT_CHANNEL).send('event', event, cb);
+    this._getWriter(this._defaultChannel).send('event', event, cb);
   }
 
   // --- Channel-routed API ---
@@ -209,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/apm-client/s3-uploader.js

@@ -12,31 +12,52 @@ const path = require('path');
 const zlib = require('zlib');
 const { createGzip } = require('zlib');
 const { pipeline } = require('stream');
-const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
+const {
+  S3Client,
+  PutObjectCommand,
+  DeleteObjectCommand,
+} = require('@aws-sdk/client-s3');
+
+// S3 key layout is FIXED (not configurable): it is the contract between
+// tracelog and the in-browser log viewer, which scans the bucket with
+// prefix listings. Channel comes before interval so that prefix-scoped
+// lifecycle rules work and a date-range scan within a channel is a single
+// lexicographically-ordered listing:
+//
+//   {channel}/{interval}/{host}[_{seq}][_current].jsonl[.gz]
+//
+//   server/2026-06-11/172.31.27.225.jsonl.gz
+//   server/2026-06-11/172.31.27.225_current.jsonl.gz
+//   server/2026-06-11/172.31.27.225_1.jsonl.gz
+//
+// There is no serviceName segment: buckets are per-service/per-env, channel
+// names are the top-level namespace (the default channel's name is set via
+// the `defaultChannel` config), and the service name is recorded in every
+// file's metadata line. The basename is underscore-delimited (hostnames
+// cannot contain underscores): host, then a numeric size-rotation seq when
+// > 0, then the literal 'current' for the live file. A host that died
+// mid-interval leaves its final '_current' upload in place, interval intact.
 
 class S3Uploader {
   /**
    * @param {Object} opts
    * @param {string} opts.bucket - S3 bucket name
-   * @param {string} opts.keyTemplate - S3 key template with {variable} placeholders
    * @param {string} [opts.region] - AWS region
    * @param {string} [opts.accessKeyId] - AWS access key ID
    * @param {string} [opts.secretAccessKey] - AWS secret access key
    * @param {string} [opts.sessionToken] - AWS session token
-   * @param {string} opts.serviceName - Service name for template variables
-   * @param {string} [opts.environment] - Environment for template variables
    * @param {boolean} [opts.gzipCompleted=true] - Gzip completed files before upload
    * @param {boolean} [opts.gzipCurrent=true] - Gzip current files before upload
    * @param {Object} [opts.logger] - Logger instance
    * @param {Object} [opts.s3Client] - S3 client instance (must have a send() method).
    *   Defaults to a real S3Client from @aws-sdk/client-s3. Inject a mock for testing.
    * @param {Function} [opts.clock] - Clock provider for testability. Returns a Date.
+   * @param {string} [opts.host] - Host label override (for testing). Defaults to
+   *   the normalized os.hostname().
    */
   constructor(opts) {
     this._bucket = opts.bucket;
-    this._keyTemplate = opts.keyTemplate;
-    this._serviceName = opts.serviceName || 'unknown';
-    this._environment = opts.environment || 'development';
+    this._host = opts.host || normalizeHost(os.hostname());
     this._gzipCompleted = opts.gzipCompleted !== false;
     this._gzipCurrent = opts.gzipCurrent !== false;
     this._log = opts.logger || null;
@@ -68,9 +89,11 @@ class S3Uploader {
   }
 
   /**
-   * Upload a completed (rotated) file, then delete local on success.
+   * Upload a completed (rotated) file, then delete local on success. Also
+   * deletes the now-superseded '_current' snapshot object for the same
+   * interval/seq, so only hosts that died mid-interval leave one behind.
    * @param {string} filePath - Path to the completed JSONL file
-   * @param {Object} vars - Template variables (channel, interval)
+   * @param {Object} vars - Key variables (channel, interval, seq)
    */
   uploadCompleted(filePath, vars) {
     if (!fs.existsSync(filePath)) return;
@@ -83,7 +106,7 @@ class S3Uploader {
   }
 
   _uploadCompletedGzipped(filePath, vars) {
-    const key = this._resolveKey(vars) + '.gz';
+    const key = this._buildKey(vars) + '.gz';
     const gzPath = filePath + '.gz';
 
     this._pendingUploads++;
@@ -116,6 +139,7 @@ class S3Uploader {
           }
           try { fs.unlinkSync(filePath); } catch (e) { /* ignore */ }
           try { fs.unlinkSync(gzPath); } catch (e) { /* ignore */ }
+          this._deleteStaleCurrent(vars);
         })
         .catch((uploadErr) => {
           this._logError(
@@ -132,7 +156,7 @@ class S3Uploader {
   }
 
   _uploadCompletedRaw(filePath, vars) {
-    const key = this._resolveKey(vars);
+    const key = this._buildKey(vars);
 
     this._pendingUploads++;
 
@@ -151,6 +175,7 @@ class S3Uploader {
           this._log.debug('Uploaded completed log to s3://%s/%s', this._bucket, key);
         }
         try { fs.unlinkSync(filePath); } catch (e) { /* ignore */ }
+        this._deleteStaleCurrent(vars);
       })
       .catch((uploadErr) => {
         this._logError(
@@ -165,17 +190,37 @@ class S3Uploader {
   }
 
   /**
-   * Upload the current (incomplete) file without deletion.
-   * Uses a stable S3 key (based on the filename, not a timestamp) so that
-   * each upload overwrites the previous snapshot instead of creating duplicates.
-   * @param {string} filePath - Path to the current JSONL file
-   * @param {Function} [cb] - Callback when upload completes
+   * Delete the '_current' snapshot object superseded by a successful
+   * completed upload of the same channel/interval/seq. Best-effort:
+   * missing objects and failures are ignored.
    */
+  _deleteStaleCurrent(vars) {
+    let key = this._buildKey({ ...vars, current: true });
+    if (this._gzipCurrent) {
+      key += '.gz';
+    }
+
+    this._pendingUploads++;
+    this._s3
+      .send(new DeleteObjectCommand({ Bucket: this._bucket, Key: key }))
+      .then(() => {
+        if (this._log) {
+          this._log.debug('Deleted stale current log s3://%s/%s', this._bucket, key);
+        }
+      })
+      .catch(() => { /* best-effort */ })
+      .finally(() => {
+        this._pendingUploads--;
+      });
+  }
+
   /**
-   * Upload the current (incomplete) file without deletion.
-   * Uses 'current' as the interval so periodic uploads overwrite the same object.
+   * Upload the current (incomplete) file without deletion. The key keeps
+   * the file's real interval and carries a '_current' basename suffix, so
+   * periodic uploads overwrite the same object, and the snapshot sorts
+   * beside its finalized siblings.
    * @param {string} filePath - Path to the current JSONL file
-   * @param {Object} vars - Template variables (channel); interval is set to 'current'
+   * @param {Object} vars - Key variables (channel, interval, seq)
    * @param {Function} [cb] - Callback when upload completes
    */
   uploadCurrent(filePath, vars, cb) {
@@ -188,7 +233,7 @@ class S3Uploader {
       return;
     }
 
-    const currentVars = { ...vars, interval: 'current' };
+    const currentVars = { ...vars, current: true };
     const rawBody = fs.readFileSync(filePath);
 
     if (this._gzipCurrent) {
@@ -199,7 +244,7 @@ class S3Uploader {
   }
 
   _uploadCurrentGzipped(filePath, rawBody, vars, cb) {
-    const key = this._resolveKey(vars) + '.gz';
+    const key = this._buildKey(vars) + '.gz';
 
     this._pendingUploads++;
 
@@ -240,7 +285,7 @@ class S3Uploader {
   }
 
   _uploadCurrentRaw(filePath, rawBody, vars, cb) {
-    const key = this._resolveKey(vars);
+    const key = this._buildKey(vars);
 
     this._pendingUploads++;
 
@@ -271,23 +316,23 @@ class S3Uploader {
   }
 
   /**
-   * Resolve an S3 key from the template.
+   * Build the S3 key for a log file (see the layout contract above).
    *
-   * @param {Object} vars - Template variables:
+   * @param {Object} vars - Key variables:
    *   - {string} channel - Channel name (e.g. 'server', 'client')
-   *   - {string} interval - Period label (e.g. '2026-03-17') or 'current'
+   *   - {string} interval - Period label (e.g. '2026-03-17')
+   *   - {number} [seq] - Size-rotation sequence number within the interval
+   *   - {boolean} [current] - True for the live (incomplete) file snapshot
    */
-  _resolveKey(vars) {
-    const allVars = {
-      serviceName: this._serviceName,
-      environment: this._environment,
-      hostname: os.hostname(),
-      ...vars,
-    };
-
-    return this._keyTemplate.replace(/\{(\w+)\}/g, (match, name) => {
-      return allVars[name] !== undefined ? allVars[name] : match;
-    });
+  _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`;
   }
 
   _logError(fmt, ...args) {
@@ -297,12 +342,18 @@ class S3Uploader {
   }
 }
 
-function _pad2(n) {
-  return String(n).padStart(2, '0');
-}
-
-function _fmtDate(d) {
-  return `${d.getFullYear()}-${_pad2(d.getMonth() + 1)}-${_pad2(d.getDate())}`;
+/**
+ * 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;
 }
 
-module.exports = { S3Uploader };
+module.exports = { S3Uploader, normalizeHost };

package/lib/config/schema.js

@@ -509,7 +509,15 @@ const CONFIG_SCHEMA = [
     defaultValue: 10000,
     envVar: 'TRACELOG_MAX_BUFFER_SIZE',
   },
-  // S3 upload
+  // Channels
+  {
+    name: 'defaultChannel',
+    configType: 'string',
+    defaultValue: 'default',
+    envVar: 'TRACELOG_DEFAULT_CHANNEL',
+  },
+  // S3 upload. The S3 key layout is fixed (the contract with the log
+  // viewer): {channel}/{interval}/{host}[_{seq}][_current].jsonl[.gz]
   {
     name: 's3Bucket',
     configType: 'string',
@@ -522,13 +530,6 @@ const CONFIG_SCHEMA = [
     defaultValue: undefined,
     envVar: 'TRACELOG_S3_REGION',
   },
-  {
-    name: 's3KeyTemplate',
-    configType: 'string',
-    defaultValue:
-      '{serviceName}/{environment}/{date}/{hostname}-{pid}-{timestamp}.jsonl',
-    envVar: 'TRACELOG_S3_KEY_TEMPLATE',
-  },
   {
     name: 's3UploadIntervalMs',
     configType: 'number',

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.5.1",
+  "version": "1.7.0",
   "description": "Node.js APM instrumentation that writes traces to JSONL files",
   "publishConfig": {
     "access": "public"