@redthreadlabs/tracelog 1.4.0

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,
+};

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,
+};