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

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

@@ -0,0 +1,106 @@
+/*
+ * 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 asyncHooks = require('async_hooks');
+
+const { BasicRunContextManager } = require('./BasicRunContextManager');
+
+// A run context manager that uses an async hook to automatically track
+// run context across async tasks.
+//
+// (Adapted from https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-context-async-hooks/src/AsyncHooksContextManager.ts)
+class AsyncHooksRunContextManager extends BasicRunContextManager {
+  constructor(log, runContextClass) {
+    super(log, runContextClass);
+    this._runContextFromAsyncId = new Map();
+    this._asyncHook = asyncHooks.createHook({
+      init: this._init.bind(this),
+      before: this._before.bind(this),
+      after: this._after.bind(this),
+      destroy: this._destroy.bind(this),
+      promiseResolve: this._destroy.bind(this),
+    });
+  }
+
+  enable() {
+    super.enable();
+    this._asyncHook.enable();
+    return this;
+  }
+
+  disable() {
+    super.disable();
+    this._asyncHook.disable();
+    this._runContextFromAsyncId.clear();
+    return this;
+  }
+
+  // Reset state for re-use of this context manager by tests in the same process.
+  testReset() {
+    // Absent a core node async_hooks bug, the easy way to implement this method
+    // would be: `this.disable(); this.enable()`.
+    // However there is a bug in Node.js v12.0.0 - v12.2.0 (inclusive) where
+    // disabling the async hook could result in it never getting re-enabled.
+    // https://github.com/nodejs/node/issues/27585
+    // https://github.com/nodejs/node/pull/27590 (included in node v12.3.0)
+    this._runContextFromAsyncId.clear();
+    this._stack = [];
+  }
+
+  /**
+   * Init hook will be called when userland create a async context, setting the
+   * context as the current one if it exist.
+   * @param asyncId id of the async context
+   * @param type the resource type
+   */
+  _init(asyncId, type, triggerAsyncId) {
+    // ignore TIMERWRAP as they combine timers with same timeout which can lead to
+    // false context propagation. TIMERWRAP has been removed in node 11
+    // every timer has it's own `Timeout` resource anyway which is used to propagete
+    // context.
+    if (type === 'TIMERWRAP') {
+      return;
+    }
+
+    const context = this._stack[this._stack.length - 1];
+    if (context !== undefined) {
+      this._runContextFromAsyncId.set(asyncId, context);
+    }
+  }
+
+  /**
+   * Destroy hook will be called when a given context is no longer used so we can
+   * remove its attached context.
+   * @param asyncId id of the async context
+   */
+  _destroy(asyncId) {
+    this._runContextFromAsyncId.delete(asyncId);
+  }
+
+  /**
+   * Before hook is called just before executing a async context.
+   * @param asyncId id of the async context
+   */
+  _before(asyncId) {
+    const context = this._runContextFromAsyncId.get(asyncId);
+    if (context !== undefined) {
+      this._enterRunContext(context);
+    }
+  }
+
+  /**
+   * After hook is called just after completing the execution of a async context.
+   */
+  _after() {
+    this._exitRunContext();
+  }
+}
+
+module.exports = {
+  AsyncHooksRunContextManager,
+};

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

@@ -0,0 +1,73 @@
+/*
+ * 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 { AsyncLocalStorage } = require('async_hooks');
+
+const { AbstractRunContextManager } = require('./AbstractRunContextManager');
+
+/**
+ * A RunContextManager that uses core node `AsyncLocalStorage` as the mechanism
+ * for run-context tracking.
+ *
+ * (Adapted from https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-context-async-hooks/src/AsyncLocalStorageContextManager.ts)
+ */
+class AsyncLocalStorageRunContextManager extends AbstractRunContextManager {
+  constructor(log, runContextClass) {
+    super(log, runContextClass);
+    this._asyncLocalStorage = new AsyncLocalStorage();
+  }
+
+  // A string representation useful for debug logging. For example,
+  //    AsyncLocalStorageRunContextManager( RC(Trans(685ead, manual), [Span(9dd31c, GET httpstat.us, ended)]) )
+  toString() {
+    return `${this.constructor.name}( ${this.active().toString()} )`;
+  }
+
+  enable() {
+    return this;
+  }
+
+  disable() {
+    this._asyncLocalStorage.disable();
+    return this;
+  }
+
+  // Reset state for re-use of this context manager by tests in the same process.
+  testReset() {
+    this.disable();
+    this.enable();
+  }
+
+  active() {
+    const store = this._asyncLocalStorage.getStore();
+    if (store == null) {
+      return this.root();
+    } else {
+      return store;
+    }
+  }
+
+  with(runContext, fn, thisArg, ...args) {
+    const cb = thisArg == null ? fn : fn.bind(thisArg);
+    return this._asyncLocalStorage.run(runContext, cb, ...args);
+  }
+
+  // This public method is needed to support the semantics of
+  // apm.startTransaction() and apm.startSpan() that impact the current run
+  // context.
+  //
+  // Otherwise, all run context changes are via `.with()` -- scoped to a
+  // function call -- or via the "before" async hook -- scoped to an async task.
+  supersedeRunContext(runContext) {
+    this._asyncLocalStorage.enterWith(runContext);
+  }
+}
+
+module.exports = {
+  AsyncLocalStorageRunContextManager,
+};

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

@@ -0,0 +1,82 @@
+/*
+ * 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 { AbstractRunContextManager } = require('./AbstractRunContextManager');
+
+// A basic manager for run context. It handles a stack of run contexts, but does
+// no automatic tracking (via async_hooks or otherwise). Use one of the
+// subclasses.
+//
+// (Adapted from https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-context-async-hooks/src/AsyncHooksContextManager.ts)
+class BasicRunContextManager extends AbstractRunContextManager {
+  constructor(log, runContextClass) {
+    super(log, runContextClass);
+    this._stack = []; // Top of stack is the current run context.
+  }
+
+  // A string representation useful for debug logging. For example,
+  //    BasicRunContextManager(
+  //      RC(Trans(685ead, manual), [Span(9dd31c, GET httpstat.us, ended)]),
+  //      RC(Trans(685ead, manual)) )
+  toString() {
+    return `${this.constructor.name}( ${this._stack
+      .map((rc) => rc.toString())
+      .join(', ')} )`;
+  }
+
+  enable() {
+    return this;
+  }
+
+  disable() {
+    this._stack = [];
+    return this;
+  }
+
+  // Reset state for re-use of this context manager by tests in the same process.
+  testReset() {
+    this.disable();
+    this.enable();
+  }
+
+  active() {
+    return this._stack[this._stack.length - 1] || this.root();
+  }
+
+  with(runContext, fn, thisArg, ...args) {
+    this._enterRunContext(runContext);
+    try {
+      return fn.call(thisArg, ...args);
+    } finally {
+      this._exitRunContext();
+    }
+  }
+
+  // This public method is needed to support the semantics of
+  // apm.startTransaction() and apm.startSpan() that impact the current run
+  // context.
+  //
+  // Otherwise, all run context changes are via `.with()` -- scoped to a
+  // function call -- or via the "before" async hook -- scoped to an async task.
+  supersedeRunContext(runContext) {
+    this._exitRunContext();
+    this._enterRunContext(runContext);
+  }
+
+  _enterRunContext(runContext) {
+    this._stack.push(runContext);
+  }
+
+  _exitRunContext() {
+    this._stack.pop();
+  }
+}
+
+module.exports = {
+  BasicRunContextManager,
+};

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

@@ -0,0 +1,151 @@
+/*
+ * 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';
+
+// A RunContext is the immutable structure that holds which transaction and span
+// are currently active, if any, for the running JavaScript code.
+//
+// Module instrumentation code interacts with run contexts via a number of
+// methods on the `Instrumentation` instance at `agent._instrumentation`.
+//
+// User code using the agent's API (the Agent API, Transaction API, and Span API)
+// are not exposes to RunContext instances. However users of the OpenTelemetry
+// API, provided by the OpenTelemetry Bridge, *are* exposed to OpenTelemetry
+// `Context` instances -- which RunContext implements.
+//
+// A RunContext holds:
+// - a current Transaction, which can be null; and
+// - a *stack* of Spans, where the top-of-stack span is the "current" one.
+//   A stack is necessary to support the semantics of multiple started and ended
+//   spans in the same async task. E.g.:
+//      apm.startTransaction('t')
+//      var s1 = apm.startSpan('s1')
+//      var s2 = apm.startSpan('s2')
+//      s2.end()
+//      assert(apm.currentSpan === s1, 's1 is now the current span')
+// - a mapping of "values". This is an arbitrary key-value mapping, but exists
+//   primarily to implement OpenTelemetry `interface Context`
+//   https://github.com/open-telemetry/opentelemetry-js-api/blob/v1.1.0/src/context/types.ts#L17-L41
+//
+// A RunContext is immutable. This means that `runContext.enterSpan(span)` and
+// other similar methods return a new/separate RunContext instance. This is
+// done so that a run-context change in the current code does not change
+// anything for other code bound to the original RunContext (e.g. via
+// `ins.bindFunction` or `ins.bindEmitter`).
+//
+// Warning: Agent code should never use the `RunContext` class directly
+// because a subclass can be provided for the `Instrumentation` to use.
+// Instead new instances should be built from an existing one, typically the
+// active one (`_runCtxMgr.active()`) or the root one (`_runCtxMgr.root()`).
+class RunContext {
+  constructor(trans, spans, parentValues) {
+    this._trans = trans || null;
+    this._spans = spans || [];
+    this._values = parentValues ? new Map(parentValues) : new Map();
+  }
+
+  currTransaction() {
+    return this._trans;
+  }
+
+  // Returns the currently active span, if any, otherwise null.
+  currSpan() {
+    if (this._spans.length > 0) {
+      return this._spans[this._spans.length - 1];
+    } else {
+      return null;
+    }
+  }
+
+  // Return a new RunContext for a newly active/current Transaction.
+  enterTrans(trans) {
+    return new this.constructor(trans, null, this._values);
+  }
+
+  // Return a new RunContext with the given span added to the top of the spans
+  // stack.
+  enterSpan(span) {
+    const newSpans = this._spans.slice();
+    newSpans.push(span);
+    return new this.constructor(this._trans, newSpans, this._values);
+  }
+
+  // Return a new RunContext with the given transaction (and hence all of its
+  // spans) removed.
+  leaveTrans() {
+    return new this.constructor(null, null, this._values);
+  }
+
+  // Return a new RunContext with the given span removed, or null if there is
+  // no change (the given span isn't part of the run context).
+  //
+  // Typically this span is the top of stack (i.e. it is the current span).
+  // However, it is possible to have out-of-order span.end() or even end a span
+  // that isn't part of the current run context stack at all. (See
+  // test/instrumentation/run-context/fixtures/end-non-current-spans.js for
+  // examples.)
+  leaveSpan(span) {
+    let newRc = null;
+    let newSpans;
+    const lastSpan = this._spans[this._spans.length - 1];
+    if (lastSpan && lastSpan.id === span.id) {
+      // Fast path for common case: `span` is top of stack.
+      newSpans = this._spans.slice(0, this._spans.length - 1);
+      newRc = new this.constructor(this._trans, newSpans, this._values);
+    } else {
+      const stackIdx = this._spans.findIndex((s) => s.id === span.id);
+      if (stackIdx !== -1) {
+        newSpans = this._spans
+          .slice(0, stackIdx)
+          .concat(this._spans.slice(stackIdx + 1));
+        newRc = new this.constructor(this._trans, newSpans, this._values);
+      }
+    }
+    return newRc;
+  }
+
+  // A string representation useful for debug logging.
+  // For example:
+  //    RunContext(Transaction(abc123, 'trans name'), [Span(def456, 'span name', ended)])
+  //                                                                           ^^^^^^^-- if the span has ended
+  //                           ^^^^^^                       ^^^^^^-- id
+  //    ^^^^^^^^^^-- the class name, typically "RunContext", but can be overriden
+  toString() {
+    const bits = [];
+    if (this._trans) {
+      bits.push(this._trans.toString());
+    }
+    if (this._spans.length > 0) {
+      const spanStrs = this._spans.map((s) => s.toString());
+      bits.push('[' + spanStrs + ']');
+    }
+    return `${this.constructor.name}(${bits.join(', ')})`;
+  }
+
+  // ---- The following implements the OTel Context interface.
+  // https://github.com/open-telemetry/opentelemetry-js-api/blob/v1.0.4/src/context/types.ts#L17
+
+  getValue(key) {
+    return this._values.get(key);
+  }
+
+  setValue(key, value) {
+    const rc = new this.constructor(this._trans, this._spans, this._values);
+    rc._values.set(key, value);
+    return rc;
+  }
+
+  deleteValue(key) {
+    const rc = new this.constructor(this._trans, this._spans, this._values);
+    rc._values.delete(key);
+    return rc;
+  }
+}
+
+module.exports = {
+  RunContext,
+};

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

@@ -0,0 +1,23 @@
+/*
+ * 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 {
+  AsyncHooksRunContextManager,
+} = require('./AsyncHooksRunContextManager');
+const {
+  AsyncLocalStorageRunContextManager,
+} = require('./AsyncLocalStorageRunContextManager');
+const { BasicRunContextManager } = require('./BasicRunContextManager');
+const { RunContext } = require('./RunContext');
+
+module.exports = {
+  AsyncHooksRunContextManager,
+  AsyncLocalStorageRunContextManager,
+  BasicRunContextManager,
+  RunContext,
+};

package/lib/instrumentation/shimmer.js

@@ -0,0 +1,123 @@
+/*
+ * 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';
+
+/**
+ * This file is extracted from the 'shimmer' project copyright by Forrest L
+ * Norvell. It have been modified slightly to be used in the current context.
+ *
+ * https://github.com/othiym23/shimmer
+ *
+ * Original file:
+ *
+ * https://github.com/othiym23/shimmer/blob/master/index.js
+ *
+ * License:
+ *
+ * BSD-2-Clause, http://opensource.org/licenses/BSD-2-Clause
+ */
+
+var symbols = require('../symbols');
+
+var isWrappedSym = Symbol('elasticAPMIsWrapped');
+
+exports.wrap = wrap;
+exports.massWrap = massWrap;
+exports.unwrap = unwrap;
+
+// Do not load agent until used to avoid circular dependency issues.
+var _agent;
+function logger() {
+  if (!_agent) _agent = require('../../');
+  return _agent.logger;
+}
+
+function isFunction(funktion) {
+  return typeof funktion === 'function';
+}
+
+function wrap(nodule, name, wrapper) {
+  if (!nodule || !nodule[name]) {
+    logger().debug('no original function %s to wrap', name);
+    return;
+  }
+
+  if (!wrapper) {
+    logger().debug({ stack: new Error().stack }, 'no wrapper function');
+    return;
+  }
+
+  if (!isFunction(nodule[name]) || !isFunction(wrapper)) {
+    logger().debug('original object and wrapper must be functions');
+    return;
+  }
+
+  if (nodule[name][isWrappedSym]) {
+    logger().debug('function %s already wrapped', name);
+    return;
+  }
+
+  var desc = Object.getOwnPropertyDescriptor(nodule, name);
+  if (desc && !desc.writable) {
+    logger().debug('function %s is not writable', name);
+    return;
+  }
+
+  var original = nodule[name];
+  var wrapped = wrapper(original, name);
+
+  wrapped[isWrappedSym] = true;
+  wrapped[symbols.unwrap] = function elasticAPMUnwrap() {
+    if (nodule[name] === wrapped) {
+      nodule[name] = original;
+      wrapped[isWrappedSym] = false;
+    }
+  };
+
+  nodule[name] = wrapped;
+
+  return wrapped;
+}
+
+function massWrap(nodules, names, wrapper) {
+  if (!nodules) {
+    logger().debug(
+      { stack: new Error().stack },
+      'must provide one or more modules to patch',
+    );
+    return;
+  } else if (!Array.isArray(nodules)) {
+    nodules = [nodules];
+  }
+
+  if (!(names && Array.isArray(names))) {
+    logger().debug('must provide one or more functions to wrap on modules');
+    return;
+  }
+
+  for (const nodule of nodules) {
+    for (const name of names) {
+      wrap(nodule, name, wrapper);
+    }
+  }
+}
+
+function unwrap(nodule, name) {
+  if (!nodule || !nodule[name]) {
+    logger().debug({ stack: new Error().stack }, 'no function to unwrap');
+    return;
+  }
+
+  if (!nodule[name][symbols.unwrap]) {
+    logger().debug(
+      'no original to unwrap to -- has %s already been unwrapped?',
+      name,
+    );
+  } else {
+    return nodule[name][symbols.unwrap]();
+  }
+}