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

package/lib/instrumentation/modules/undici.js

@@ -0,0 +1,270 @@
+/*
+ * 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';
+
+// Instrument the undici module.
+//
+// This uses undici's diagnostics_channel support for instrumentation.
+//    https://github.com/nodejs/undici/blob/main/docs/api/DiagnosticsChannel.md
+// Undici is also used for Node >=v18.0.0's `fetch()` implementation, via
+// an esbuild bundle. This instrumentation is enabled if either `global.fetch`
+// is present or `require('undici')`.
+//
+// Limitations:
+// - Currently this isn't subscribing to 'undici:client:...' messages.
+//   With typical undici usage a connection will only be initiated for a
+//   request. However, if a user manually does `client.connect(...)` then it is
+//   possible for this instrumentation to miss a connection error from
+//   'undici:client:connectError'. It would eventually be nice to heuristically
+//   add 'connect' spans as children of request spans.
+// - This doesn't instrument HTTP CONNECT, as exposed by `undici.connect(...)`.
+//   I don't think the current undici diagnostics_channel messages provide a
+//   way to watch the completion of the CONNECT request.
+// - This hasn't been tested with `undici.upgrade()`.
+//
+// Some notes on if/when we want to collect some HTTP client metrics:
+// - The time between 'undici:client:connected' and 'undici:client:sendHeaders'
+//   could be a measure of client-side latency. I'm not sure if client-side
+//   queueing of requests would show a time gap here.
+// - The time between 'undici:client:sendHeaders' and 'undici:client:bodySent'
+//   might be interesting for large bodies, or perhaps for streaming requests.
+// - The time between 'undici:client:bodySent' and 'undici:request:headers'
+//   could be a measure of response TTFB latency.
+
+let diagch = null;
+try {
+  diagch = require('diagnostics_channel');
+} catch (_importErr) {
+  // pass
+}
+
+const semver = require('semver');
+
+// Search an undici@5 request.headers string for a 'traceparent' header.
+const headersStrHasTraceparentRe = /^traceparent:/im;
+
+let isInstrumented = false;
+let spanFromReq = null;
+let chans = null;
+
+// Get the content-length from undici response headers.
+// `headers` is an Array of buffers: [k, v, k, v, ...].
+// If the header is not present, or has an invalid value, this returns null.
+function contentLengthFromResponseHeaders(headers) {
+  const name = 'content-length';
+  for (let i = 0; i < headers.length; i += 2) {
+    const k = headers[i];
+    if (k.length === name.length && k.toString().toLowerCase() === name) {
+      const v = Number(headers[i + 1]);
+      if (!isNaN(v)) {
+        return v;
+      } else {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+function uninstrumentUndici() {
+  if (!isInstrumented) {
+    return;
+  }
+  isInstrumented = false;
+
+  spanFromReq = null;
+  chans.forEach(({ chan, onMessage }) => {
+    chan.unsubscribe(onMessage);
+  });
+  chans = null;
+}
+
+/**
+ * Setup instrumentation for undici. The instrumentation is based entirely on
+ * diagnostics_channel usage, so no reference to the loaded undici module is
+ * required.
+ */
+function instrumentUndici(agent) {
+  if (isInstrumented) {
+    return;
+  }
+  isInstrumented = true;
+
+  const ins = agent._instrumentation;
+  spanFromReq = new WeakMap();
+
+  // Keep ref to avoid https://github.com/nodejs/node/issues/42170 bug and for
+  // unsubscribing.
+  chans = [];
+  function diagchSub(name, onMessage) {
+    const chan = diagch.channel(name);
+    chan.subscribe(onMessage);
+    chans.push({
+      name,
+      chan,
+      onMessage,
+    });
+  }
+
+  diagchSub('undici:request:create', ({ request }) => {
+    // We do not handle instrumenting HTTP CONNECT. See limitation notes above.
+    if (request.method === 'CONNECT') {
+      return;
+    }
+
+    const url = new URL(request.origin);
+    const span = ins.createSpan(
+      `${request.method} ${url.host}`,
+      'external',
+      'http',
+      request.method,
+      { exitSpan: true },
+    );
+
+    // W3C trace-context propagation.
+    // If the span is null (e.g. hit `transactionMaxSpans`, unsampled
+    // transaction), then fallback to the current run context's span or
+    // transaction, if any.
+    const parentRunContext = ins.currRunContext();
+    const propSpan =
+      span || parentRunContext.currSpan() || parentRunContext.currTransaction();
+    if (propSpan) {
+      // Guard against adding a duplicate 'traceparent' header, because that
+      // breaks ES. https://github.com/elastic/apm-agent-nodejs/issues/3964
+      // Dev Note: This cheats a little and assumes the header names to add
+      // will include 'traceparent'.
+      let alreadyHasTp = false;
+      if (Array.isArray(request.headers)) {
+        // undici@6
+        for (let i = 0; i < request.headers.length; i += 2) {
+          if (request.headers[i].toLowerCase() === 'traceparent') {
+            alreadyHasTp = true;
+            break;
+          }
+        }
+      } else if (typeof request.headers === 'string') {
+        // undici@5
+        alreadyHasTp = headersStrHasTraceparentRe.test(request.headers);
+      }
+
+      if (!alreadyHasTp) {
+        propSpan.propagateTraceContextHeaders(
+          request,
+          function (req, name, value) {
+            if (typeof request.addHeader === 'function') {
+              req.addHeader(name, value);
+            } else if (Array.isArray(request.headers)) {
+              // undici@6.11.0 accidentally, briefly removed `request.addHeader()`.
+              req.headers.push(name, value);
+            }
+          },
+        );
+      }
+    }
+
+    if (span) {
+      spanFromReq.set(request, span);
+
+      // Set some initial HTTP context, in case the request errors out before a response.
+      span.setHttpContext({
+        method: request.method,
+        url: request.origin + request.path,
+      });
+
+      const destContext = {
+        address: url.hostname,
+      };
+      const port =
+        Number(url.port) ||
+        (url.protocol === 'https:' && 443) ||
+        (url.protocol === 'http:' && 80);
+      if (port) {
+        destContext.port = port;
+      }
+      span._setDestinationContext(destContext);
+    }
+  });
+
+  diagchSub('undici:request:headers', ({ request, response }) => {
+    const span = spanFromReq.get(request);
+    if (span !== undefined) {
+      // We are currently *not* capturing response headers, even though the
+      // intake API does allow it, because none of the other `setHttpContext`
+      // uses currently do.
+
+      const httpContext = {
+        method: request.method,
+        status_code: response.statusCode,
+        url: request.origin + request.path,
+      };
+      const cLen = contentLengthFromResponseHeaders(response.headers);
+      if (cLen !== null) {
+        httpContext.response = { encoded_body_size: cLen };
+      }
+      span.setHttpContext(httpContext);
+
+      span._setOutcomeFromHttpStatusCode(response.statusCode);
+    }
+  });
+
+  diagchSub('undici:request:trailers', ({ request }) => {
+    const span = spanFromReq.get(request);
+    if (span !== undefined) {
+      span.end();
+      spanFromReq.delete(request);
+    }
+  });
+
+  diagchSub('undici:request:error', ({ request, error }) => {
+    const span = spanFromReq.get(request);
+    const errOpts = {};
+    if (span !== undefined) {
+      errOpts.parent = span;
+      // Cases where we won't have an undici parent span:
+      // - We've hit transactionMaxSpans.
+      // - The undici HTTP span was suppressed because it is a child of an
+      //   exit span (e.g. when used as the transport for the Elasticsearch
+      //   client).
+      // It might be debatable whether we want to capture the error in the
+      // latter case. This could be revisited later.
+    }
+    agent.captureError(error, errOpts);
+    if (span !== undefined) {
+      span.end();
+      spanFromReq.delete(request);
+    }
+  });
+}
+
+function shimUndici(undici, agent, { version, enabled }) {
+  if (!enabled) {
+    return undici;
+  }
+  if (semver.lt(version, '4.7.1')) {
+    // Undici added its diagnostics_channel messages in v4.7.0. In v4.7.1 the
+    // `request.origin` property, that we need, was added.
+    agent.logger.debug(
+      'cannot instrument undici: undici version %s is not supported',
+      version,
+    );
+    return undici;
+  }
+  if (!diagch) {
+    agent.logger.debug(
+      'cannot instrument undici: there is no "diagnostics_channel" module',
+      process.version,
+    );
+    return undici;
+  }
+
+  instrumentUndici(agent);
+  return undici;
+}
+
+module.exports = shimUndici;
+module.exports.instrumentUndici = instrumentUndici;
+module.exports.uninstrumentUndici = uninstrumentUndici;

package/lib/instrumentation/modules/ws.js

@@ -0,0 +1,59 @@
+/*
+ * 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';
+
+var semver = require('semver');
+
+var shimmer = require('../shimmer');
+
+module.exports = function (ws, agent, { version, enabled }) {
+  if (!enabled) return ws;
+  if (!semver.satisfies(version, '>=1 <8')) {
+    agent.logger.debug('ws version %s not supported - aborting...', version);
+    return ws;
+  }
+
+  const ins = agent._instrumentation;
+
+  agent.logger.debug('shimming ws.prototype.send function');
+  shimmer.wrap(ws.prototype, 'send', wrapSend);
+
+  return ws;
+
+  function wrapSend(orig) {
+    return function wrappedSend() {
+      agent.logger.debug('intercepted call to ws.prototype.send');
+      const span = ins.createSpan(
+        'Send WebSocket Message',
+        'websocket',
+        'send',
+        { exitSpan: true },
+      );
+      if (!span) {
+        return orig.apply(this, arguments);
+      }
+
+      const args = Array.prototype.slice.call(arguments);
+      let cb = args[args.length - 1];
+      const onDone = function () {
+        span.end();
+        if (cb) {
+          cb.apply(this, arguments);
+        }
+      };
+      if (typeof cb === 'function') {
+        args[args.length - 1] = ins.bindFunction(onDone);
+      } else {
+        cb = null;
+        args.push(ins.bindFunction(onDone));
+      }
+
+      const spanRunContext = ins.currRunContext().enterSpan(span);
+      return ins.withRunContext(spanRunContext, orig, this, ...args);
+    };
+  }
+};

package/lib/instrumentation/noop-transaction.js

@@ -0,0 +1,81 @@
+/*
+ * 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 constants = require('../constants');
+
+const NOOP_TRANSACTION_ID = '0000000000000000';
+const NOOP_TRACEID = '00000000000000000000000000000000';
+const NOOP_TRACEPARENT = '00-00000000000000000000000000000-0000000000000000-00';
+
+/**
+ * A do-nothing Transaction object.
+ * https://www.elastic.co/guide/en/apm/agent/nodejs/current/transaction-api.html
+ */
+class NoopTransaction {
+  constructor() {
+    this.name = 'unnamed';
+    this.type = 'noop';
+    this.traceparent = NOOP_TRACEPARENT;
+    this.result = constants.RESULT_SUCCESS;
+    this.outcome = constants.OUTCOME_UNKNOWN;
+    this.ids = {
+      'trace.id': NOOP_TRACEID,
+      'transaction.id': NOOP_TRANSACTION_ID,
+    };
+
+    // Unofficial properties mentioned in a comment in index.d.ts.
+    this.timestamp = Date.now();
+    this.id = NOOP_TRANSACTION_ID;
+    this.traceId = NOOP_TRACEID;
+    this.sampled = false;
+    this.ended = false;
+  }
+
+  // Public methods.
+  setType() {}
+  setLabel() {
+    return true;
+  }
+  addLabels() {
+    return true;
+  }
+  setOutcome() {}
+  startSpan() {
+    return null;
+  }
+  end() {}
+  ensureParentId() {
+    return NOOP_TRANSACTION_ID;
+  }
+  toString() {
+    return `Transaction(${this.id}, '${this.name}'${
+      this.ended ? ', ended' : ''
+    })`;
+  }
+
+  // Non-public methods mentioned in a comment in index.d.ts.
+  setUserContext() {}
+  setCustomContext() {}
+  setDefaultName() {}
+  setDefaultNameFromRequest() {}
+  toJSON() {
+    return {};
+  }
+  duration() {
+    return 0;
+  }
+  setFaas() {}
+  setMessageContext() {}
+  setServiceContext() {}
+  setCloudContext() {}
+  _setOutcomeFromHttpStatusCode() {}
+}
+
+module.exports = {
+  NoopTransaction,
+};

package/lib/instrumentation/run-context/AbstractRunContextManager.js

@@ -0,0 +1,215 @@
+/*
+ * 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 { RunContext } = require('./RunContext');
+
+const ADD_LISTENER_METHODS = [
+  'addListener',
+  'on',
+  'once',
+  'prependListener',
+  'prependOnceListener',
+];
+
+// An abstract base RunContextManager class that implements the following
+// methods that all run context manager implementations can share:
+//    root()
+//    bindFn(runContext, target)
+//    bindEE(runContext, eventEmitter)
+//    isEEBound(eventEmitter)
+// and stubs out the remaining public methods of the RunContextManager
+// interface.
+//
+// (This class has largerly the same API as @opentelemetry/api `ContextManager`.
+// The implementation is adapted from
+// https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-context-async-hooks/src/AbstractAsyncHooksContextManager.ts)
+class AbstractRunContextManager {
+  constructor(log, runContextClass = RunContext) {
+    this._log = log;
+    this._kListeners = Symbol('ElasticListeners');
+    // eslint-disable-next-line new-cap
+    this._root = new runContextClass();
+  }
+
+  // Get the root run context. This is always empty (no current trans or span).
+  //
+  // This is the equivalent of OTel JS API's `ROOT_CONTEXT` constant. Ours
+  // is not a top-level constant, because the RunContext class can be
+  // overriden.
+  root() {
+    return this._root;
+  }
+
+  enable() {
+    throw new Error('abstract method not implemented');
+  }
+
+  disable() {
+    throw new Error('abstract method not implemented');
+  }
+
+  // Reset state for re-use of this context manager by tests in the same process.
+  testReset() {
+    this.disable();
+    this.enable();
+  }
+
+  active() {
+    throw new Error('abstract method not implemented');
+  }
+
+  with(runContext, fn, thisArg, ...args) {
+    throw new Error('abstract method not implemented');
+  }
+
+  supersedeRunContext(runContext) {
+    throw new Error('abstract method not implemented');
+  }
+
+  // The OTel ContextManager API has a single .bind() like this:
+  //
+  // bind (runContext, target) {
+  //   if (target instanceof EventEmitter) {
+  //     return this._bindEventEmitter(runContext, target)
+  //   }
+  //   if (typeof target === 'function') {
+  //     return this._bindFunction(runContext, target)
+  //   }
+  //   return target
+  // }
+  //
+  // Is there any value in this over our two separate `.bind*` methods?
+
+  bindFn(runContext, target) {
+    if (typeof target !== 'function') {
+      return target;
+    }
+    // this._log.trace('bind %s to fn "%s"', runContext, target.name)
+
+    const self = this;
+    const wrapper = function () {
+      return self.with(runContext, () => target.apply(this, arguments));
+    };
+    Object.defineProperty(wrapper, 'length', {
+      enumerable: false,
+      configurable: true,
+      writable: false,
+      value: target.length,
+    });
+
+    return wrapper;
+  }
+
+  // (This implementation is adapted from OTel's `_bindEventEmitter`.)
+  bindEE(runContext, ee) {
+    // Explicitly do *not* guard with `ee instanceof EventEmitter`. The
+    // `Request` object from the aws-sdk@2 module, for example, has an `on`
+    // with the EventEmitter API that we want to bind, but it is not otherwise
+    // an EventEmitter.
+
+    const map = this._getPatchMap(ee);
+    if (map !== undefined) {
+      // No double-binding.
+      return ee;
+    }
+    this._createPatchMap(ee);
+
+    // patch methods that add a listener to propagate context
+    ADD_LISTENER_METHODS.forEach((methodName) => {
+      if (ee[methodName] === undefined) return;
+      ee[methodName] = this._patchAddListener(ee, ee[methodName], runContext);
+    });
+    // patch methods that remove a listener
+    if (typeof ee.removeListener === 'function') {
+      ee.removeListener = this._patchRemoveListener(ee, ee.removeListener);
+    }
+    if (typeof ee.off === 'function') {
+      ee.off = this._patchRemoveListener(ee, ee.off);
+    }
+    // patch method that remove all listeners
+    if (typeof ee.removeAllListeners === 'function') {
+      ee.removeAllListeners = this._patchRemoveAllListeners(
+        ee,
+        ee.removeAllListeners,
+      );
+    }
+    return ee;
+  }
+
+  // Return true iff the given EventEmitter is already bound to a run context.
+  isEEBound(ee) {
+    return this._getPatchMap(ee) !== undefined;
+  }
+
+  // Patch methods that remove a given listener so that we match the "patched"
+  // version of that listener (the one that propagate context).
+  _patchRemoveListener(ee, original) {
+    const contextManager = this;
+    return function (event, listener) {
+      const map = contextManager._getPatchMap(ee);
+      const listeners = map && map[event];
+      if (listeners === undefined) {
+        return original.call(this, event, listener);
+      }
+      const patchedListener = listeners.get(listener);
+      return original.call(this, event, patchedListener || listener);
+    };
+  }
+
+  // Patch methods that remove all listeners so we remove our internal
+  // references for a given event.
+  _patchRemoveAllListeners(ee, original) {
+    const contextManager = this;
+    return function (event) {
+      const map = contextManager._getPatchMap(ee);
+      if (map !== undefined) {
+        if (arguments.length === 0) {
+          contextManager._createPatchMap(ee);
+        } else if (map[event] !== undefined) {
+          delete map[event];
+        }
+      }
+      return original.apply(this, arguments);
+    };
+  }
+
+  // Patch methods on an event emitter instance that can add listeners so we
+  // can force them to propagate a given context.
+  _patchAddListener(ee, original, runContext) {
+    const contextManager = this;
+    return function (event, listener) {
+      let map = contextManager._getPatchMap(ee);
+      if (map === undefined) {
+        map = contextManager._createPatchMap(ee);
+      }
+      let listeners = map[event];
+      if (listeners === undefined) {
+        listeners = new WeakMap();
+        map[event] = listeners;
+      }
+      const patchedListener = contextManager.bindFn(runContext, listener);
+      // store a weak reference of the user listener to ours
+      listeners.set(listener, patchedListener);
+      return original.call(this, event, patchedListener);
+    };
+  }
+
+  _createPatchMap(ee) {
+    const map = Object.create(null);
+    ee[this._kListeners] = map;
+    return map;
+  }
+
+  _getPatchMap(ee) {
+    return ee[this._kListeners];
+  }
+}
+
+module.exports = {
+  AbstractRunContextManager,
+};