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

package/lib/instrumentation/elasticsearch-shared.js

@@ -0,0 +1,63 @@
+/*
+ * 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';
+
+// Shared functionality between the instrumentations of:
+// - elasticsearch - the legacy Elasticsearch JS client
+// - @elastic/elasticsearch - the new Elasticsearch JS client
+
+// Only capture the ES request body if the request path matches the
+// `elasticsearchCaptureBodyUrls` config.
+function shouldCaptureBody(path, elasticsearchCaptureBodyUrlsRegExp) {
+  if (!path) {
+    return false;
+  }
+  for (var i = 0; i < elasticsearchCaptureBodyUrlsRegExp.length; i++) {
+    const re = elasticsearchCaptureBodyUrlsRegExp[i];
+    if (re.test(path)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Get an appropriate `span.context.db.statement` for this ES client request, if any.
+ * https://github.com/elastic/apm/blob/main/specs/agents/tracing-instrumentation-db.md#elasticsearch_capture_body_urls-configuration
+ *
+ * @param {string | null} path
+ * @param {string | null} body
+ * @param {RegExp[]} elasticsearchCaptureBodyUrlsRegExp
+ * @return {string | undefined}
+ */
+function getElasticsearchDbStatement(
+  path,
+  body,
+  elasticsearchCaptureBodyUrlsRegExp,
+) {
+  if (body && shouldCaptureBody(path, elasticsearchCaptureBodyUrlsRegExp)) {
+    if (typeof body === 'string') {
+      return body;
+    } else if (Buffer.isBuffer(body) || typeof body.pipe === 'function') {
+      // Never serialize a Buffer or a Readable. These guards mirror
+      // `shouldSerialize()` in the ES client, e.g.:
+      // https://github.com/elastic/elastic-transport-js/blob/069172506d1fcd544b23747d8c2d497bab053038/src/Transport.ts#L614-L618
+    } else if (Array.isArray(body)) {
+      try {
+        return body.map(JSON.stringify).join('\n') + '\n'; // ndjson
+      } catch (_ignoredErr) {}
+    } else if (typeof body === 'object') {
+      try {
+        return JSON.stringify(body);
+      } catch (_ignoredErr) {}
+    }
+  }
+}
+
+module.exports = {
+  getElasticsearchDbStatement,
+};

package/lib/instrumentation/express-utils.js

@@ -0,0 +1,91 @@
+/*
+ * 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 url = require('url');
+
+var symbols = require('../symbols');
+
+function normalizeSlash(value) {
+  return value[0] === '/' ? value : '/' + value;
+}
+
+function excludeRoot(value) {
+  return value !== '/';
+}
+
+function join(parts) {
+  if (!parts) return;
+  return parts.filter(excludeRoot).map(normalizeSlash).join('') || '/';
+}
+
+// This works for both express AND restify
+function routePath(route) {
+  if (!route) return;
+  return route.path || (route.regexp && route.regexp.source);
+}
+
+function getStackPath(req) {
+  var stack = req[symbols.expressMountStack];
+  return join(stack);
+}
+
+// This function is also able to extract the path from a Restify request as
+// it's storing the route name on req.route.path as well
+function getPathFromRequest(req, useBase, usePathAsTransactionName) {
+  if (req[symbols.staticFile]) {
+    return 'static file';
+  }
+
+  var path = getStackPath(req);
+  var route = routePath(req.route);
+
+  if (route) {
+    return path ? join([path, route]) : route;
+  } else if (path && (path !== '/' || useBase)) {
+    return path;
+  }
+
+  if (usePathAsTransactionName) {
+    // `req.url` is the "request-target" from the HTTP request line
+    // (https://www.rfc-editor.org/rfc/rfc7230#section-3.1.1). The special-case
+    // handling for leading '/' is because this:
+    //    GET //foo/bar HTTP/1.1
+    //    Host: example.com
+    // should result in:
+    //    { host: 'example.com', pathname: '//foo/bar' }
+    // and *not*:
+    //    { host: 'foo', pathname: '/bar' }
+    //
+    // Assuming 'http://' for the `base` URL is fine, because we don't use the
+    // protocol.
+    let base;
+    try {
+      // Host header may contain invalid characters therefore the URL
+      // parsing will fail and break the app. This try block is to avoid it
+      // Ref: https://github.com/elastic/apm-agent-nodejs/issues/3874
+      const url = new url.URL('http://' + (req.headers && req.headers.host));
+      base = 'http://' + url.hostname;
+    } catch (err) {
+      base = 'http://undefined';
+    }
+
+    // We may receive invalid chars in the path also but the URL
+    // constructor escapes them without throwing.
+    const parsed = req.url.startsWith('/')
+      ? new url.URL(base + req.url)
+      : new url.URL(req.url, base);
+
+    return parsed && parsed.pathname;
+  }
+}
+
+module.exports = {
+  getPathFromRequest,
+  getStackPath,
+  routePath,
+};

package/lib/instrumentation/generic-span.js

@@ -0,0 +1,322 @@
+/*
+ * 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 truncate = require('unicode-byte-truncate');
+
+const { INTAKE_STRING_MAX_SIZE } = require('../constants');
+const constants = require('../constants');
+const { SpanCompression } = require('./span-compression');
+const Timer = require('./timer');
+const TraceContext = require('../tracecontext');
+const { TraceParent } = require('../tracecontext/traceparent');
+
+module.exports = GenericSpan;
+
+/**
+ * GenericSpan is an internal base class for Span and Transaction.
+ *
+ * @param {Agent} agent
+ * @param {Object} opts
+ *    TODO: document supported opts
+ */
+function GenericSpan(agent, opts) {
+  this._timer = new Timer(opts.timer, opts.startTime);
+
+  this._context = TraceContext.startOrResume(
+    opts.childOf,
+    agent._conf,
+    opts.tracestate,
+  );
+  this._hasPropagatedTraceContext = false;
+
+  this._parentSpan = null;
+  if (opts.childOf instanceof GenericSpan) {
+    this.setParentSpan(opts.childOf);
+  }
+  this._compression = new SpanCompression(agent);
+  this._compression.setBufferedSpan(null);
+
+  this._agent = agent;
+  this._labels = null;
+  this._ids = null; // Populated by sub-types of GenericSpan
+  this._otelKind = null;
+  this._otelAttributes = null;
+
+  this._links = [];
+  if (opts.links) {
+    for (let i = 0; i < opts.links.length; i++) {
+      const link = linkFromLinkArg(opts.links[i]);
+      if (link) {
+        this._links.push(link);
+      }
+    }
+  }
+
+  this.timestamp = this._timer.start;
+  this.ended = false;
+  this._duration = null; // Duration in milliseconds. Set on `.end()`.
+  this._endTimestamp = null;
+
+  this.outcome = constants.OUTCOME_UNKNOWN;
+
+  // Freezing the outcome allows us to prefer a value set from
+  // from the API and allows a span to keep its unknown status
+  // even if it succesfully ends.
+  this._isOutcomeFrozen = false;
+}
+
+Object.defineProperty(GenericSpan.prototype, 'id', {
+  enumerable: true,
+  get() {
+    return this._context.traceparent.id;
+  },
+});
+
+Object.defineProperty(GenericSpan.prototype, 'traceId', {
+  enumerable: true,
+  get() {
+    return this._context.traceparent.traceId;
+  },
+});
+
+Object.defineProperty(GenericSpan.prototype, 'parentId', {
+  enumerable: true,
+  get() {
+    return this._context.traceparent.parentId;
+  },
+});
+
+Object.defineProperty(GenericSpan.prototype, 'sampled', {
+  enumerable: true,
+  get() {
+    return this._context.traceparent.recorded;
+  },
+});
+
+Object.defineProperty(GenericSpan.prototype, 'sampleRate', {
+  enumerable: true,
+  get() {
+    const rate = parseFloat(this._context.tracestate.getValue('s'));
+    if (rate >= 0 && rate <= 1) {
+      return rate;
+    }
+    return null;
+  },
+});
+
+Object.defineProperty(GenericSpan.prototype, 'traceparent', {
+  enumerable: true,
+  get() {
+    return this._context.toString();
+  },
+});
+
+// The duration of the span, in milliseconds.
+GenericSpan.prototype.duration = function () {
+  if (!this.ended) {
+    this._agent.logger.debug(
+      'tried to call duration() on un-ended transaction/span %o',
+      {
+        id: this.id,
+        parent: this.parentId,
+        trace: this.traceId,
+        name: this.name,
+        type: this.type,
+      },
+    );
+    return null;
+  }
+
+  return this._duration;
+};
+
+// The 'stringify' option is for backward compatibility and will likely be
+// removed in the next major version.
+GenericSpan.prototype.setLabel = function (key, value, stringify = true) {
+  const makeLabelValue = () => {
+    if (
+      !stringify &&
+      (typeof value === 'boolean' || typeof value === 'number')
+    ) {
+      return value;
+    }
+
+    return truncate(String(value), INTAKE_STRING_MAX_SIZE);
+  };
+
+  if (!key) return false;
+  if (!this._labels) this._labels = {};
+  var skey = key.replace(/[.*"]/g, '_');
+  if (key !== skey) {
+    this._agent.logger.warn('Illegal characters used in tag key: %s', key);
+  }
+  this._labels[skey] = makeLabelValue();
+  return true;
+};
+
+GenericSpan.prototype.addLabels = function (labels, stringify) {
+  if (!labels) return false;
+  var keys = Object.keys(labels);
+  for (const key of keys) {
+    if (!this.setLabel(key, labels[key], stringify)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+// Add span links.
+//
+// @param {Array} links - An array of objects with a `context` property that is
+//    a Transaction, Span, or TraceParent instance; an OTel SpanContext object;
+//    or a W3C trace-context 'traceparent' string.
+GenericSpan.prototype.addLinks = function (links) {
+  if (links) {
+    for (let i = 0; i < links.length; i++) {
+      this.addLink(links[i]);
+    }
+  }
+};
+
+// Add a span link.
+//
+// @param {Link} link - An object with a `context` property that is
+//    a Transaction, Span, or TraceParent instance; an OTel SpanContext object;
+//    or a W3C trace-context 'traceparent' string.
+GenericSpan.prototype.addLink = function (linkArg) {
+  const link = linkFromLinkArg(linkArg);
+  if (link) {
+    this._links.push(link);
+  }
+};
+
+GenericSpan.prototype._freezeOutcome = function () {
+  this._isOutcomeFrozen = true;
+};
+
+GenericSpan.prototype._isValidOutcome = function (outcome) {
+  return (
+    outcome === constants.OUTCOME_FAILURE ||
+    outcome === constants.OUTCOME_SUCCESS ||
+    outcome === constants.OUTCOME_UNKNOWN
+  );
+};
+
+GenericSpan.prototype.propagateTraceContextHeaders = function (
+  carrier,
+  setter,
+) {
+  this._hasPropagatedTraceContext = true;
+  return this._context.propagateTraceContextHeaders(carrier, setter);
+};
+GenericSpan.prototype.setParentSpan = function (span) {
+  this._parentSpan = span;
+};
+
+GenericSpan.prototype.getParentSpan = function (span) {
+  return this._parentSpan;
+};
+
+GenericSpan.prototype.getBufferedSpan = function () {
+  return this._compression.getBufferedSpan();
+};
+
+GenericSpan.prototype.setBufferedSpan = function (span) {
+  return this._compression.setBufferedSpan(span);
+};
+
+GenericSpan.prototype.isCompositeSameKind = function () {
+  return this._compression.isCompositeSameKind();
+};
+
+GenericSpan.prototype.isComposite = function () {
+  return this._compression.isComposite();
+};
+
+GenericSpan.prototype.getCompositeSum = function () {
+  return this._compression.composite.sum;
+};
+
+// https://github.com/elastic/apm/blob/main/specs/agents/tracing-api-otel.md#span-kind
+// @param {String} kind
+GenericSpan.prototype._setOTelKind = function (kind) {
+  this._otelKind = kind;
+};
+
+// This returns the internal OTel attributes object so it can be mutated.
+GenericSpan.prototype._getOTelAttributes = function () {
+  if (!this._otelAttributes) {
+    this._otelAttributes = {};
+  }
+  return this._otelAttributes;
+};
+
+// Serialize OTel-related fields into the given payload, if any.
+GenericSpan.prototype._serializeOTel = function (payload) {
+  if (this._otelKind) {
+    payload.otel = {
+      span_kind: this._otelKind,
+    };
+  }
+
+  if (this._otelAttributes) {
+    // Though the spec allows it ("MAY"), we are opting *not* to report OTel
+    // span attributes as labels for older (<7.16) versions of APM server.
+    // This is to avoid the added complexity of guarding allowed attribute
+    // value types to those supported by the APM server intake API.
+    if (!payload.otel) {
+      payload.otel = {};
+    }
+
+    payload.otel.attributes = this._otelAttributes;
+  }
+};
+
+// Translate a `opts.links` entry (see the `Link` type in "index.d.ts") to a
+// span link as it will be serialized and sent to APM server. If the linkArg is
+// invalid, this will return null.
+//
+// @param {Object} linkArg - An object with a `context` property that is
+//    a Transaction, Span, or TraceParent instance; an OTel SpanContext object;
+//    or a W3C trace-context 'traceparent' string.
+function linkFromLinkArg(linkArg) {
+  if (!linkArg || !linkArg.context) {
+    return null;
+  }
+
+  const ctx = linkArg.context;
+  let traceId;
+  let spanId;
+
+  if (ctx.traceId && ctx.spanId) {
+    // Duck-typing for an OTel SpanContext. APM intake v2 only supports the
+    // trace id and span id fields for span links, so we only need care about
+    // those attributes.
+    traceId = ctx.traceId;
+    spanId = ctx.spanId;
+  } else if (ctx._context instanceof TraceContext) {
+    // Transaction or Span
+    traceId = ctx._context.traceparent.traceId;
+    spanId = ctx._context.traceparent.id;
+  } else if (ctx instanceof TraceParent) {
+    traceId = ctx.traceId;
+    spanId = ctx.id;
+  } else if (typeof ctx === 'string') {
+    // Note: Unfortunately TraceParent.fromString doesn't validate the string.
+    const traceparent = TraceParent.fromString(ctx);
+    traceId = traceparent.traceId;
+    spanId = traceparent.id;
+  } else {
+    return null;
+  }
+
+  return {
+    trace_id: traceId,
+    span_id: spanId,
+  };
+}