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

package/lib/opentelemetry-bridge/otelutils.js

@@ -0,0 +1,99 @@
+/*
+ * 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 semver = require('semver');
+const timeOrigin = require('perf_hooks').performance.timeOrigin;
+
+// Note: This is *OTel's* TraceState class, which differs from our TraceState
+// class in "lib/tracecontext/...".
+const { TraceState } = require('./opentelemetry-core-mini/trace/TraceState');
+
+const haveUsablePerformanceNow = semver.satisfies(process.version, '>=8.12.0');
+
+function isTimeInputHrTime(value) {
+  return (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    typeof value[0] === 'number' &&
+    typeof value[1] === 'number'
+  );
+}
+
+// Convert an OTel `TimeInput` to a number of milliseconds since the Unix epoch.
+//
+// The latter is the time format used for `SpanOptions.startTime` and the
+// `endTime` arg to `Span.end()` and `Transaction.end()`.
+//
+// `TimeInput` is defined as:
+//      // hrtime, epoch milliseconds, performance.now() or Date
+//      export type TimeInput = HrTime | number | Date;
+//
+// This implementation is adapted from of TimeInput parsing in
+// "@opentelemetry/core/src/common/time.ts". Some notes:
+// - @opentelemetry/core base supported node is 8.12.0. The APM agent's is
+//   currently 8.6.0. Before 8.12.0, node's `performance.now()` did *not*
+//   return a value relative to `performance.timeOrigin()`. Therefore it was
+//   not useful to specify an absolute time value.
+// - Allowing both epoch milliseconds and performance.now() in the same arg
+//   is inherently ambiguous. To disambiguate, the following code relies on an
+//   *assumption* (the same made by @opentelemetry/core) that one never wants to
+//   provide a TimeInput value that is before the process started. Woe be the
+//   code that attempts to set a retroactive span startTime for, say, an
+//   incoming message from an out of process queue.
+function epochMsFromOTelTimeInput(otelTimeInput) {
+  if (isTimeInputHrTime(otelTimeInput)) {
+    // OTel's HrTime is `[<seconds since unix epoch>, <nanoseconds>]`
+    return otelTimeInput[0] * 1e3 + otelTimeInput[1] / 1e6;
+  } else if (typeof otelTimeInput === 'number') {
+    // Assume a performance.now() if it's smaller than process start time.
+    if (haveUsablePerformanceNow && otelTimeInput < timeOrigin) {
+      return timeOrigin + otelTimeInput;
+    } else {
+      return otelTimeInput;
+    }
+  } else if (otelTimeInput instanceof Date) {
+    return otelTimeInput.getTime();
+  } else {
+    throw TypeError(`Invalid OTel TimeInput: ${otelTimeInput}`);
+  }
+}
+
+// Convert an OTel SpanContext to a traceparent string.
+//
+// Adapted from W3CTraceContextPropagator in @opentelemetry/core.
+// https://github.com/open-telemetry/opentelemetry-js/blob/83355af4999c2d1ca660ce2499017d19642742bc/packages/opentelemetry-core/src/trace/W3CTraceContextPropagator.ts#L83-L85
+function traceparentStrFromOTelSpanContext(spanContext) {
+  return `00-${spanContext.traceId}-${spanContext.spanId}-0${Number(
+    spanContext.traceFlags || otel.TraceFlags.NONE,
+  ).toString(16)}`;
+}
+
+// Convert an Elastic TraceContext instance to an OTel SpanContext.
+// These are the Elastic and OTel classes for storing W3C trace-context data.
+function otelSpanContextFromTraceContext(traceContext) {
+  const traceparent = traceContext.traceparent;
+  const otelSpanContext = {
+    traceId: traceparent.traceId,
+    spanId: traceparent.id,
+    // `traceparent.flags` is a two-char hex string. `traceFlags` is a number.
+    // This conversion assumes `traceparent.flags` are valid.
+    traceFlags: parseInt(traceparent.flags, 16),
+  };
+  const traceStateStr = traceContext.toTraceStateString();
+  if (traceStateStr) {
+    otelSpanContext.traceState = new TraceState(traceStateStr);
+  }
+  return otelSpanContext;
+}
+
+module.exports = {
+  epochMsFromOTelTimeInput,
+  otelSpanContextFromTraceContext,
+  traceparentStrFromOTelSpanContext,
+};

package/lib/opentelemetry-bridge/setup.js

@@ -0,0 +1,76 @@
+/*
+ * 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 util = require('util');
+const otel = require('@opentelemetry/api');
+
+const logging = require('../logging');
+const { fetchSpanKey } = require('./OTelBridgeRunContext');
+const oblog = require('./oblog');
+const { OTelContextManager } = require('./OTelContextManager');
+const { OTelTracerProvider } = require('./OTelTracerProvider');
+const { OTelTracer } = require('./OTelTracer');
+
+function setupOTelBridge(agent) {
+  let success;
+
+  const log = logging.isLoggerCustom(agent.logger)
+    ? agent.logger
+    : agent.logger.child({ 'event.module': 'otelbridge' });
+
+  // `otel.diag` is "the OpenTelemetry internal diagnostic API". If *trace*
+  // level logging is enabled, then hook into diag.
+  if (log.isLevelEnabled('trace')) {
+    success = otel.diag.setLogger(
+      {
+        verbose: log.trace.bind(log),
+        debug: log.debug.bind(log),
+        info: log.info.bind(log),
+        warn: log.warn.bind(log),
+        error: log.error.bind(log),
+      },
+      otel.DiagLogLevel.ALL,
+    );
+    if (!success) {
+      log.error('could not register OpenTelemetry bridge diag logger');
+      return;
+    }
+  }
+
+  // For development/debugging-only, set `LOG_OTEL_API_CALLS = true` to get log
+  // (almost) every call into the OpenTelemetry API. See docs in "oblog.js".
+  const LOG_OTEL_API_CALLS = false;
+  if (LOG_OTEL_API_CALLS) {
+    // oblog.setApiCallLogFn(log.debug.bind(log)) // Alternative, to use our ecs logger.
+    oblog.setApiCallLogFn((...args) => {
+      const s = util.format(...args);
+      console.log('\x1b[90motelapi:\x1b[39m \x1b[32m' + s + '\x1b[39m');
+    });
+  }
+
+  success = otel.trace.setGlobalTracerProvider(
+    new OTelTracerProvider(new OTelTracer(agent)),
+  );
+  if (!success) {
+    log.error('could not register OpenTelemetry bridge TracerProvider');
+    return;
+  }
+
+  // The OTelBridgeRunContext class needs to get the SPAN_KEY before it can
+  // be used.
+  fetchSpanKey();
+
+  success = otel.context.setGlobalContextManager(new OTelContextManager(agent));
+  if (!success) {
+    log.error('could not register OpenTelemetry bridge ContextManager');
+  }
+}
+
+module.exports = {
+  setupOTelBridge,
+};

package/lib/opentelemetry-metrics/ElasticApmMetricExporter.js

@@ -0,0 +1,285 @@
+/*
+ * 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.
+ */
+
+const { ExportResultCode } = require('@opentelemetry/core');
+const {
+  AggregationTemporality,
+  InstrumentType,
+  ExplicitBucketHistogramAggregation,
+  SumAggregation,
+  LastValueAggregation,
+  DropAggregation,
+  DataPointType,
+} = require('@opentelemetry/sdk-metrics');
+const { LRUCache } = require('lru-cache');
+
+/**
+ * The `timestamp` in a metricset for APM Server intake is "UTC based and
+ * formatted as microseconds since Unix epoch".
+ *
+ * Dev note: We need to round because APM server intake requires an integer.
+ * This means a loss of sub-ms precision, which for this use case is fine.
+ */
+function metricTimestampFromOTelHrTime(otelHrTime) {
+  // OTel's HrTime is `[<seconds since unix epoch>, <nanoseconds>]`
+  return Math.round(otelHrTime[0] * 1e6 + otelHrTime[1] / 1e3);
+}
+
+// From oteljs/packages/sdk-metrics/src/utils.ts#hashAttributes
+function hashAttributes(attributes) {
+  let keys = Object.keys(attributes);
+  if (keys.length === 0) return '';
+
+  // Return a string that is stable on key orders.
+  keys = keys.sort();
+  return JSON.stringify(keys.map((key) => [key, attributes[key]]));
+}
+
+/**
+ * Fill in an Intake V2 API "sample" object for a histogram from an OTel Metrics
+ * histogram DataPoint.
+ *
+ * Algorithm is from the spec (`convertBucketBoundaries`)
+ */
+function fillIntakeHistogramSample(sample, otelDataPoint) {
+  const otelCounts = otelDataPoint.value.buckets.counts;
+  const otelBoundaries = otelDataPoint.value.buckets.boundaries;
+
+  const bucketCount = otelCounts.length;
+  if (bucketCount === 0) {
+    return;
+  }
+
+  const intakeCounts = (sample.counts = []);
+  const intakeValues = (sample.values = []);
+  sample.type = 'histogram';
+
+  // otelBoundaries has a size of bucketCount-1
+  // the first bucket has the boundaries ( -inf, otelBoundaries[0] ]
+  // the second bucket has the boundaries ( otelBoundaries[0], otelBoundaries[1] ]
+  // ..
+  // the last bucket has the boundaries (otelBoundaries[bucketCount-2], inf)
+  for (let i = 0; i < bucketCount; i++) {
+    if (otelCounts[i] !== 0) {
+      // ignore empty buckets
+      intakeCounts.push(otelCounts[i]);
+      if (i === 0) {
+        // first bucket
+        let bound = otelBoundaries[i];
+        if (bound > 0) {
+          bound /= 2;
+        }
+        intakeValues.push(bound);
+      } else if (i === bucketCount - 1) {
+        // last bucket
+        intakeValues.push(otelBoundaries[bucketCount - 2]);
+      } else {
+        // in between
+        const lower = otelBoundaries[i - 1];
+        const upper = otelBoundaries[i];
+        intakeValues.push(lower + (upper - lower) / 2);
+      }
+    }
+  }
+}
+
+/**
+ * A PushMetricExporter that exports to an Elastic APM server. It is meant to be
+ * used with a PeriodicExportingMetricReader -- which defers to
+ * `selectAggregation` and `selectAggregationTemporality` on this class.
+ *
+ * @implements {import('@opentelemetry/sdk-metrics').PushMetricExporter}
+ */
+class ElasticApmMetricExporter {
+  constructor(agent) {
+    this._agent = agent;
+    this._histogramAggregation = new ExplicitBucketHistogramAggregation(
+      this._agent._conf.customMetricsHistogramBoundaries,
+    );
+    this._sumAggregation = new SumAggregation();
+    this._lastValueAggregation = new LastValueAggregation();
+    this._dropAggregation = new DropAggregation();
+    this._attrDropWarnCache = new LRUCache({ max: 1000 });
+    this._dataPointTypeDropWarnCache = new LRUCache({ max: 1000 });
+  }
+
+  /**
+   * Spec: https://github.com/elastic/apm/blob/main/specs/agents/metrics-otel.md#aggregation
+   *
+   * @param {import('@opentelemetry/sdk-metrics').InstrumentType} instrumentType
+   * @returns {import('@opentelemetry/sdk-metrics').Aggregation}
+   */
+  selectAggregation(instrumentType) {
+    // The same behaviour as OTel's `DefaultAggregation`, except for changes
+    // to the default Histogram bucket sizes and support for the
+    // `custom_metrics_histogram_boundaries` config var.
+    switch (instrumentType) {
+      case InstrumentType.COUNTER:
+      case InstrumentType.UP_DOWN_COUNTER:
+      case InstrumentType.OBSERVABLE_COUNTER:
+      case InstrumentType.OBSERVABLE_UP_DOWN_COUNTER:
+        return this._sumAggregation;
+      case InstrumentType.OBSERVABLE_GAUGE:
+        return this._lastValueAggregation;
+      case InstrumentType.HISTOGRAM:
+        return this._histogramAggregation;
+      default:
+        this._agent.logger.warn(
+          `cannot selectAggregation: unknown OTel Metric instrumentType: ${instrumentType}`,
+        );
+        return this._dropAggregation;
+    }
+  }
+
+  // Spec: https://github.com/elastic/apm/blob/main/specs/agents/metrics-otel.md#aggregation-temporality
+  //
+  // Note: This differs from the OTel SDK default.
+  // `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=Cumulative`
+  // https://opentelemetry.io/docs/reference/specification/metrics/sdk_exporters/otlp/
+  selectAggregationTemporality(instrumentType) {
+    switch (instrumentType) {
+      case InstrumentType.COUNTER:
+      case InstrumentType.OBSERVABLE_COUNTER:
+      case InstrumentType.HISTOGRAM:
+      case InstrumentType.OBSERVABLE_GAUGE:
+        return AggregationTemporality.DELTA;
+      case InstrumentType.UP_DOWN_COUNTER:
+      case InstrumentType.OBSERVABLE_UP_DOWN_COUNTER:
+        return AggregationTemporality.CUMULATIVE;
+    }
+  }
+
+  async forceFlush() {
+    return this._agent.flush();
+  }
+
+  async shutdown() {
+    return this._agent.flush();
+  }
+
+  /**
+   * Export an OTel `ResourceMetrics` to Elastic APM intake `metricset`s.
+   *
+   * Dev notes:
+   * - Explicitly *not* including `metricData.descriptor.unit` because the APM
+   *   spec doesn't include it. It isn't clear there is value.
+   */
+  export(resourceMetrics, resultCallback) {
+    // console.log('resourceMetrics:'); console.dir(resourceMetrics, { depth: 10 })
+    for (const scopeMetrics of resourceMetrics.scopeMetrics) {
+      // Metrics from separate instrumentation scopes must be in separate
+      // `metricset` objects. In the future, the APM spec may dictate that we
+      // add labels for the instrumentation scope -- perhaps `otel.scope.*`.
+      // Discussion: https://github.com/elastic/apm/pull/742#discussion_r1061444699
+      const metricsetFromAttrHash = {};
+
+      for (const metricData of scopeMetrics.metrics) {
+        const metricName = metricData.descriptor.name;
+        if (this._agent._isMetricNameDisabled(metricName)) {
+          continue;
+        }
+        if (
+          !(
+            metricData.dataPointType === DataPointType.GAUGE ||
+            metricData.dataPointType === DataPointType.SUM ||
+            metricData.dataPointType === DataPointType.HISTOGRAM
+          )
+        ) {
+          if (!this._dataPointTypeDropWarnCache.has(metricName)) {
+            this._agent.logger.warn(
+              `dropping metric "${metricName}": cannot export metrics with dataPointType=${metricData.dataPointType}`,
+            );
+            this._dataPointTypeDropWarnCache.set(metricName, true);
+          }
+        }
+
+        for (const dataPoint of metricData.dataPoints) {
+          const labels = this._labelsFromOTelMetricAttributes(
+            dataPoint.attributes,
+            metricData.descriptor.name,
+          );
+          const attrHash = hashAttributes(labels);
+          let metricset = metricsetFromAttrHash[attrHash];
+          if (!metricset) {
+            metricset = {
+              samples: {},
+              // Assumption: `endTime` is the same for all `dataPoint`s in
+              // this `metricData`.
+              timestamp: metricTimestampFromOTelHrTime(dataPoint.endTime),
+              tags: labels,
+            };
+            metricsetFromAttrHash[attrHash] = metricset;
+          }
+          const sample = {};
+          switch (metricData.dataPointType) {
+            case DataPointType.GAUGE:
+              sample.type = 'gauge';
+              sample.value = dataPoint.value;
+              break;
+            case DataPointType.SUM:
+              if (metricData.isMonotonic) {
+                sample.type = 'counter';
+              } else {
+                sample.type = 'gauge';
+              }
+              sample.value = dataPoint.value;
+              break;
+            case DataPointType.HISTOGRAM:
+              fillIntakeHistogramSample(sample, dataPoint);
+              break;
+          }
+          if (sample.type) {
+            metricset.samples[metricData.descriptor.name] = sample;
+          }
+        }
+      }
+
+      // Importantly, if a metric has no `dataPoints` then we send nothing. This
+      // satisfies the following from the APM agents spec:
+      //
+      // > For all instrument types with delta temporality, agents MUST filter out
+      // > zero values before exporting.
+      Object.values(metricsetFromAttrHash).forEach((metricset) => {
+        this._agent._apmClient.sendMetricSet(metricset);
+      });
+    }
+
+    return resultCallback({ code: ExportResultCode.SUCCESS });
+  }
+
+  /**
+   * Convert from `dataPoint.attributes` to a set of labels (a.k.a. tags) for
+   * Elastic APM intake. Attributes with an *array* value are not supported --
+   * they are dropped with a log.warn that mentions the metric and attribute
+   * names.
+   *
+   * This makes *in-place* changes to the given `attrs` argument. It returns
+   * the same object.
+   *
+   * https://github.com/elastic/apm/blob/main/specs/agents/metrics-otel.md#labels
+   */
+  _labelsFromOTelMetricAttributes(attrs, metricName) {
+    const keys = Object.keys(attrs);
+    for (var i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      const v = attrs[k];
+      if (Array.isArray(v)) {
+        delete attrs[k];
+        const cacheKey = metricName + '/' + k;
+        if (!this._attrDropWarnCache.has(cacheKey)) {
+          this._agent.logger.warn(
+            { metricName, attrName: k },
+            'dropping array-valued metric attribute: array attribute values are not supported',
+          );
+          this._attrDropWarnCache.set(cacheKey, true);
+        }
+      }
+    }
+    return attrs;
+  }
+}
+
+module.exports = ElasticApmMetricExporter;

package/lib/opentelemetry-metrics/index.js

@@ -0,0 +1,50 @@
+/*
+ * 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.
+ */
+
+const assert = require('assert');
+
+const {
+  MeterProvider,
+  PeriodicExportingMetricReader,
+} = require('@opentelemetry/sdk-metrics');
+const semver = require('semver');
+
+const ElasticApmMetricExporter = require('./ElasticApmMetricExporter');
+
+// `isOTelMetricsFeatSupported` is true if the agent's included OTel Metrics
+// feature is supported. Currently this depends on the Node.js version supported
+// by the Metrics SDK package.
+const _supportRange = require('@opentelemetry/sdk-metrics/package.json').engines
+  .node;
+const isOTelMetricsFeatSupported = semver.satisfies(
+  process.version,
+  _supportRange,
+);
+
+function createOTelMetricReader(agent) {
+  const metricsInterval = agent._conf.metricsInterval;
+  assert(
+    metricsInterval > 0,
+    'createOTelMeterProvider() should not be called if metricsInterval <= 0',
+  );
+  return new PeriodicExportingMetricReader({
+    exporter: new ElasticApmMetricExporter(agent),
+    exportIntervalMillis: metricsInterval * 1000,
+    exportTimeoutMillis: (metricsInterval / 2) * 1000,
+  });
+}
+
+function createOTelMeterProvider(agent) {
+  const meterProvider = new MeterProvider();
+  meterProvider.addMetricReader(createOTelMetricReader(agent));
+  return meterProvider;
+}
+
+module.exports = {
+  isOTelMetricsFeatSupported,
+  createOTelMetricReader,
+  createOTelMeterProvider,
+};