@redthreadlabs/tracelog 1.4.0

package/lib/agent.js

@@ -0,0 +1,1226 @@
+/*
+ * Copyright Shaxpir Inc. 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.
+ */
+
+'use strict';
+
+const http = require('http');
+const path = require('path');
+
+const isError = require('core-util-is').isError;
+const Filters = require('object-filter-sequence');
+
+const { agentActivationMethodFromStartStack } = require('./activation-method');
+const {
+  CAPTURE_ERROR_LOG_STACK_TRACES_ALWAYS,
+  CAPTURE_ERROR_LOG_STACK_TRACES_MESSAGES,
+} = require('./constants');
+const config = require('./config/config');
+const connect = require('./middleware/connect');
+const constants = require('./constants');
+const errors = require('./errors');
+const { InflightEventSet } = require('./InflightEventSet');
+const { Instrumentation } = require('./instrumentation');
+const logging = require('./logging');
+const Metrics = require('./metrics');
+const parsers = require('./parsers');
+const symbols = require('./symbols');
+const { frameCacheStats, initStackTraceCollection } = require('./stacktraces');
+const Span = require('./instrumentation/span');
+const Transaction = require('./instrumentation/transaction');
+const { createApmClient } = require('./apm-client/apm-client');
+
+const IncomingMessage = http.IncomingMessage;
+const ServerResponse = http.ServerResponse;
+
+const version = require('../package').version;
+
+// ---- Agent
+
+module.exports = Agent;
+
+function Agent() {
+  // Early configuration to ensure `agent.logger` works before `agent.start()`.
+  this.logger = config.configLogger();
+
+  // Get an initial pre-.start() configuration of agent defaults. This is a
+  // crutch for Agent APIs that depend on `agent._conf`.
+  this._conf = config.initialConfig(this.logger);
+
+  this._httpClient = null;
+  this._uncaughtExceptionListener = null;
+  this._inflightEvents = new InflightEventSet();
+  this._instrumentation = new Instrumentation(this);
+  this._metrics = new Metrics(this);
+  this._errorFilters = new Filters();
+  this._transactionFilters = new Filters();
+  this._spanFilters = new Filters();
+  this._eventFilters = new Filters();
+  this._apmClient = null;
+
+  this.middleware = { connect: connect.bind(this) };
+}
+
+Object.defineProperty(Agent.prototype, 'currentTransaction', {
+  get() {
+    return this._instrumentation.currTransaction();
+  },
+});
+
+Object.defineProperty(Agent.prototype, 'currentSpan', {
+  get() {
+    return this._instrumentation.currSpan();
+  },
+});
+
+Object.defineProperty(Agent.prototype, 'currentTraceparent', {
+  get() {
+    const current =
+      this._instrumentation.currSpan() ||
+      this._instrumentation.currTransaction();
+    return current ? current.traceparent : null;
+  },
+});
+
+Object.defineProperty(Agent.prototype, 'currentTraceIds', {
+  get() {
+    return this._instrumentation.ids();
+  },
+});
+
+// Destroy this agent. This prevents any new agent processing, communication
+// with APM server, and resets changed global state *as much as is possible*.
+//
+// In the typical uses case -- a singleton Agent running for the full process
+// lifetime -- it is *not* necessary to call `agent.destroy()`.  It is used
+// for some testing.
+//
+// Limitations:
+// - Patching/wrapping of functions for instrumentation *is* undone, but
+//   references to the wrapped versions can remain.
+// - There may be in-flight tasks (in ins.addEndedSpan() and
+//   agent.captureError() for example) that will complete after this destroy
+//   completes. They should have no impact other than CPU/resource use.
+Agent.prototype.destroy = async function () {
+  if (this._apmClient && this._apmClient.destroy) {
+    this._apmClient.destroy();
+  }
+  // So in-flight tasks in ins.addEndedSpan() and agent.captureError() do
+  // not use the destroyed transport.
+  this._apmClient = null;
+
+  // So in-flight tasks do not call user-added filters after the agent has
+  // been destroyed.
+  this._errorFilters = new Filters();
+  this._transactionFilters = new Filters();
+  this._spanFilters = new Filters();
+  this._eventFilters = new Filters();
+
+  if (this._uncaughtExceptionListener) {
+    process.removeListener(
+      'uncaughtException',
+      this._uncaughtExceptionListener,
+    );
+  }
+  this._metrics.stop();
+  this._instrumentation.stop();
+
+  // Allow a new Agent instance to `.start()`. Typically this is only relevant
+  // for tests that may use multiple Agent instances in a single test process.
+  global[symbols.agentInitialized] = null;
+
+  if (
+    this._origStackTraceLimit &&
+    Error.stackTraceLimit !== this._origStackTraceLimit
+  ) {
+    Error.stackTraceLimit = this._origStackTraceLimit;
+  }
+};
+
+// These are metrics about the agent itself -- separate from the metrics
+// gathered on behalf of the using app and sent to APM server. Currently these
+// are only useful for internal debugging of the APM agent itself.
+//
+// **These stats are NOT a promised interface.**
+Agent.prototype._getStats = function () {
+  const stats = {
+    frameCache: frameCacheStats,
+  };
+  if (
+    this._instrumentation._runCtxMgr &&
+    this._instrumentation._runCtxMgr._runContextFromAsyncId
+  ) {
+    stats.runContextFromAsyncIdSize =
+      this._instrumentation._runCtxMgr._runContextFromAsyncId.size;
+  }
+  if (this._apmClient && typeof this._apmClient._getStats === 'function') {
+    stats.apmclient = this._apmClient._getStats();
+  }
+  return stats;
+};
+
+Agent.prototype.addPatch = function (modules, handler) {
+  return this._instrumentation.addPatch.apply(this._instrumentation, arguments);
+};
+
+Agent.prototype.removePatch = function (modules, handler) {
+  return this._instrumentation.removePatch.apply(
+    this._instrumentation,
+    arguments,
+  );
+};
+
+Agent.prototype.clearPatches = function (modules) {
+  return this._instrumentation.clearPatches.apply(
+    this._instrumentation,
+    arguments,
+  );
+};
+
+Agent.prototype.startTransaction = function (
+  name,
+  type,
+  { startTime, childOf } = {},
+) {
+  return this._instrumentation.startTransaction.apply(
+    this._instrumentation,
+    arguments,
+  );
+};
+
+Agent.prototype.endTransaction = function (result, endTime) {
+  return this._instrumentation.endTransaction.apply(
+    this._instrumentation,
+    arguments,
+  );
+};
+
+Agent.prototype.setTransactionName = function (name) {
+  return this._instrumentation.setTransactionName.apply(
+    this._instrumentation,
+    arguments,
+  );
+};
+
+/**
+ * Sets outcome value for current transaction
+ *
+ * The setOutcome method allows users to override the default
+ * outcome handling in the agent and set their own value.
+ *
+ * @param {string} outcome must be one of `failure`, `success`, or `unknown`
+ */
+Agent.prototype.setTransactionOutcome = function (outcome) {
+  return this._instrumentation.setTransactionOutcome.apply(
+    this._instrumentation,
+    arguments,
+  );
+};
+
+Agent.prototype.startSpan = function (
+  name,
+  type,
+  subtype,
+  action,
+  { startTime, childOf, exitSpan } = {},
+) {
+  return this._instrumentation.startSpan.apply(
+    this._instrumentation,
+    arguments,
+  );
+};
+
+/**
+ * Sets outcome value for current active span
+ *
+ * The setOutcome method allows users to override the default
+ * outcome handling in the agent and set their own value.
+ *
+ * @param {string} outcome must be one of `failure`, `success`, or `unknown`
+ */
+Agent.prototype.setSpanOutcome = function (outcome) {
+  return this._instrumentation.setSpanOutcome.apply(
+    this._instrumentation,
+    arguments,
+  );
+};
+
+Agent.prototype._config = function (opts) {
+  this._conf = config.createConfig(opts, this.logger);
+  this.logger = this._conf.logger;
+};
+
+Agent.prototype.isStarted = function () {
+  return global[symbols.agentInitialized];
+};
+
+Agent.prototype.start = function (opts) {
+  if (this.isStarted()) {
+    throw new Error('Do not call .start() more than once');
+  }
+  global[symbols.agentInitialized] = true;
+
+  this._config(opts);
+
+  if (!this._conf.active) {
+    this.logger.debug('Tracelog agent disabled (`active` is false)');
+    return this;
+  }
+
+  // Log preamble showing agent, environment and config relevant info
+  const preambleData = this._conf.loggingPreambleData;
+  const isPreviewVersion = version.indexOf('-') !== -1;
+  const startStack = {};
+
+  if (this._conf.active && this._conf.serviceName) {
+    this._origStackTraceLimit = Error.stackTraceLimit;
+    Error.stackTraceLimit = 20; // require more than default 10 for `agentActivationMethodFromStartStack()`
+    Error.captureStackTrace(startStack);
+    Error.stackTraceLimit = this._origStackTraceLimit;
+    this._agentActivationMethod = agentActivationMethodFromStartStack(
+      startStack,
+      this.logger,
+    );
+    preambleData.activationMethod = this._agentActivationMethod;
+
+    if (this._conf.logLevel === 'trace') {
+      // Attempt to load package.json from process.argv.
+      let pkg = null;
+      try {
+        var basedir = path.dirname(process.argv[1] || '.');
+        pkg = require(path.join(basedir, 'package.json'));
+      } catch (e) {}
+
+      // Add stack & dependencies for extra information
+      preambleData.dependencies = pkg
+        ? pkg.dependencies
+        : '<could not determine>';
+      preambleData.startTrace = startStack.stack.split(/\n */).slice(1);
+    }
+  }
+
+  this.logger.info(preambleData, 'Tracelog v%s', version);
+
+  if (!logging.isLoggerCustom(this.logger)) {
+    // Periodically dump the current config (delta from defaults) when logging
+    // at "trace"-level. This allows getting the effective config from a running
+    // agent by setting trace-level logging and getting 1 minute of logs.
+    // (Sometimes getting logs from application *start* is no possible.)
+    setInterval(() => {
+      if (this.logger.isLevelEnabled('trace')) {
+        try {
+          const currConfig = this._conf.getCurrConfig();
+          this.logger.trace({ currConfig }, 'currConfig');
+        } catch (err) {
+          this.logger.trace({ err }, 'error calculating currConfig');
+        }
+      }
+    }, 60 * 1000).unref();
+  }
+
+  if (isPreviewVersion) {
+    this.logger.warn(
+      'Version %s is a pre-release and not intended for use in production environments',
+      version,
+    );
+  }
+
+  if (!this._conf.serviceName) {
+    this.logger.error(
+      'Tracelog is incorrectly configured: Missing serviceName (tracing will be disabled)',
+    );
+    this._conf.active = false;
+    return this;
+  }
+
+  initStackTraceCollection();
+  this._apmClient = createApmClient(this._conf, this);
+
+  this._instrumentation.start();
+
+  if (this._isMetricsEnabled()) {
+    this._metrics.start();
+  }
+
+  Error.stackTraceLimit = this._conf.stackTraceLimit;
+  if (this._conf.captureExceptions) this.handleUncaughtExceptions();
+
+  return this;
+};
+
+Agent.prototype._isMetricsEnabled = function () {
+  return this._conf.metricsInterval !== 0 && !this._conf.contextPropagationOnly;
+};
+
+Agent.prototype.getServiceName = function () {
+  return this._conf ? this._conf.serviceName : undefined;
+};
+
+Agent.prototype.getServiceVersion = function () {
+  return this._conf ? this._conf.serviceVersion : undefined;
+};
+
+Agent.prototype.getServiceEnvironment = function () {
+  return this._conf ? this._conf.environment : undefined;
+};
+
+Agent.prototype.getServiceNodeName = function () {
+  return this._conf ? this._conf.serviceNodeName : undefined;
+};
+
+Agent.prototype.setFramework = function ({ name, version, overwrite = true }) {
+  if (!this._apmClient || !this._conf) {
+    return;
+  }
+  const conf = {};
+  if (name && (overwrite || !this._conf.frameworkName))
+    this._conf.frameworkName = conf.frameworkName = name;
+  if (version && (overwrite || !this._conf.frameworkVersion))
+    this._conf.frameworkVersion = conf.frameworkVersion = version;
+  this._apmClient.config(conf);
+};
+
+Agent.prototype.setUserContext = function (context) {
+  var trans = this._instrumentation.currTransaction();
+  if (!trans) return false;
+  trans.setUserContext(context);
+  return true;
+};
+
+Agent.prototype.setCustomContext = function (context) {
+  var trans = this._instrumentation.currTransaction();
+  if (!trans) return false;
+  trans.setCustomContext(context);
+  return true;
+};
+
+Agent.prototype.setGlobalLabel = function (key, value) {
+  if (!this._conf.globalLabels) this._conf.globalLabels = [];
+  const foundPos = this._conf.globalLabels.findIndex(([name]) => key === name);
+  if (foundPos > -1) {
+    this._conf.globalLabels[foundPos][1] = value;
+  } else {
+    this._conf.globalLabels.push([key, value]);
+  }
+  if (!this._apmClient) {
+    this.logger.warn('cannot setGlobalLabel on inactive or unconfigured agent');
+    return;
+  }
+  this._apmClient.config({
+    globalLabels: this._conf.globalLabels.reduce((acc, [k, v]) => {
+      acc[k] = v;
+      return acc;
+    }, {}),
+  });
+};
+
+Agent.prototype.setLabel = function (key, value, stringify) {
+  var trans = this._instrumentation.currTransaction();
+  if (!trans) return false;
+  return trans.setLabel(key, value, stringify);
+};
+
+Agent.prototype.addLabels = function (labels, stringify) {
+  var trans = this._instrumentation.currTransaction();
+  if (!trans) return false;
+  return trans.addLabels(labels, stringify);
+};
+
+Agent.prototype.addFilter = function (fn) {
+  this.addErrorFilter(fn);
+  this.addTransactionFilter(fn);
+  this.addSpanFilter(fn);
+  this.addEventFilter(fn);
+  // Note: This does *not* add to *metadata* filters, partly for backward
+  // compat -- the structure of metadata objects is quite different and could
+  // break existing filters -- and partly because that different structure
+  // means it makes less sense to re-use the same function to filter them.
+};
+
+Agent.prototype.addErrorFilter = function (fn) {
+  if (typeof fn !== 'function') {
+    this.logger.error("Can't add filter of type %s", typeof fn);
+    return;
+  }
+
+  this._errorFilters.push(fn);
+};
+
+Agent.prototype.addTransactionFilter = function (fn) {
+  if (typeof fn !== 'function') {
+    this.logger.error("Can't add filter of type %s", typeof fn);
+    return;
+  }
+
+  this._transactionFilters.push(fn);
+};
+
+Agent.prototype.addSpanFilter = function (fn) {
+  if (typeof fn !== 'function') {
+    this.logger.error("Can't add filter of type %s", typeof fn);
+    return;
+  }
+
+  this._spanFilters.push(fn);
+};
+
+Agent.prototype.addEventFilter = function (fn) {
+  if (typeof fn !== 'function') {
+    this.logger.error("Can't add filter of type %s", typeof fn);
+    return;
+  }
+
+  this._eventFilters.push(fn);
+};
+
+Agent.prototype.addMetadataFilter = function (fn) {
+  if (typeof fn !== 'function') {
+    this.logger.error("Can't add filter of type %s", typeof fn);
+    return;
+  } else if (!this._apmClient) {
+    this.logger.error(
+      'cannot add metadata filter to inactive or unconfigured agent (agent has no transport)',
+    );
+    return;
+  } else if (typeof this._apmClient.addMetadataFilter !== 'function') {
+    // Graceful failure if unexpectedly using a too-old APM client.
+    this.logger.error(
+      'cannot add metadata filter: transport does not support addMetadataFilter',
+    );
+    return;
+  }
+
+  // Metadata filters are handled by the APM client, where metadata is
+  // processed.
+  this._apmClient.addMetadataFilter(fn);
+};
+
+const EMPTY_OPTS = {};
+
+// Capture an APM server "error" event for the given `err` and send it to APM
+// server.
+//
+// Usage:
+//    captureError(err, opts, cb)
+//    captureError(err, opts)
+//    captureError(err, cb)
+//
+// where:
+// - `err` is an Error instance, or a string message, or a "parameterized string
+//   message" object, e.g.:
+//      {
+//        message: "this is my message template: %d %s"},
+//        params: [ 42, "another param" ]
+//      }
+// - `opts` can include any of the following (all optional):
+//   - `opts.timestamp` - Milliseconds since the Unix epoch. Defaults to now.
+//   - `opts.user` - Object to add to `error.context.user`.
+//   - `opts.tags` - Deprecated, use `opts.labels`. Object to add to
+//     `error.context.labels`.
+//   - `opts.labels` - Object to add to `error.context.labels`.
+//   - `opts.custom` - Object to add to `error.context.custom`.
+//   - `opts.message` - If `err` is an Error instance, this string is added to
+//     `error.log.message` (unless it matches err.message).
+//   - `opts.request` - HTTP request (node `IncomingMessage` instance) to use
+//     for `error.context.request`. If not given, a `req` on the parent
+//     transaction (see `opts.parent` below) will be used.
+//   - `opts.response` - HTTP response (node `ServerResponse` instance) to use
+//     for `error.context.response`. If not given, a `res` on the parent
+//     transaction (see `opts.parent` below) will be used.
+//   - `opts.handled` - Boolean indicating if this exception was handled by
+//     application code. Default true. Setting to `false` also results in the
+//     error being flushed to APM server as soon as it is processed.
+//   - `opts.captureAttributes` - Boolean. Default true. Set to false to *not*
+//     include properties of `err` as attributes on the APM error event.
+//   - `opts.skipOutcome` - Boolean. Default false. Set to true to not have
+//     this captured error set `<currentSpan>.outcome = failure`.
+//   - `opts.parent` - A Transaction or Span instance to make the parent of
+//     this error. If not given (undefined), then the current span or
+//     transaction will be used. If `null` is given, then no span or transaction
+//     will be used.
+//   - `opts.exceptionType` - A string to use for `error.exception.type`. By
+//     default this is `err.name`. This option is only relevant if `err` is an
+//     Error instance.
+// - `cb` is a callback `function (captureErr, apmErrorIdString)`. If provided,
+//   the error will be flushed to APM server as soon as it is processed, and
+//   `cb` will be called when that send is complete.
+Agent.prototype.writeError = function (err, opts, cb) {
+  if (typeof opts === 'function') {
+    cb = opts;
+    opts = EMPTY_OPTS;
+  } else if (!opts) {
+    opts = EMPTY_OPTS;
+  }
+
+  const id = errors.generateErrorId();
+
+  if (!this.isStarted()) {
+    if (cb) {
+      cb(new Error('cannot capture error before agent is started'), id);
+    }
+    return;
+  }
+
+  // Avoid unneeded error/stack processing if only propagating trace-context.
+  if (this._conf.contextPropagationOnly) {
+    if (cb) {
+      process.nextTick(cb, null, id);
+    }
+    return;
+  }
+
+  const agent = this;
+  let callSiteLoc = null;
+  const errIsError = isError(err);
+  const handled = opts.handled !== false; // default true
+  const shouldCaptureAttributes = opts.captureAttributes !== false; // default true
+  const skipOutcome = Boolean(opts.skipOutcome);
+  const timestampUs = opts.timestamp
+    ? Math.floor(opts.timestamp * 1000)
+    : Date.now() * 1000;
+
+  // Determine transaction/span context to associate with this error.
+  let parent;
+  let span;
+  let trans;
+  if (opts.parent === undefined) {
+    parent =
+      this._instrumentation.currSpan() ||
+      this._instrumentation.currTransaction();
+  } else if (opts.parent === null) {
+    parent = null;
+  } else {
+    parent = opts.parent;
+  }
+  if (parent instanceof Transaction) {
+    span = null;
+    trans = parent;
+  } else if (parent instanceof Span) {
+    span = parent;
+    trans = parent.transaction;
+  }
+  const traceContext = (span || trans || {})._context;
+  const req =
+    opts.request instanceof IncomingMessage ? opts.request : trans && trans.req;
+  const res =
+    opts.response instanceof ServerResponse
+      ? opts.response
+      : trans && trans.res;
+
+  // As an added feature, for *some* cases, we capture a stacktrace at the point
+  // this `captureError` was called. This is added to `error.log.stacktrace`.
+  if (
+    handled &&
+    (agent._conf.captureErrorLogStackTraces ===
+      CAPTURE_ERROR_LOG_STACK_TRACES_ALWAYS ||
+      (!errIsError &&
+        agent._conf.captureErrorLogStackTraces ===
+          CAPTURE_ERROR_LOG_STACK_TRACES_MESSAGES))
+  ) {
+    callSiteLoc = {};
+    Error.captureStackTrace(callSiteLoc, Agent.prototype.writeError);
+  }
+
+  if (span && !skipOutcome) {
+    span._setOutcomeFromErrorCapture(constants.OUTCOME_FAILURE);
+  }
+
+  // Note this error as an "inflight" event. See Agent#flush().
+  const inflightEvents = this._inflightEvents;
+  inflightEvents.add(id);
+
+  // Move the remaining captureError processing to a later tick because:
+  // 1. This allows the calling code to continue processing. For example, for
+  //    Express instrumentation this can significantly improve latency in
+  //    the app's endpoints because the response does not proceed until the
+  //    error handlers return.
+  // 2. Gathering `error.context.response` in the same tick results in data
+  //    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),
+    };
+    if (req) {
+      errorContext.request = parsers.getContextFromRequest(
+        req,
+        agent._conf,
+        'errors',
+      );
+    }
+    if (res) {
+      errorContext.response = parsers.getContextFromResponse(
+        res,
+        agent._conf,
+        true,
+      );
+    }
+
+    errors.createAPMError(
+      {
+        log: agent.logger,
+        id,
+        exception: errIsError ? err : null,
+        logMessage: errIsError ? null : err,
+        shouldCaptureAttributes,
+        timestampUs,
+        handled,
+        callSiteLoc,
+        message: opts.message,
+        sourceLinesAppFrames: agent._conf.sourceLinesErrorAppFrames,
+        sourceLinesLibraryFrames: agent._conf.sourceLinesErrorLibraryFrames,
+        trans,
+        traceContext,
+        errorContext,
+        exceptionType: opts.exceptionType,
+      },
+      function filterAndSendError(_err, apmError) {
+        // _err is always null from createAPMError.
+
+        apmError = agent._errorFilters.process(apmError);
+        if (!apmError) {
+          agent.logger.debug('error ignored by filter %o', { id });
+          inflightEvents.delete(id);
+          if (cb) {
+            cb(null, id);
+          }
+          return;
+        }
+
+        if (agent._apmClient) {
+          agent.logger.debug('Sending error to tracelog: %o', { id });
+          agent._apmClient.sendError(apmError);
+          inflightEvents.delete(id);
+          if (!handled || cb) {
+            // Immediately flush *unhandled* errors -- those from
+            // `uncaughtException` -- on the assumption that the process may
+            // soon crash. Also flush when a `cb` is provided.
+            agent.flush(function (flushErr) {
+              if (cb) {
+                cb(flushErr, id);
+              }
+            });
+          }
+        } else {
+          inflightEvents.delete(id);
+          if (cb) {
+            cb(new Error('cannot send error: missing transport'), id);
+          }
+        }
+      },
+    );
+  });
+};
+
+// Capture an arbitrary custom event.
+//
+// Usage:
+//    captureEvent(type, opts)
+//    captureEvent(type, opts, cb)
+//
+// - `type` {string} - Event type/category (e.g. 'page_view', 'purchase').
+// - `opts` {Object} - Event data:
+//   - `message` {string} - Human-readable description.
+//   - `level` {string} - Severity: 'debug', 'info', 'warn', 'error', 'fatal'.
+//   - `timestamp` {number} - Unix epoch ms. Defaults to Date.now().
+//   - `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.
+//   - `user` {Object} - End-user identity: { id, email, username }.
+//   - `client` {Object} - Client environment: { name, version, os, device, runtime }.
+//   - `params` {Object} - Arbitrary key-value data.
+// - `cb` {Function} - Optional callback, called after the event is buffered.
+Agent.prototype.writeEvent = function (type, opts, cb) {
+  if (typeof opts === 'function') {
+    cb = opts;
+    opts = {};
+  } else if (!opts) {
+    opts = {};
+  }
+
+  if (!this.isStarted()) {
+    if (cb) {
+      cb(new Error('cannot write event before agent is started'));
+    }
+    return;
+  }
+
+  if (this._conf.contextPropagationOnly) {
+    if (cb) {
+      process.nextTick(cb);
+    }
+    return;
+  }
+
+  if (this._apmClient) {
+    const event = this._eventFilters.process(_buildEvent(type, opts));
+    if (event) {
+      this._apmClient.sendEvent(event);
+    }
+  }
+
+  // If an error was provided, also emit a full error record
+  if (opts.error != null) {
+    this.writeError(opts.error);
+  }
+
+  if (cb) {
+    process.nextTick(cb);
+  }
+};
+
+// Capture a batch of custom events at once. Designed for server endpoints
+// that receive batches of events from client devices (mobile apps, browsers).
+//
+// Usage:
+//    captureEvents(events)
+//    captureEvents(events, cb)
+//
+// - `events` {Array<Object>} - Each element must have a `type` and may include
+//   the same fields as `captureEvent` opts: message, level, timestamp, duration,
+//   user, client, params.
+// - `cb` {Function} - Optional callback, called after all events are buffered.
+Agent.prototype.writeEvents = function (events, cb) {
+  if (!Array.isArray(events) || events.length === 0) {
+    if (cb) process.nextTick(cb);
+    return;
+  }
+
+  if (!this.isStarted()) {
+    if (cb) {
+      cb(new Error('cannot write events before agent is started'));
+    }
+    return;
+  }
+
+  if (this._conf.contextPropagationOnly) {
+    if (cb) {
+      process.nextTick(cb);
+    }
+    return;
+  }
+
+  if (this._apmClient) {
+    for (const item of events) {
+      const event = this._eventFilters.process(_buildEvent(item.type, item));
+      if (event) {
+        this._apmClient.sendEvent(event);
+      }
+    }
+  }
+
+  if (cb) {
+    process.nextTick(cb);
+  }
+};
+
+// --- Channels ---
+//
+// A Channel routes records to a named JSONL file. The agent itself is
+// the default channel ('server'). Named channels are created lazily via
+// getChannel(name) and write to separate files (e.g. tracelog-client-*.jsonl).
+
+/**
+ * Get a named channel. Returns an object with writeEvent, writeEvents,
+ * writeError, writeTransaction, and writeSpan methods that route to the
+ * named channel's JSONL file.
+ */
+Agent.prototype.getChannel = function (name) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Channel name must be a non-empty string');
+  }
+  return new Channel(this, name);
+};
+
+function Channel(agent, name) {
+  this._agent = agent;
+  this._name = name;
+}
+
+Channel.prototype.writeEvent = function (type, opts, cb) {
+  if (typeof opts === 'function') {
+    cb = opts;
+    opts = {};
+  } else if (!opts) {
+    opts = {};
+  }
+
+  if (!this._agent.isStarted() || !this._agent._apmClient) {
+    if (cb) process.nextTick(cb);
+    return;
+  }
+
+  const event = this._agent._eventFilters.process(_buildEvent(type, opts));
+  if (event) {
+    this._agent._apmClient.sendToChannel(this._name, 'event', event);
+  }
+
+  if (opts.error != null) {
+    this._agent.writeError(opts.error);
+  }
+
+  if (cb) process.nextTick(cb);
+};
+
+Channel.prototype.writeEvents = function (events, cb) {
+  if (!Array.isArray(events) || events.length === 0) {
+    if (cb) process.nextTick(cb);
+    return;
+  }
+
+  if (!this._agent.isStarted() || !this._agent._apmClient) {
+    if (cb) process.nextTick(cb);
+    return;
+  }
+
+  for (const item of events) {
+    const event = this._agent._eventFilters.process(_buildEvent(item.type, item));
+    if (event) {
+      this._agent._apmClient.sendToChannel(this._name, 'event', event);
+    }
+  }
+
+  if (cb) process.nextTick(cb);
+};
+
+Channel.prototype.writeError = function (err, opts, cb) {
+  // Delegate to the agent (errors always go to the default channel)
+  this._agent.writeError(err, opts, cb);
+};
+
+Channel.prototype.writeTransaction = function (input) {
+  if (!this._agent._apmClient || !input) return;
+  const transaction = _validateTransaction(input);
+  if (transaction) {
+    this._agent._apmClient.sendToChannel(this._name, 'transaction', transaction);
+  }
+};
+
+Channel.prototype.writeSpan = function (input) {
+  if (!this._agent._apmClient || !input) return;
+  const span = _validateSpan(input);
+  if (span) {
+    this._agent._apmClient.sendToChannel(this._name, 'span', span);
+  }
+};
+
+// --- Write transaction/span on the default channel ---
+
+// Write a validated transaction record to the default channel.
+Agent.prototype.writeTransaction = function (input) {
+  if (!this._apmClient || !input) return;
+  const transaction = _validateTransaction(input);
+  if (transaction) {
+    this._apmClient.sendTransaction(transaction);
+  }
+};
+
+// Write a validated span record to the default channel.
+Agent.prototype.writeSpan = function (input) {
+  if (!this._apmClient || !input) return;
+  const span = _validateSpan(input);
+  if (span) {
+    this._apmClient.sendSpan(span);
+  }
+};
+
+// Backward compat aliases
+Agent.prototype.captureEvent = Agent.prototype.writeEvent;
+Agent.prototype.captureEvents = Agent.prototype.writeEvents;
+Agent.prototype.captureError = Agent.prototype.writeError;
+Agent.prototype.writeClientTransaction = Agent.prototype.writeTransaction;
+Agent.prototype.writeClientSpan = Agent.prototype.writeSpan;
+
+// --- Validation helpers for transaction/span records ---
+
+const HEX_16 = /^[0-9a-f]{16}$/;
+const HEX_32 = /^[0-9a-f]{32}$/;
+const VALID_OUTCOMES = ['success', 'failure', 'unknown'];
+
+function _validateTransaction(input) {
+  const id = typeof input.id === 'string' && HEX_16.test(input.id) ? input.id : null;
+  const trace_id = typeof input.trace_id === 'string' && HEX_32.test(input.trace_id) ? input.trace_id : null;
+  if (!id || !trace_id) return null;
+
+  const transaction = {
+    id,
+    trace_id,
+    timestamp: typeof input.timestamp === 'number' && isFinite(input.timestamp) ? Math.floor(input.timestamp) : Date.now() * 1000,
+    outcome: VALID_OUTCOMES.includes(input.outcome) ? input.outcome : 'unknown',
+    sampled: input.sampled === true,
+    span_count: { started: typeof input.span_count?.started === 'number' ? input.span_count.started : 0 },
+  };
+
+  if (typeof input.name === 'string') transaction.name = input.name.slice(0, 1024);
+  if (typeof input.type === 'string') transaction.type = input.type.slice(0, 1024);
+  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 (input.context && typeof input.context === 'object') {
+    const ctx = _sanitizeContext(input.context);
+    if (ctx) transaction.context = ctx;
+  }
+
+  return transaction;
+}
+
+function _validateSpan(input) {
+  const id = typeof input.id === 'string' && HEX_16.test(input.id) ? input.id : null;
+  const trace_id = typeof input.trace_id === 'string' && HEX_32.test(input.trace_id) ? input.trace_id : null;
+  const transaction_id = typeof input.transaction_id === 'string' && HEX_16.test(input.transaction_id) ? input.transaction_id : null;
+  const parent_id = typeof input.parent_id === 'string' && HEX_16.test(input.parent_id) ? input.parent_id : null;
+  if (!id || !trace_id || !transaction_id || !parent_id) return null;
+
+  const span = {
+    id,
+    trace_id,
+    transaction_id,
+    parent_id,
+    timestamp: typeof input.timestamp === 'number' && isFinite(input.timestamp) ? Math.floor(input.timestamp) : Date.now() * 1000,
+    sync: input.sync === true,
+    outcome: VALID_OUTCOMES.includes(input.outcome) ? input.outcome : 'unknown',
+  };
+
+  if (typeof input.name === 'string') span.name = input.name.slice(0, 1024);
+  if (typeof input.type === 'string') span.type = input.type.slice(0, 1024);
+  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 (input.context && typeof input.context === 'object') {
+    const ctx = _sanitizeContext(input.context);
+    if (ctx) span.context = ctx;
+  }
+
+  return span;
+}
+
+// Sanitize the context object for client-originated records.
+// Only allows tags (with primitive values) and user (with string fields).
+function _sanitizeContext(ctx) {
+  const result = {};
+
+  if (ctx.tags && typeof ctx.tags === 'object') {
+    const tags = {};
+    for (const [k, v] of Object.entries(ctx.tags)) {
+      if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+        tags[k] = v;
+      }
+    }
+    if (Object.keys(tags).length > 0) result.tags = tags;
+  }
+
+  if (ctx.user && typeof ctx.user === 'object') {
+    const user = {};
+    if (typeof ctx.user.id === 'string') user.id = ctx.user.id;
+    if (typeof ctx.user.email === 'string') user.email = ctx.user.email;
+    if (typeof ctx.user.username === 'string') user.username = ctx.user.username;
+    if (Object.keys(user).length > 0) result.user = user;
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function _buildEvent(type, opts) {
+  const event = {
+    type: type || 'custom',
+    timestamp: opts.timestamp || Date.now(),
+  };
+  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);
+    }
+  }
+  return event;
+}
+
+// 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
+// remember to terminate the process manually.
+Agent.prototype.handleUncaughtExceptions = function (cb) {
+  var agent = this;
+
+  if (this._uncaughtExceptionListener) {
+    process.removeListener(
+      'uncaughtException',
+      this._uncaughtExceptionListener,
+    );
+  }
+
+  this._uncaughtExceptionListener = function (err) {
+    agent.logger.debug({ err }, 'Tracelog caught unhandled exception');
+    // This somewhat mimics Node.js's core printing of the error to stderr, but
+    // is not quite the same output. Compare to:
+    // https://github.com/nodejs/node/blob/v20.5.0/src/node_errors.cc#L246-L266
+    console.error(err);
+
+    agent.captureError(err, { handled: false }, function () {
+      cb ? cb(err) : process.exit(1);
+    });
+  };
+
+  process.on('uncaughtException', this._uncaughtExceptionListener);
+};
+
+// Flush all ended APM events (transactions, spans, errors, metricsets) to APM
+// server as soon as possible. If the optional `cb` is given, it will be called
+// `cb(flushErr)` when this is complete. If no `cb` is given, then a `Promise`
+// will be returned, which will either resolve with `void` or reject with
+// `flushErr`.
+//
+// Encoding and passing event data to the agent's transport is *asynchronous*
+// for some event types: spans and errors. This flush will make a *best effort*
+// attempt to wait for those "inflight" events to finish processing before
+// flushing data to APM server. To avoid `.flush()` hanging, this times out
+// after one second.
+//
+// If flush is called while still waiting for inflight events in an earlier
+// flush call, then the more recent flush will only wait for events that were
+// newly inflight *since the last .flush()* call. I.e. the second flush does
+// *not* wait for the set of events the first flush is waiting on. This makes
+// the semantics of flush less than ideal (one cannot blindly call .flush() to
+// flush *everything* that has come before). However it handles the common use
+// case of flushing synchronously after ending a span or capturing an error:
+//    mySpan.end()
+//    await apm.flush()
+// and it simplifies the implementation.
+//
+// # Dev Notes
+//
+// To support the implementation, agent code that creates an inflight event
+// must do the following:
+// - Take a reference to the current set of inflight events:
+//      const inflightEvents = agent._inflightEvents
+// - Add a unique ID for the event to the set:
+//      inflightEvents.add(id)
+// - Delete the ID from the set when sent to the transport (`.sendSpan(...)` et
+//   al) or when dropping the event (e.g. because of a filter):
+//      inflightEvents.delete(id)
+Agent.prototype.flush = function (cb) {
+  // This 1s timeout is a subjective balance between "long enough for spans
+  // and errors to reasonably encode" and "short enough to not block data
+  // being reported to APM server".
+  const DEFAULT_INFLIGHT_FLUSH_TIMEOUT_MS = 1000;
+
+  // shared options for the private `._flush()` API.
+  const opts = { inflightTimeoutMs: DEFAULT_INFLIGHT_FLUSH_TIMEOUT_MS };
+
+  if (typeof cb !== 'function') {
+    return new Promise((resolve, reject) => {
+      this._flush(opts, (err) => {
+        if (err) {
+          reject(err);
+        }
+
+        resolve();
+      });
+    });
+  }
+
+  return this._flush(opts, cb);
+};
+
+// The internal-use `.flush()` that supports some options not exposed to the
+// public API.
+//
+// @param {Number} opts.inflightTimeoutMs - Required. The number of ms to wait
+//    for inflight events (spans, errors) to finish being send to the transport
+//    before flushing.
+Agent.prototype._flush = function (opts, cb) {
+  if (!this._apmClient) {
+    // Log an *err* to provide a stack for the user.
+    const err = new Error('cannot flush agent before it is started');
+    this.logger.warn({ err }, err.message);
+    if (cb) {
+      process.nextTick(cb);
+    }
+    return;
+  }
+
+  const boundCb = cb && this._instrumentation.bindFunction(cb);
+
+  // If there are no inflight events then avoid creating additional objects.
+  if (this._inflightEvents.size === 0) {
+    this._apmClient.flush(boundCb);
+    return;
+  }
+
+  // Otherwise, there are inflight events to wait for.  Setup a handler to
+  // callback when the current set of inflight events complete.
+  const flushingInflightEvents = this._inflightEvents;
+  flushingInflightEvents.setDrainHandler((drainErr) => {
+    // The only possible drainErr is a timeout. This is best effort, so we only
+    // log this and move on.
+    this.logger.debug(
+      {
+        numRemainingInflightEvents: flushingInflightEvents.size,
+        err: drainErr,
+      },
+      'flush: drained inflight events',
+    );
+
+    // Then, flush the intake request to APM server.
+    this._apmClient.flush(boundCb);
+  }, opts.inflightTimeoutMs);
+
+  // Create a new empty set to collect subsequent inflight events.
+  this._inflightEvents = new InflightEventSet();
+};
+
+Agent.prototype.registerMetric = function (name, labelsOrCallback, callback) {
+  var labels;
+  if (typeof labelsOrCallback === 'function') {
+    callback = labelsOrCallback;
+  } else {
+    labels = labelsOrCallback;
+  }
+
+  if (typeof callback !== 'function') {
+    this.logger.error("Can't add callback of type %s", typeof callback);
+    return;
+  }
+
+  this._metrics.getOrCreateGauge(name, callback, labels);
+};
+
+/**
+ * Return true iff the given metric name is "disabled", according to the
+ * `disableMetrics` config var.
+ *
+ * @returns {boolean}
+ */
+Agent.prototype._isMetricNameDisabled = function (name) {
+  const regexps = this._conf.disableMetricsRegExp;
+  for (var i = 0; i < regexps.length; i++) {
+    if (regexps[i].test(name)) {
+      return true;
+    }
+  }
+  return false;
+};