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

package/lib/opentelemetry-bridge/OTelBridgeNonRecordingSpan.js

@@ -0,0 +1,150 @@
+/*
+ * 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 otel = require('@opentelemetry/api');
+
+const agent = require('../..');
+const { OUTCOME_UNKNOWN } = require('../constants');
+const { traceparentStrFromOTelSpanContext } = require('./otelutils');
+
+// This class is used to handle OTel's concept of a `NonRecordingSpan` -- a
+// span that is never sent/exported, but can carry SpanContext (i.e. W3C
+// trace-context) that should be propagated. For a use case, see:
+// "test/opentelemetry-bridge/fixtures/nonrecordingspan-parent.js"
+//
+// This masquerades as a Transaction on the agent's internal run-context
+// tracking. Therefore it needs to support enough of Transaction's interface
+// for that to work.
+//
+// This also needs to support enough of OTel API's `interface Span` -- mostly
+// mimicking the behavior of OTel's internal `NonRecordingSpan`:
+// https://github.com/open-telemetry/opentelemetry-js-api/blob/main/src/trace/NonRecordingSpan.ts
+class OTelBridgeNonRecordingSpan {
+  constructor(otelNonRecordingSpan) {
+    this._spanContext = otelNonRecordingSpan.spanContext();
+    this.name = '';
+    this.type = null;
+    this.subtype = null;
+    this.action = null;
+    this.outcome = OUTCOME_UNKNOWN;
+    this.ended = false;
+    this.result = '';
+  }
+
+  get id() {
+    return this._spanContext.spanId;
+  }
+
+  get traceparent() {
+    return traceparentStrFromOTelSpanContext(this._spanContext);
+  }
+
+  get ids() {
+    return {
+      'trace.id': this._spanContext.traceId,
+      'transaction.id': this._spanContext.spanId,
+    };
+  }
+
+  setType() {}
+
+  setLabel(_key, _value, _stringify) {
+    return false;
+  }
+
+  addLabels(_labels, _stringify) {
+    return false;
+  }
+
+  setOutcome(_outcome) {}
+
+  startSpan() {
+    return null;
+  }
+
+  ensureParentId() {
+    return '';
+  }
+
+  // ---- private class Transaction API
+  // Only the parts of that API that are used on instances of this class.
+
+  createSpan() {
+    return null;
+  }
+
+  // GenericSpan#propagateTraceContextHeaders()
+  //
+  // Implementation adapted from OTel's W3CTraceContextPropagator#inject().
+  propagateTraceContextHeaders(carrier, setter) {
+    if (!carrier || !setter) {
+      return;
+    }
+    if (!this._spanContext || !otel.isSpanContextValid(this._spanContext)) {
+      return;
+    }
+
+    const traceparentStr = traceparentStrFromOTelSpanContext(this._spanContext);
+    setter(carrier, 'traceparent', traceparentStr);
+    if (agent._conf.useElasticTraceparentHeader) {
+      setter(carrier, 'elastic-apm-traceparent', traceparentStr);
+    }
+
+    if (this._spanContext.traceState) {
+      setter(carrier, 'tracestate', this._spanContext.traceState.serialize());
+    }
+  }
+
+  // ---- OTel interface Span
+  // Implementation adapted from opentelemetry-js-api/src/trace/NonRecordingSpan.ts
+
+  spanContext() {
+    return this._spanContext;
+  }
+
+  setAttribute(_key, _value) {
+    return this;
+  }
+
+  setAttributes(_attributes) {
+    return this;
+  }
+
+  addEvent(_name, _attributes) {
+    return this;
+  }
+
+  setStatus(_status) {
+    return this;
+  }
+
+  updateName(_name) {
+    return this;
+  }
+
+  addLink(_link) {
+    return this;
+  }
+
+  addLinks(_links) {
+    return this;
+  }
+
+  end(_endTime) {}
+
+  // isRecording always returns false for NonRecordingSpan.
+  isRecording() {
+    return false;
+  }
+
+  recordException(_exception, _time) {}
+}
+
+module.exports = {
+  OTelBridgeNonRecordingSpan,
+};

package/lib/opentelemetry-bridge/OTelBridgeRunContext.js

@@ -0,0 +1,124 @@
+/*
+ * 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 otel = require('@opentelemetry/api');
+
+const oblog = require('./oblog');
+const { OTelBridgeNonRecordingSpan } = require('./OTelBridgeNonRecordingSpan');
+const { OTelSpan } = require('./OTelSpan');
+const { RunContext } = require('../instrumentation/run-context');
+const Span = require('../instrumentation/span');
+
+const OTEL_CONTEXT_KEY = otel.createContextKey(
+  'Elastic APM Context Key OTEL CONTEXT',
+);
+let SPAN_KEY = null;
+
+// `fetchSpanKey()` is called once during OTel SDK setup to get the `SPAN_KEY`
+// that will be used by the OTel JS API during tracing -- when
+// `otel.trace.setSpan(context, span)` et al are called.
+//
+// The fetched SPAN_KEY is used later by OTelBridgeRunContext to intercept
+// `Context.{get,set,delete}Value` and translate to the agent's internal
+// RunContext semantics for controlling the active/current span.
+function fetchSpanKey() {
+  const capturingContext = {
+    spanKey: null,
+    setValue(key, _value) {
+      this.spanKey = key;
+    },
+  };
+  const fakeSpan = {};
+  otel.trace.setSpan(capturingContext, fakeSpan);
+  SPAN_KEY = capturingContext.spanKey;
+  if (!SPAN_KEY) {
+    throw new Error('could not fetch OTel API "SPAN_KEY"');
+  }
+}
+
+// This is a subclass of RunContext that is used when the agent's OTel SDK
+// is enabled. It bridges between the OTel API's `Context` and the agent's
+// `RunContext`.
+//
+// 1. It bridges between `<Context>.setValue(SPAN_KEY, ...)`, `.getValue(SPAN_KEY)`
+//    used by the OTel API and the RunContext methods used to track the current
+//    transaction and span.
+// 2. It can propagate an OTel API `Context` instance (e.g. the internal
+//    `BaseContext` that is exposed by `otel.ROOT_CONTEXT`) and proxy
+//    `.getValue(key)` calls to it. See `OTEL_CONTEXT_KEY` below.
+class OTelBridgeRunContext extends RunContext {
+  setOTelContext(otelContext) {
+    // First, save the `Context` instance in case it holds keys other than SPAN_KEY.
+    let runContext = this.setValue(OTEL_CONTEXT_KEY, otelContext);
+    // Second, if the `Context` holds a span, then pass that to our `setValue`
+    // that knows how to translate that to RunContext semantics.
+    const span = otel.trace.getSpan(otelContext);
+    if (span) {
+      runContext = runContext.setValue(SPAN_KEY, span);
+    }
+    return runContext;
+  }
+
+  getValue(key) {
+    oblog.apicall('OTelBridgeRunContext.getValue(%o)', key);
+    if (key === SPAN_KEY) {
+      const curr = this.currSpan() || this.currTransaction();
+      if (!curr) {
+        return undefined;
+      } else if (curr instanceof OTelBridgeNonRecordingSpan) {
+        return curr;
+      } else {
+        return new OTelSpan(curr);
+      }
+    }
+    const value = super.getValue(key);
+    if (value !== undefined) {
+      return value;
+    } else {
+      // Fallback to possibly-stashed OTel API Context instance.
+      const otelContext = super.getValue(OTEL_CONTEXT_KEY);
+      if (otelContext) {
+        return otelContext.getValue(key);
+      }
+    }
+  }
+
+  setValue(key, value) {
+    oblog.apicall('OTelBridgeRunContext.setValue(%o, %s)', key, value);
+    if (key === SPAN_KEY) {
+      if (value instanceof OTelSpan) {
+        if (value._span instanceof Span) {
+          return this.enterSpan(value._span);
+        } else {
+          // assert(value._span instanceof Transaction || value._span instanceof OTelBridgeNonRecordingSpan)
+          return this.enterTrans(value._span);
+        }
+      } else if (
+        typeof value.isRecording === 'function' &&
+        !value.isRecording()
+      ) {
+        return this.enterTrans(new OTelBridgeNonRecordingSpan(value));
+      }
+    }
+    return super.setValue(key, value);
+  }
+
+  deleteValue(key) {
+    oblog.apicall('OTelBridgeRunContext.deleteValue(%o)', key);
+    if (key === SPAN_KEY) {
+      return this.leaveTrans();
+    }
+    // TODO: Should perhaps proxy deleteValue(key) to the possible underlying OTEL_CONTEXT_KEY entry.
+    return super.deleteValue(key);
+  }
+}
+
+module.exports = {
+  fetchSpanKey,
+  OTelBridgeRunContext,
+};

package/lib/opentelemetry-bridge/OTelContextManager.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 EventEmitter = require('events');
+const oblog = require('./oblog');
+const { OTelBridgeRunContext } = require('./OTelBridgeRunContext');
+
+// Implements interface ContextManager from:
+// https://github.com/open-telemetry/opentelemetry-js-api/blob/v1.0.4/src/context/types.ts#L43
+class OTelContextManager {
+  constructor(agent) {
+    this._agent = agent;
+    this._ins = agent._instrumentation;
+  }
+
+  active() {
+    oblog.apicall('OTelContextManager.active()');
+    return this._ins.currRunContext();
+  }
+
+  _runContextFromOTelContext(otelContext) {
+    let runContext;
+    if (otelContext instanceof OTelBridgeRunContext) {
+      runContext = otelContext;
+    } else {
+      // `otelContext` is some object implementing OTel's `interface Context`
+      // (typically a `BaseContext` from @opentelemetry/api). We derive a new
+      // OTelBridgeRunContext from the root run-context that properly uses
+      // the Context.
+      runContext = this._ins._runCtxMgr.root().setOTelContext(otelContext);
+    }
+    return runContext;
+  }
+
+  with(otelContext, fn, thisArg, ...args) {
+    oblog.apicall(
+      'OTelContextManager.with(%s<...>, function %s, ...)',
+      otelContext.constructor.name,
+      fn.name || '<anonymous>',
+    );
+    const runContext = this._runContextFromOTelContext(otelContext);
+    return this._ins._runCtxMgr.with(runContext, fn, thisArg, ...args);
+  }
+
+  bind(otelContext, target) {
+    oblog.apicall(
+      'OTelContextManager.bind(%s, %s type)',
+      otelContext,
+      typeof target,
+    );
+    if (target instanceof EventEmitter) {
+      const runContext = this._runContextFromOTelContext(otelContext);
+      return this._ins._runCtxMgr.bindEE(runContext, target);
+    }
+    if (typeof target === 'function') {
+      const runContext = this._runContextFromOTelContext(otelContext);
+      return this._ins._runCtxMgr.bindFn(runContext, target);
+    }
+    return target;
+  }
+
+  enable() {
+    oblog.apicall('OTelContextManager.enable()');
+    this._ins._runCtxMgr.enable();
+    return this;
+  }
+
+  disable() {
+    oblog.apicall('OTelContextManager.disable()');
+    this._ins._runCtxMgr.disable();
+    return this;
+  }
+}
+
+module.exports = {
+  OTelContextManager,
+};

package/lib/opentelemetry-bridge/OTelSpan.js

@@ -0,0 +1,344 @@
+/*
+ * 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 assert = require('assert');
+const URL = require('url').URL;
+
+const otel = require('@opentelemetry/api');
+
+const GenericSpan = require('../instrumentation/generic-span');
+const oblog = require('./oblog');
+const {
+  otelSpanContextFromTraceContext,
+  epochMsFromOTelTimeInput,
+} = require('./otelutils');
+const {
+  RESULT_SUCCESS,
+  OUTCOME_UNKNOWN,
+  OUTCOME_SUCCESS,
+  RESULT_FAILURE,
+  OUTCOME_FAILURE,
+} = require('../constants');
+const Span = require('../instrumentation/span');
+const Transaction = require('../instrumentation/transaction');
+
+// Based on `isHomogeneousAttributeValueArray` from
+// packages/opentelemetry-core/src/common/attributes.ts
+function isHomogeneousArrayOfStrNumBool(arr) {
+  const len = arr.length;
+  let elemType = null;
+  for (let i = 0; i < len; i++) {
+    const elem = arr[i];
+    if (elem === undefined || elem === null) {
+      continue;
+    }
+    if (!elemType) {
+      elemType = typeof elem;
+      if (
+        !(
+          elemType === 'string' ||
+          elemType === 'number' ||
+          elemType === 'boolean'
+        )
+      ) {
+        return false;
+      }
+    } else if (typeof elem !== elemType) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// Set the given attribute key `k` and `v` according to these OTel rules:
+// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute
+function maybeSetOTelAttr(attrs, k, v) {
+  if (Array.isArray(v)) {
+    // Is it homogeneous? Nulls and undefineds are allowed.
+    if (isHomogeneousArrayOfStrNumBool(v)) {
+      attrs[k] = v.slice();
+    }
+  } else {
+    switch (typeof v) {
+      case 'number':
+      case 'boolean':
+        attrs[k] = v;
+        break;
+      case 'string':
+        // Truncation (at 1024 bytes) is done in elastic-apm-http-client.
+        attrs[k] = v;
+        break;
+    }
+  }
+}
+
+// This wraps a core Transaction or Span in the OTel API's `inteface Span`.
+class OTelSpan {
+  constructor(span) {
+    assert(span instanceof GenericSpan);
+    this._span = span;
+    this._spanContext = null;
+  }
+
+  toString() {
+    return `OTelSpan<${this._span.constructor.name}<${this._span.id}, "${this._span.name}">>`;
+  }
+
+  // ---- OTel interface Span
+  // https://github.com/open-telemetry/opentelemetry-js-api/blob/v1.0.4/src/trace/span.ts
+
+  spanContext() {
+    oblog.apicall('%s.spanContext()', this);
+    if (!this._spanContext) {
+      this._spanContext = otelSpanContextFromTraceContext(this._span._context);
+    }
+    return this._spanContext;
+  }
+
+  setAttribute(key, value) {
+    if (this._span.ended || !key || typeof key !== 'string') {
+      return this;
+    }
+
+    const attrs = this._span._getOTelAttributes();
+    maybeSetOTelAttr(attrs, key, value);
+
+    return this;
+  }
+
+  setAttributes(attributes) {
+    if (this._span.ended || !attributes || typeof attributes !== 'object') {
+      return this;
+    }
+
+    const attrs = this._span._getOTelAttributes();
+    for (const k in attributes) {
+      if (k.length === 0) continue;
+      maybeSetOTelAttr(attrs, k, attributes[k]);
+    }
+
+    return this;
+  }
+
+  // Span events are not currently supported.
+  addEvent(name, attributesOrStartTime, startTime) {
+    return this;
+  }
+
+  setStatus(otelSpanStatus) {
+    if (this._span.ended) {
+      return this;
+    }
+    switch (otelSpanStatus) {
+      case otel.SpanStatusCode.ERROR:
+        this._span.setOutcome(OUTCOME_FAILURE);
+        break;
+      case otel.SpanStatusCode.OK:
+        this._span.setOutcome(OUTCOME_SUCCESS);
+        break;
+      case otel.SpanStatusCode.UNSET:
+        this._span.setOutcome(OUTCOME_UNKNOWN);
+        break;
+    }
+    // Also set transaction.result, similar to the Java APM agent.
+    if (this._span instanceof Transaction) {
+      switch (otelSpanStatus) {
+        case otel.SpanStatusCode.ERROR:
+          this._span.result = RESULT_FAILURE;
+          break;
+        case otel.SpanStatusCode.OK:
+          this._span.result = RESULT_SUCCESS;
+          break;
+      }
+    }
+    return this;
+  }
+
+  updateName(name) {
+    if (this._span.ended) {
+      return this;
+    }
+    this._span.name = name;
+    return this;
+  }
+
+  addLink(link) {
+    this._span.addLink(link);
+    return this;
+  }
+
+  addLinks(links) {
+    this._span.addLinks(links);
+    return this;
+  }
+
+  end(otelEndTime) {
+    oblog.apicall('%s.end(endTime=%s)', this, otelEndTime);
+    const endTime =
+      otelEndTime === undefined
+        ? undefined
+        : epochMsFromOTelTimeInput(otelEndTime);
+    if (this._span instanceof Transaction) {
+      this._transCompatMapping();
+      this._span.end(undefined, endTime);
+    } else {
+      assert(this._span instanceof Span);
+      this._spanCompatMapping();
+      this._span.end(endTime);
+    }
+  }
+
+  // https://github.com/elastic/apm/blob/main/specs/agents/tracing-api-otel.md#compatibility-mapping
+  _transCompatMapping() {
+    const attrs = this._span._otelAttributes;
+    let type = 'unknown';
+    if (!attrs) {
+      this._span.type = type;
+      return;
+    }
+
+    const otelKind = otel.SpanKind[this._span._otelKind]; // map from string to int form
+    const isRpc = attrs['rpc.system'] !== undefined;
+    const isHttp =
+      attrs['http.url'] !== undefined || attrs['http.scheme'] !== undefined;
+    const isMessaging = attrs['messaging.system'] !== undefined;
+    if (otelKind === otel.SpanKind.SERVER && (isRpc || isHttp)) {
+      type = 'request';
+    } else if (otelKind === otel.SpanKind.CONSUMER && isMessaging) {
+      type = 'messaging';
+    } else {
+      type = 'unknown';
+    }
+    this._span.type = type;
+  }
+
+  // https://github.com/elastic/apm/blob/main/specs/agents/tracing-api-otel.md#compatibility-mapping
+  _spanCompatMapping() {
+    const attrs = this._span._otelAttributes;
+    const otelKind = otel.SpanKind[this._span._otelKind]; // map from string to int form
+    if (!attrs) {
+      if (otelKind === otel.SpanKind.INTERNAL) {
+        this._span.type = 'app';
+        this._span.subtype = 'internal';
+      } else {
+        this._span.type = 'unknown';
+      }
+      return;
+    }
+
+    let type;
+    let subtype;
+    let serviceTargetType = null;
+    let serviceTargetName = null;
+
+    const httpPortFromScheme = function (scheme) {
+      if (scheme === 'http') {
+        return 80;
+      } else if (scheme === 'https') {
+        return 443;
+      }
+      return -1;
+    };
+
+    // Extracts 'host:port' from URL.
+    const parseNetName = function (url) {
+      let u;
+      try {
+        u = new URL(url); // https://developer.mozilla.org/en-US/docs/Web/API/URL
+      } catch (_err) {
+        return undefined;
+      }
+      if (u.port !== '') {
+        return u.host; // host:port already in URL
+      } else {
+        var port = httpPortFromScheme(
+          u.protocol.substring(0, u.protocol.length - 1),
+        );
+        return port > 0 ? u.hostname + ':' + port : u.hostname;
+      }
+    };
+
+    let netPort = attrs['net.peer.port'] || -1;
+    const netPeer = attrs['net.peer.name'] || attrs['net.peer.ip'];
+    let netName = netPeer; // netName includes port, if provided
+    if (netName && netPort > 0) {
+      netName += ':' + netPort;
+    }
+
+    if (attrs['db.system']) {
+      type = 'db';
+      subtype = attrs['db.system'];
+      serviceTargetType = subtype;
+      serviceTargetName = attrs['db.name'] || null;
+    } else if (attrs['messaging.system']) {
+      type = 'messaging';
+      subtype = attrs['messaging.system'];
+      if (!netName && attrs['messaging.url']) {
+        netName = parseNetName(attrs['messaging.url']);
+      }
+      serviceTargetType = subtype;
+      serviceTargetName = attrs['messaging.destination'] || null;
+    } else if (attrs['rpc.system']) {
+      type = 'external';
+      subtype = attrs['rpc.system'];
+      serviceTargetType = subtype;
+      serviceTargetName = netName || attrs['rpc.service'] || null;
+    } else if (attrs['http.url'] || attrs['http.scheme']) {
+      type = 'external';
+      subtype = 'http';
+      serviceTargetType = 'http';
+      const httpHost = attrs['http.host'] || netPeer;
+      if (httpHost) {
+        if (netPort < 0) {
+          netPort = httpPortFromScheme(attrs['http.scheme']);
+        }
+        serviceTargetName = netPort < 0 ? httpHost : httpHost + ':' + netPort;
+      } else if (attrs['http.url']) {
+        serviceTargetName = parseNetName(attrs['http.url']);
+      }
+    }
+
+    if (type === undefined) {
+      if (otelKind === otel.SpanKind.INTERNAL) {
+        type = 'app';
+        subtype = 'internal';
+      } else {
+        type = 'unknown';
+      }
+    }
+
+    this._span.type = type;
+    if (subtype) {
+      this._span.subtype = subtype;
+    }
+    if (serviceTargetType || serviceTargetName) {
+      this._span.setServiceTarget(serviceTargetType, serviceTargetName);
+    }
+  }
+
+  isRecording() {
+    return !this._span.ended && this._span.sampled;
+  }
+
+  recordException(otelException, otelTime) {
+    const errOpts = {
+      parent: this._span,
+      captureAttributes: false,
+      skipOutcome: true,
+    };
+    if (otelTime !== undefined) {
+      errOpts.timestamp = epochMsFromOTelTimeInput(otelTime);
+    }
+
+    this._span._agent.captureError(otelException, errOpts);
+  }
+}
+
+module.exports = {
+  OTelSpan,
+};