@redthreadlabs/tracelog 1.4.0 → 1.5.1

package/index.d.ts

@@ -293,6 +293,15 @@ declare namespace apm {
     spanStackTraceMinDuration?: string;
     stackTraceLimit?: number;
     traceContinuationStrategy?: TraceContinuationStrategy;
+    /**
+     * Route auto-instrumented transactions (and their spans and breakdown
+     * metricsets) to a named channel when the transaction name matches a
+     * wildcard pattern. First matching rule wins; unmatched records go to
+     * the default channel.
+     *
+     * Example: `[{ pattern: '* unknown route*', channel: 'unknown-route' }]`
+     */
+    transactionChannels?: Array<TransactionChannelRule>;
     transactionIgnoreUrls?: Array<string>;
     transactionMaxSpans?: number;
     transactionSampleRate?: number;
@@ -329,6 +338,13 @@ declare namespace apm {
     writeSpan (span: object): void;
   }
 
+  interface TransactionChannelRule {
+    /** Wildcard pattern matched against the transaction name. */
+    pattern: string;
+    /** Channel to route matching transactions, spans, and breakdown metricsets to. */
+    channel: string;
+  }
+
   interface CaptureEventOptions {
     message?: string;
     level?: 'debug' | 'info' | 'warn' | 'error' | 'fatal';

package/lib/agent.js

@@ -1,5 +1,5 @@
 /*
- * Copyright Shaxpir Inc. and Elasticsearch B.V. and other contributors where applicable.
+ * Copyright Red Thread Labs LLC. and Elasticsearch B.V. and other contributors where applicable.
  * Licensed under the BSD 2-Clause License; you may not use this file except in
  * compliance with the BSD 2-Clause License.
  */
@@ -831,6 +831,26 @@ Agent.prototype.writeEvents = function (events, cb) {
 // the default channel ('server'). Named channels are created lazily via
 // getChannel(name) and write to separate files (e.g. tracelog-client-*.jsonl).
 
+/**
+ * Resolve the channel that records for the named transaction should be
+ * routed to, per the `transactionChannels` config rules (first matching
+ * rule wins). Returns null when no rule matches, i.e. the record belongs
+ * on the default channel. Used for auto-instrumented transactions, their
+ * spans, and their breakdown metricsets.
+ */
+Agent.prototype._channelForTransactionName = function (name) {
+  const rules = this._conf && this._conf.transactionChannelRules;
+  if (!rules || rules.length === 0 || typeof name !== 'string') {
+    return null;
+  }
+  for (let i = 0; i < rules.length; i++) {
+    if (rules[i].re.test(name)) {
+      return rules[i].channel;
+    }
+  }
+  return null;
+};
+
 /**
  * Get a named channel. Returns an object with writeEvent, writeEvents,
  * writeError, writeTransaction, and writeSpan methods that route to the

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

@@ -1,6 +1,6 @@
 /*
  * Copyright Elasticsearch B.V. and other contributors where applicable.
- * Copyright Shaxpir Inc. All rights reserved.
+ * Copyright Red Thread Labs LLC. All rights reserved.
  * Licensed under the BSD 2-Clause License; you may not use this file except in
  * compliance with the BSD 2-Clause License.
  */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright Shaxpir Inc. All rights reserved.
+ * Copyright Red Thread Labs LLC. All rights reserved.
  * Licensed under the BSD 2-Clause License; you may not use this file except in
  * compliance with the BSD 2-Clause License.
  */

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

@@ -1,6 +1,6 @@
 /*
  * Copyright Elasticsearch B.V. and other contributors where applicable.
- * Copyright Shaxpir Inc. All rights reserved.
+ * Copyright Red Thread Labs LLC. All rights reserved.
  * Licensed under the BSD 2-Clause License; you may not use this file except in
  * compliance with the BSD 2-Clause License.
  */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright Shaxpir Inc. All rights reserved.
+ * Copyright Red Thread Labs LLC. All rights reserved.
  * Licensed under the BSD 2-Clause License; you may not use this file except in
  * compliance with the BSD 2-Clause License.
  */

package/lib/config/config.js

@@ -48,6 +48,7 @@ const {
   normalizeSanitizeFieldNames,
   normalizeCloudProvider,
   normalizeCustomMetricsHistogramBoundaries,
+  normalizeTransactionChannels,
   normalizeTransactionSampleRate,
   normalizeTraceContinuationStrategy,
   normalizeContextManager,
@@ -396,6 +397,7 @@ function normalize(opts, logger) {
   normalizeDurationOptions(opts, DURATION_OPTS, defaults, logger);
   normalizeBools(opts, BOOL_OPTS, defaults, logger);
   normalizeIgnoreOptions(opts);
+  normalizeTransactionChannels(opts, [], defaults, logger);
   normalizeElasticsearchCaptureBodyUrls(opts);
   normalizeDisableMetrics(opts);
   normalizeSanitizeFieldNames(opts);

package/lib/config/normalizers.js

@@ -427,6 +427,46 @@ function normalizeIgnoreOptions(opts, fields, defaults, logger) {
   }
 }
 
+/**
+ * Normalizes transactionChannels rules into compiled wildcard matchers.
+ *
+ * Input is an array of { pattern, channel } objects, where `pattern` is a
+ * wildcard expression matched against the transaction name (e.g.
+ * '* unknown route*') and `channel` is the name of the channel to route
+ * matching transactions (and their spans and breakdown metricsets) to.
+ * Compiles to opts.transactionChannelRules: [{ re, channel }]. Invalid
+ * rules are dropped with a warning.
+ *
+ * @param {Record<String, unknown>} opts the configuration options to normalize
+ * @param {String[]} fields the list of fields to normalize (unused)
+ * @param {Record<String, unknown>} defaults the configuration defaults (unused)
+ * @param {import('../logging.js').Logger} logger
+ */
+function normalizeTransactionChannels(opts, fields, defaults, logger) {
+  if (opts.transactionChannels) {
+    opts.transactionChannelRules = [];
+    const wildcard = new WildcardMatcher();
+    for (const rule of opts.transactionChannels) {
+      if (
+        !rule ||
+        typeof rule.pattern !== 'string' ||
+        typeof rule.channel !== 'string' ||
+        !rule.channel
+      ) {
+        logger.warn(
+          'invalid transactionChannels rule (expected { pattern, channel } strings): %j',
+          rule,
+        );
+        continue;
+      }
+      opts.transactionChannelRules.push({
+        re: wildcard.compile(rule.pattern),
+        channel: rule.channel,
+      });
+    }
+  }
+}
+
 /**
  * Normalizes the wildcard matchers of sanitizeFieldNames and thansforms the into RegExps
  *
@@ -640,6 +680,7 @@ module.exports = {
   normalizeKeyValuePairs,
   normalizeNumbers,
   normalizeSanitizeFieldNames,
+  normalizeTransactionChannels,
   normalizeTransactionSampleRate,
   secondsFromDuration,
   normalizeTraceContinuationStrategy,

package/lib/config/schema.js

@@ -361,6 +361,17 @@ const CONFIG_SCHEMA = [
     centralConfigName: 'trace_continuation_strategy',
     crossAgentName: 'trace_continuation_strategy',
   },
+  {
+    name: 'transactionChannels',
+    configType: 'transactionChannelArray',
+    defaultValue: [],
+  },
+  {
+    name: 'transactionChannelRules',
+    configType: 'wildcardChannelRuleArray',
+    defaultValue: [],
+    deps: ['transactionChannels'],
+  },
   {
     name: 'transactionIgnoreUrls',
     configType: 'stringArray',

package/lib/instrumentation/index.js

@@ -710,6 +710,14 @@ Instrumentation.prototype.addEndedTransaction = function (transaction) {
       trans: transaction.id,
       trace: transaction.traceId,
     });
+    // The transaction's name is final now, so held spans can be routed
+    // even though the transaction record itself was dropped.
+    this._drainPendingChannelSpans(
+      transaction,
+      agent._channelForTransactionName(
+        transaction._customName || transaction._defaultName,
+      ),
+    );
     return;
   }
 
@@ -717,7 +725,40 @@ Instrumentation.prototype.addEndedTransaction = function (transaction) {
     trans: transaction.id,
     trace: transaction.traceId,
   });
-  agent._apmClient.sendTransaction(payload);
+  const channel = agent._channelForTransactionName(payload.name);
+  // Spans held while this transaction's name was unresolved follow the
+  // same routing decision as the transaction itself.
+  this._drainPendingChannelSpans(transaction, channel);
+  if (channel && typeof agent._apmClient.sendToChannel === 'function') {
+    agent._apmClient.sendToChannel(channel, 'transaction', payload);
+  } else {
+    agent._apmClient.sendTransaction(payload);
+  }
+};
+
+// Send any span payloads that were held on the transaction because the
+// transaction's name (and so its channel routing) was not yet resolved
+// when the span ended. See `_encodeAndSendSpan`.
+Instrumentation.prototype._drainPendingChannelSpans = function (
+  transaction,
+  channel,
+) {
+  const agent = this._agent;
+  const pending = transaction._pendingChannelSpans;
+  if (!pending) {
+    return;
+  }
+  transaction._pendingChannelSpans = null;
+  if (!agent._apmClient) {
+    return;
+  }
+  for (const payload of pending) {
+    if (channel && typeof agent._apmClient.sendToChannel === 'function') {
+      agent._apmClient.sendToChannel(channel, 'span', payload);
+    } else {
+      agent._apmClient.sendSpan(payload);
+    }
+  }
 };
 
 Instrumentation.prototype.addEndedSpan = function (span) {
@@ -841,7 +882,40 @@ Instrumentation.prototype._encodeAndSendSpan = function (span) {
           type: span.type,
         });
         if (agent._apmClient) {
-          agent._apmClient.sendSpan(payload);
+          // Spans follow their transaction's channel. The transaction name
+          // is only meaningful for routing once *resolved* (custom or
+          // framework-set); the `name` getter must not be used here, since
+          // until the transaction ends it falls back to
+          // '<METHOD> unknown route (unnamed)', which would spuriously
+          // match rules aimed at unmatched-route traffic. When routing is
+          // configured and the name is not yet resolved (e.g. Express only
+          // names transactions when the request finishes), hold the span on
+          // its transaction; addEndedTransaction() drains held spans with
+          // the transaction's final routing decision.
+          const trans = span.transaction;
+          const routingEnabled =
+            agent._conf.transactionChannelRules &&
+            agent._conf.transactionChannelRules.length > 0 &&
+            typeof agent._apmClient.sendToChannel === 'function';
+          if (!routingEnabled) {
+            agent._apmClient.sendSpan(payload);
+          } else {
+            const resolvedName =
+              trans && (trans._customName || trans._defaultName);
+            if (!resolvedName && trans && !trans.ended) {
+              if (!trans._pendingChannelSpans) {
+                trans._pendingChannelSpans = [];
+              }
+              trans._pendingChannelSpans.push(payload);
+            } else {
+              const channel = agent._channelForTransactionName(resolvedName);
+              if (channel) {
+                agent._apmClient.sendToChannel(channel, 'span', payload);
+              } else {
+                agent._apmClient.sendSpan(payload);
+              }
+            }
+          }
         }
       }
     }

package/lib/metrics/reporter.js

@@ -67,7 +67,19 @@ class MetricsReporter extends Reporter {
 
       if (this._agent._apmClient) {
         for (const metric of seen.values()) {
-          this._agent._apmClient.sendMetricSet(metric);
+          // Breakdown metricsets carry the name of the transaction they
+          // were aggregated for; route them to that transaction's channel.
+          const channel = this._agent._channelForTransactionName(
+            metric.transaction && metric.transaction.name,
+          );
+          if (
+            channel &&
+            typeof this._agent._apmClient.sendToChannel === 'function'
+          ) {
+            this._agent._apmClient.sendToChannel(channel, 'metricset', metric);
+          } else {
+            this._agent._apmClient.sendMetricSet(metric);
+          }
         }
       }
     });

package/package.json

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