@depup/elastic-apm-node 4.15.0-depup.0

package/lib/agent.js

@@ -0,0 +1,941 @@
+/*
+ * Copyright 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 { elasticApmAwsLambda } = require('./lambda');
+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 {
+  isOTelMetricsFeatSupported,
+  createOTelMeterProvider,
+} = require('./opentelemetry-metrics');
+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._otelMeterProvider = null;
+  this._errorFilters = new Filters();
+  this._transactionFilters = new Filters();
+  this._spanFilters = new Filters();
+  this._apmClient = null;
+
+  this.lambda = elasticApmAwsLambda(this);
+  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._otelMeterProvider) {
+    // This will call `Agent#flush()`.
+    try {
+      await this._otelMeterProvider.shutdown({ timeoutMillis: 1000 });
+    } catch (reason) {
+      this.logger.warn('failed to shutdown OTel MeterProvider:', reason);
+    }
+    this._otelMeterProvider = null;
+  }
+
+  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();
+
+  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('Elastic APM 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, 'Elastic APM Node.js Agent 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.serverUrl) {
+    this.logger.error(
+      'Elastic APM is incorrectly configured: Invalid serverUrl (APM will be disabled)',
+    );
+    this._conf.active = false;
+    return this;
+  }
+
+  if (!this._conf.serviceName) {
+    this.logger.error(
+      'Elastic APM is incorrectly configured: Missing serviceName (APM will be disabled)',
+    );
+    this._conf.active = false;
+    return this;
+  }
+
+  initStackTraceCollection();
+  this._apmClient = createApmClient(this._conf, this);
+
+  let runContextClass;
+  if (this._conf.opentelemetryBridgeEnabled) {
+    const {
+      setupOTelBridge,
+      OTelBridgeRunContext,
+    } = require('./opentelemetry-bridge');
+    runContextClass = OTelBridgeRunContext;
+    setupOTelBridge(this);
+  }
+  this._instrumentation.start(runContextClass);
+
+  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;
+};
+
+/**
+ * Lazily create a singleton OTel MeterProvider that periodically exports
+ * metrics to APM server. This may return null if the MeterProvider is
+ * unsupported for this node version, metrics are disabled, etc.
+ *
+ * @returns {import('@opentelemetry/api').MeterProvider | null}
+ */
+Agent.prototype._getOrCreateOTelMeterProvider = function () {
+  if (this._otelMeterProvider) {
+    return this._otelMeterProvider;
+  }
+
+  if (!this._isMetricsEnabled()) {
+    return null;
+  }
+  if (!isOTelMetricsFeatSupported) {
+    return null;
+  }
+
+  this.logger.trace('create Elastic APM MeterProvider for @opentelemetry/api');
+  this._otelMeterProvider = createOTelMeterProvider(this);
+  return this._otelMeterProvider;
+};
+
+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);
+  // 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.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.captureError = 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.captureError);
+  }
+
+  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 Elastic APM: %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);
+          }
+        }
+      },
+    );
+  });
+};
+
+// 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 }, 'Elastic APM 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.
+// @param {Boolean} opts.lambdaEnd - Optional, default false. Set this to true
+//    to signal to the transport that this is the flush at the end of a Lambda
+//    function invocation.
+//    https://github.com/elastic/apm/blob/main/specs/agents/tracing-instrumentation-aws-lambda.md#data-flushing
+Agent.prototype._flush = function (opts, cb) {
+  const lambdaEnd = !!opts.lambdaEnd;
+
+  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({ lambdaEnd }, 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({ lambdaEnd }, 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;
+};