@redthreadlabs/tracelog 1.4.0

package/lib/instrumentation/modules/restify.js

@@ -0,0 +1,52 @@
+/*
+ * 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 semver = require('semver');
+
+const shimmer = require('../shimmer');
+
+module.exports = function (restify, agent, { version, enabled }) {
+  if (!enabled) {
+    return restify;
+  }
+  if (!semver.satisfies(version, '>=5.2.0 <12.0.0')) {
+    agent.logger.debug('restify version %s not supported, skipping', version);
+    return restify;
+  }
+
+  agent.setFramework({ name: 'restify', version, overwrite: false });
+
+  function patchServer(server) {
+    if (semver.gte(version, '7.0.0')) {
+      shimmer.wrap(server, '_onHandlerError', function (orig) {
+        return function _wrappedOnHandlerError(err, req, res, isUncaught) {
+          if (err)
+            agent.captureError(err, { request: req, handled: !isUncaught });
+          return orig.apply(this, arguments);
+        };
+      });
+    } else {
+      shimmer.wrap(server, '_emitErrorEvents', function (orig) {
+        return function _wrappedOnHandlerError(req, res, route, err, cb) {
+          if (err) agent.captureError(err, { request: req });
+          return orig.apply(this, arguments);
+        };
+      });
+    }
+  }
+
+  shimmer.wrap(restify, 'createServer', function (fn) {
+    return function wrappedCreateServer() {
+      const server = fn.apply(this, arguments);
+      patchServer(server);
+      return server;
+    };
+  });
+
+  return restify;
+};

package/lib/instrumentation/modules/tedious.js

@@ -0,0 +1,159 @@
+/*
+ * 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 clone = require('shallow-clone-shim');
+var sqlSummary = require('sql-summary');
+
+var { getDBDestination } = require('../context');
+
+module.exports = function (tedious, agent, { version, enabled }) {
+  if (!enabled) return tedious;
+  if (
+    semver.satisfies(version, '>=19') &&
+    !semver.satisfies(process.version, '>=18.17')
+  ) {
+    agent.logger.debug(
+      'tedious version %s not supported for node %s - aborting...',
+      version,
+      process.version,
+    );
+    return tedious;
+  }
+  if (version === '4.0.0' || !semver.satisfies(version, '>=1.9.0 <20')) {
+    agent.logger.debug(
+      'tedious version %s not supported - aborting...',
+      version,
+    );
+    return tedious;
+  }
+
+  const ins = agent._instrumentation;
+
+  return clone({}, tedious, {
+    Connection(descriptor) {
+      const getter = descriptor.get;
+      if (getter) {
+        // tedious v6.5.0+
+        descriptor.get = function get() {
+          return wrapConnection(getter());
+        };
+      } else if (typeof descriptor.value === 'function') {
+        descriptor.value = wrapConnection(descriptor.value);
+      } else {
+        agent.logger.debug(
+          'could not patch `tedious.Connection` property for tedious version %s - aborting...',
+          version,
+        );
+      }
+      return descriptor;
+    },
+    Request(descriptor) {
+      const getter = descriptor.get;
+      if (getter) {
+        // tedious v6.5.0+
+        descriptor.get = function get() {
+          return wrapRequest(getter());
+        };
+      } else if (typeof descriptor.value === 'function') {
+        descriptor.value = wrapRequest(descriptor.value);
+      } else {
+        agent.logger.debug(
+          'could not patch `tedious.Request` property for tedious version %s - aborting...',
+          version,
+        );
+      }
+      return descriptor;
+    },
+  });
+
+  function wrapRequest(OriginalRequest) {
+    class Request extends OriginalRequest {
+      constructor() {
+        super(...arguments);
+        ins.bindEmitter(this);
+      }
+    }
+
+    return Request;
+  }
+
+  function wrapConnection(OriginalConnection) {
+    class Connection extends OriginalConnection {
+      constructor() {
+        super(...arguments);
+        ins.bindEmitter(this);
+      }
+
+      makeRequest(request, _packetType, payload) {
+        // if not a Request object (i.e. a BulkLoad), then bail
+        if (!request.parametersByName) {
+          return super.makeRequest(...arguments);
+        }
+        const span = ins.createSpan(null, 'db', 'mssql', 'query', {
+          exitSpan: true,
+        });
+        if (!span) {
+          return super.makeRequest(...arguments);
+        }
+
+        let host, port, instanceName;
+        if (typeof this.config === 'object') {
+          // http://tediousjs.github.io/tedious/api-connection.html#function_newConnection
+          host = this.config.server;
+          if (this.config.options) {
+            port = this.config.options.port;
+            instanceName = this.config.options.instanceName;
+          }
+        }
+        span._setDestinationContext(getDBDestination(host, port));
+
+        let sql;
+        let preparing;
+        if (payload.parameters !== undefined) {
+          // This looks for tedious instance with `RpcRequestPayload` started
+          // since version >=v11.0.10, when RPC parameter handling was refactored
+          // (https://github.com/tediousjs/tedious/pull/1275).
+          preparing =
+            typeof payload.procedure === 'number'
+              ? // tedious@16.2.0 starts using stored procedure *IDs*
+                // (https://github.com/tediousjs/tedious/pull/1327)
+                payload.procedure === 11
+              : payload.procedure === 'sp_prepare';
+          const stmtParam =
+            payload.parameters.find(({ name }) => name === 'statement') ||
+            payload.parameters.find(({ name }) => name === 'stmt');
+          sql = stmtParam ? stmtParam.value : request.sqlTextOrProcedure;
+        } else {
+          preparing = request.sqlTextOrProcedure === 'sp_prepare';
+          const params = request.parametersByName;
+          sql = (params.statement || params.stmt || {}).value;
+        }
+        span.name = sqlSummary(sql) + (preparing ? ' (prepare)' : '');
+        const dbContext = { type: 'sql', statement: sql };
+        if (instanceName) {
+          dbContext.instance = instanceName;
+        }
+        span.setDbContext(dbContext);
+
+        const origCallback = request.userCallback;
+        request.userCallback = ins.bindFunction(function tracedCallback() {
+          // TODO: captureError and setOutcome on err first arg here
+          span.end();
+          if (origCallback) {
+            return origCallback.apply(this, arguments);
+          }
+        });
+
+        return super.makeRequest(...arguments);
+      }
+    }
+
+    return Connection;
+  }
+};

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