@redthreadlabs/tracelog 1.4.0 → 1.5.0

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

@@ -717,7 +717,12 @@ Instrumentation.prototype.addEndedTransaction = function (transaction) {
     trans: transaction.id,
     trace: transaction.traceId,
   });
-  agent._apmClient.sendTransaction(payload);
+  const channel = agent._channelForTransactionName(payload.name);
+  if (channel && typeof agent._apmClient.sendToChannel === 'function') {
+    agent._apmClient.sendToChannel(channel, 'transaction', payload);
+  } else {
+    agent._apmClient.sendTransaction(payload);
+  }
 };
 
 Instrumentation.prototype.addEndedSpan = function (span) {
@@ -841,7 +846,17 @@ Instrumentation.prototype._encodeAndSendSpan = function (span) {
           type: span.type,
         });
         if (agent._apmClient) {
-          agent._apmClient.sendSpan(payload);
+          // Spans follow their transaction's channel. The transaction name
+          // may not be final until the transaction ends, so this routing is
+          // best-effort for spans that end before the route is resolved.
+          const channel = agent._channelForTransactionName(
+            span.transaction && span.transaction.name,
+          );
+          if (channel && typeof agent._apmClient.sendToChannel === 'function') {
+            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.0",
   "description": "Node.js APM instrumentation that writes traces to JSONL files",
   "publishConfig": {
     "access": "public"