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

package/index.d.ts

@@ -0,0 +1,398 @@
+/*
+ * 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.
+ */
+
+/// <reference types="node" />
+
+// Note: We avoid import of any external `@types/...` to avoid TypeScript users
+// needing to manually install them. The only exception is the prerequisite to
+// `npm install -D @types/node`.
+import type { IncomingMessage, ServerResponse } from 'http';
+import { Connect } from './types/connect';
+import { AwsLambda } from './types/aws-lambda';
+
+declare namespace apm {
+  // Agent API
+  // https://www.elastic.co/guide/en/apm/agent/nodejs/current/agent-api.html
+  export interface Agent {
+    // Configuration
+    start (options?: AgentConfigOptions): Agent;
+    isStarted (): boolean;
+    getServiceName (): string | undefined;
+    getServiceVersion (): string | undefined;
+    getServiceEnvironment (): string;
+    getServiceNodeName (): string | undefined;
+    setFramework (options: {
+      name?: string;
+      version?: string;
+      overwrite?: boolean;
+    }): void;
+    addPatch (modules: string | Array<string>, handler: string | PatchHandler): void;
+    removePatch (modules: string | Array<string>, handler: string | PatchHandler): void;
+    clearPatches (modules: string | Array<string>): void;
+
+    // Data collection hooks
+    middleware: { connect (): Connect.ErrorHandleFunction };
+    lambda (handler: AwsLambda.Handler): AwsLambda.Handler;
+    lambda (type: string, handler: AwsLambda.Handler): AwsLambda.Handler;
+    handleUncaughtExceptions (
+      fn?: (err: Error) => void
+    ): void;
+
+    // Errors
+    captureError (
+      err: Error | string | ParameterizedMessageObject,
+      callback?: CaptureErrorCallback
+    ): void;
+    captureError (
+      err: Error | string | ParameterizedMessageObject,
+      options?: CaptureErrorOptions,
+      callback?: CaptureErrorCallback
+    ): void;
+
+    // Distributed Tracing
+    currentTraceparent: string | null;
+    currentTraceIds: {
+      'trace.id'?: string;
+      'transaction.id'?: string;
+      'span.id'?: string;
+    }
+
+    // Transactions
+    startTransaction(
+      name?: string | null,
+      options?: TransactionOptions
+    ): Transaction;
+    startTransaction(
+      name: string | null,
+      type: string | null,
+      options?: TransactionOptions
+    ): Transaction;
+    setTransactionName (name: string): void;
+    endTransaction (result?: string | number, endTime?: number): void;
+    currentTransaction: Transaction | null;
+
+    // Spans
+    startSpan(
+      name?: string | null,
+      options?: SpanOptions
+    ): Span | null;
+    startSpan(
+      name: string | null,
+      type: string | null,
+      options?: SpanOptions
+    ): Span | null;
+    startSpan(
+      name: string | null,
+      type: string | null,
+      subtype: string | null,
+      options?: SpanOptions
+    ): Span | null;
+    startSpan(
+      name: string | null,
+      type: string | null,
+      subtype: string | null,
+      action: string | null,
+      options?: SpanOptions
+    ): Span | null;
+    currentSpan: Span | null;
+
+    // Context
+    setGlobalLabel (name: string, value: LabelValue): void;
+    setLabel (name: string, value: LabelValue, stringify?: boolean): boolean;
+    addLabels (labels: Labels, stringify?: boolean): boolean;
+    setUserContext (user: UserObject): void;
+    setCustomContext (custom: object): void;
+
+    // Transport
+    addFilter (fn: FilterFn): void;
+    addErrorFilter (fn: FilterFn): void;
+    addSpanFilter (fn: FilterFn): void;
+    addTransactionFilter (fn: FilterFn): void;
+    addMetadataFilter (fn: FilterFn): void;
+    flush (): Promise<void>;
+    flush (callback?: Function): void;
+    destroy (): Promise<void>;
+
+    // Utils
+    logger: Logger;
+
+    // Custom metrics
+    registerMetric(name: string, callback: Function): void;
+    registerMetric(name: string, labels: Labels, callback: Function): void;
+
+    setTransactionOutcome(outcome: Outcome): void;
+    setSpanOutcome(outcome: Outcome): void;
+  }
+
+  type Outcome = 'unknown' | 'success' | 'failure';
+
+  // Transaction API
+  // https://www.elastic.co/guide/en/apm/agent/nodejs/current/transaction-api.html
+  export interface Transaction {
+    // The following properties and methods are currently not documented as their API isn't considered official:
+    // - timestamp, ended, id, traceId, parentId, sampled, duration()
+    // - setUserContext(), setCustomContext(), toJSON(), setDefaultName(), setDefaultNameFromRequest()
+
+    name: string;
+    type: string | null;
+    traceparent: string;
+    outcome: Outcome;
+    result: string | number;
+    ids: {
+      'trace.id': string;
+      'transaction.id': string;
+    }
+
+    setType (type?: string | null): void;
+    setLabel (name: string, value: LabelValue, stringify?: boolean): boolean;
+    addLabels (labels: Labels, stringify?: boolean): boolean;
+    setOutcome(outcome: Outcome): void;
+    addLink (link: Link): void;
+    addLinks (links: Link[]): void;
+
+    startSpan(
+      name?: string | null,
+      options?: SpanOptions
+    ): Span | null;
+    startSpan(
+      name: string | null,
+      type: string | null,
+      options?: SpanOptions
+    ): Span | null;
+    startSpan(
+      name: string | null,
+      type: string | null,
+      subtype: string | null,
+      options?: SpanOptions
+    ): Span | null;
+    startSpan(
+      name: string | null,
+      type: string | null,
+      subtype: string | null,
+      action: string | null,
+      options?: SpanOptions
+    ): Span | null;
+    ensureParentId (): string;
+    end (result?: string | number | null, endTime?: number): void;
+  }
+
+  // Span API
+  // https://www.elastic.co/guide/en/apm/agent/nodejs/current/span-api.html
+  export interface Span {
+    // The following properties and methods are currently not documented as their API isn't considered official:
+    // - timestamp, ended, id, traceId, parentId, sampled, duration()
+    // - customStackTrace(), setDbContext()
+
+    transaction: Transaction;
+    name: string;
+    type: string | null;
+    subtype: string | null;
+    action: string | null;
+    traceparent: string;
+    outcome: Outcome;
+    ids: {
+      'trace.id': string;
+      'span.id': string;
+    }
+
+    setType (type?: string | null, subtype?: string | null, action?: string | null): void;
+    setLabel (name: string, value: LabelValue, stringify?: boolean): boolean;
+    addLabels (labels: Labels, stringify?: boolean): boolean;
+    setOutcome(outcome: Outcome): void;
+    setServiceTarget(type?: string | null, name?: string | null): void;
+    addLink (link: Link): void;
+    addLinks (links: Link[]): void;
+    end (endTime?: number): void;
+  }
+
+  // https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html
+  export interface AgentConfigOptions {
+    abortedErrorThreshold?: string; // Also support `number`, but as we're removing this functionality soon, there's no need to advertise it
+    active?: boolean;
+    addPatch?: KeyValueConfig;
+    apiKey?: string;
+    apiRequestSize?: string; // Also support `number`, but as we're removing this functionality soon, there's no need to advertise it
+    apiRequestTime?: string; // Also support `number`, but as we're removing this functionality soon, there's no need to advertise it
+    breakdownMetrics?: boolean;
+    captureBody?: CaptureBody;
+    captureErrorLogStackTraces?: CaptureErrorLogStackTraces;
+    captureExceptions?: boolean;
+    captureHeaders?: boolean;
+    /**
+     * @deprecated Use `spanStackTraceMinDuration`.
+     */
+    captureSpanStackTraces?: boolean;
+    centralConfig?: boolean;
+    cloudProvider?: string;
+    configFile?: string;
+    containerId?: string;
+    contextManager?: string;
+    contextPropagationOnly?: boolean;
+    disableInstrumentations?: string | string[];
+    disableSend?: boolean;
+    elasticsearchCaptureBodyUrls?: Array<string>;
+    environment?: string;
+    /**
+     * @deprecated Use `longFieldMaxLength`
+     */
+    errorMessageMaxLength?: string;
+    errorOnAbortedRequests?: boolean;
+    exitSpanMinDuration?: string;
+    frameworkName?: string;
+    frameworkVersion?: string;
+    globalLabels?: KeyValueConfig;
+    hostname?: string;
+    ignoreMessageQueues?: Array<string>;
+    ignoreUrls?: Array<string | RegExp>;
+    ignoreUserAgents?: Array<string | RegExp>;
+    instrument?: boolean;
+    instrumentIncomingHTTPRequests?: boolean;
+    kubernetesNamespace?: string;
+    kubernetesNodeName?: string;
+    kubernetesPodName?: string;
+    kubernetesPodUID?: string;
+    logLevel?: LogLevel;
+    logger?: Logger; // Notably this Logger interface matches the Pino Logger.
+    longFieldMaxLength?: number;
+    maxQueueSize?: number;
+    metricsInterval?: string; // Also support `number`, but as we're removing this functionality soon, there's no need to advertise it
+    metricsLimit?: number;
+    opentelemetryBridgeEnabled?: boolean;
+    payloadLogFile?: string;
+    sanitizeFieldNames?: Array<string>;
+    secretToken?: string;
+    serverCaCertFile?: string;
+    serverTimeout?: string; // Also support `number`, but as we're removing this functionality soon, there's no need to advertise it
+    serverUrl?: string;
+    serviceName?: string;
+    serviceNodeName?: string;
+    serviceVersion?: string;
+    sourceLinesErrorAppFrames?: number;
+    sourceLinesErrorLibraryFrames?: number;
+    sourceLinesSpanAppFrames?: number;
+    sourceLinesSpanLibraryFrames?: number;
+    spanCompressionEnabled?: boolean;
+    spanCompressionExactMatchMaxDuration?: string;
+    spanCompressionSameKindMaxDuration?: string;
+    /**
+     * @deprecated Use `spanStackTraceMinDuration`.
+     */
+    spanFramesMinDuration?: string;
+    spanStackTraceMinDuration?: string;
+    stackTraceLimit?: number;
+    traceContinuationStrategy?: TraceContinuationStrategy;
+    transactionIgnoreUrls?: Array<string>;
+    transactionMaxSpans?: number;
+    transactionSampleRate?: number;
+    useElasticTraceparentHeader?: boolean;
+    usePathAsTransactionName?: boolean;
+    verifyServerCert?: boolean;
+  }
+
+  interface CaptureErrorOptions {
+    request?: IncomingMessage;
+    response?: ServerResponse;
+    timestamp?: number;
+    handled?: boolean;
+    user?: UserObject;
+    labels?: Labels;
+    tags?: Labels;
+    custom?: object;
+    message?: string;
+    captureAttributes?: boolean;
+    skipOutcome?: boolean;
+    /**
+     * A Transaction or Span instance to make the parent of this error. If not
+     * given (undefined), then the current span or transaction will be used. If
+     * `null` is given, then no span or transaction will be used.
+     */
+    parent?: Transaction | Span | null;
+  }
+
+  interface Labels {
+    [key: string]: LabelValue;
+  }
+
+  interface UserObject {
+    id?: string | number;
+    username?: string;
+    email?: string;
+  }
+
+  interface ParameterizedMessageObject {
+    message: string;
+    params: Array<any>;
+  }
+
+  interface Logger {
+    // Defining overloaded methods rather than a separate `interface LogFn`
+    // as @types/pino does, because the IDE completion shows these as *methods*
+    // rather than as properties, which is slightly nicer.
+    fatal (msg: string, ...args: any[]): void;
+    fatal (obj: {}, msg?: string, ...args: any[]): void;
+    error (msg: string, ...args: any[]): void;
+    error (obj: {}, msg?: string, ...args: any[]): void;
+    warn (msg: string, ...args: any[]): void;
+    warn (obj: {}, msg?: string, ...args: any[]): void;
+    info (msg: string, ...args: any[]): void;
+    info (obj: {}, msg?: string, ...args: any[]): void;
+    debug (msg: string, ...args: any[]): void;
+    debug (obj: {}, msg?: string, ...args: any[]): void;
+    trace (msg: string, ...args: any[]): void;
+    trace (obj: {}, msg?: string, ...args: any[]): void;
+    // Allow a passed in Logger that has other properties, as a Pino logger
+    // does. Discussion:
+    // https://github.com/elastic/apm-agent-nodejs/pull/926/files#r266239656
+    [propName: string]: any;
+  }
+
+  // Link and `links` are intended to be compatible with OTel's
+  // equivalent APIs in "opentelemetry-js-api/src/trace/link.ts". Currently
+  // span link attributes are not supported.
+  export interface Link {
+    /** A W3C trace-context 'traceparent' string, Transaction, Span, or OTel SpanContext. */
+    context: Transaction | Span | {traceId: string, spanId: string} | string;
+  }
+
+  export interface TransactionOptions {
+    startTime?: number;
+    // `childOf` is a W3C trace-context 'traceparent' string. Passing a
+    // Transaction or Span is deprecated.
+    childOf?: Transaction | Span | string;
+    tracestate?: string; // A W3C trace-context 'tracestate' string.
+    links?: Link[];
+  }
+
+  export interface SpanOptions {
+    startTime?: number;
+    childOf?: Transaction | Span | string;
+    exitSpan?: boolean;
+    links?: Link[];
+  }
+
+  type CaptureBody = 'off' | 'errors' | 'transactions' | 'all';
+  type CaptureErrorLogStackTraces = 'never' | 'messages' | 'always';
+  type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'warning' | 'error' | 'fatal' | 'critical' | 'off';
+  type TraceContinuationStrategy = 'continue' | 'restart' | 'restart_external';
+
+  type CaptureErrorCallback = (err: Error | null, id: string) => void;
+  type FilterFn = (payload: Payload) => Payload | boolean | void;
+  type LabelValue = string | number | boolean | null | undefined;
+  type KeyValueConfig = string | Labels | Array<Array<LabelValue>>
+
+  type Payload = { [propName: string]: any }
+
+  type PatchHandler = (exports: any, agent: Agent, options: PatchOptions) => any;
+
+  interface PatchOptions {
+    name: string;
+    version: string | undefined;
+    enabled: boolean;
+  }
+}
+
+declare const apm: apm.Agent;
+export = apm;

package/index.js

@@ -0,0 +1,11 @@
+/*
+ * 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 Agent = require('./lib/agent');
+
+module.exports = new Agent();

package/lib/InflightEventSet.js

@@ -0,0 +1,53 @@
+/*
+ * 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 `Set` object used to track inflight APM events: ended spans and errors
+// that are currently being processed, but have not yet been sent to the Agent
+// transport.
+//
+// `setDrainHandler` allows setting a function to be called when the inflight
+// events have drained. Agent#flush() uses this to ensure that a flush waits
+// for inflight events to be processed, so they are sent to APM Server before
+// calling back.
+class InflightEventSet extends Set {
+  // Set a `fn` to be called *once* when the set size next goes to zero.
+  // If the optional `timeoutMs` is given, then `fn(err)` will be called if
+  // the set hasn't yet drained.
+  setDrainHandler(fn, timeoutMs) {
+    this._drainHandler = fn;
+    if (timeoutMs) {
+      this._drainTimeout = setTimeout(() => {
+        this._drain(new Error('inflight event set drain timeout'));
+      }, timeoutMs).unref();
+    }
+  }
+
+  // Call the drain handler, if there is one.
+  _drain(err) {
+    if (this._drainHandler) {
+      if (this._drainTimeout) {
+        clearTimeout(this._drainTimeout);
+        this._drainTimeout = null;
+      }
+      this._drainHandler(err);
+      // Remove the handler so it is only called once.
+      this._drainHandler = null;
+    }
+  }
+
+  delete(key) {
+    super.delete(key);
+    if (this.size === 0) {
+      this._drain();
+    }
+  }
+}
+
+module.exports = {
+  InflightEventSet,
+};

package/lib/activation-method.js

@@ -0,0 +1,119 @@
+/*
+ * 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 path = require('path');
+
+const errorStackParser = require('error-stack-parser');
+const semver = require('semver');
+
+var { isLambdaExecutionEnvironment } = require('./lambda');
+
+const CONTAINS_R_ELASTIC_APM_NODE_START =
+  /(-r\s+|--require\s*=?\s*).*elastic-apm-node\/start/;
+
+/**
+ * Determine the 'service.agent.activation_method' metadata value from an Error
+ * stack collected at `Agent.start()` time. Spec:
+ * https://github.com/elastic/apm/blob/main/specs/agents/metadata.md#activation-method
+ *
+ * @param {Error} startStack - An Error object with a captured stack trace.
+ *    The `stackTraceLimit` for the stack should be at least 15 -- higher
+ *    that the default of 10.
+ * @returns {string} one of the following values:
+ *    - "unknown"
+ *    - "require":
+ *         require('elastic-apm-node').start(...)
+ *         require('elastic-apm-node/start')
+ *    - "import":
+ *         import 'elastic-apm-node/start.js'
+ *         import apm from 'elastic-apm-node'; apm.start()
+ *    - "aws-lambda-layer": `NODE_OPTIONS` using Agent installed at /opt/nodejs/node_modules/elastic-apm-node
+ *    - "k8s-attach": `NODE_OPTIONS` using Agent, and `ELASTIC_APM_ACTIVATION_METHOD=K8S_ATTACH` (or `K8S` for bwcompat to earlier apm-k8s-attacher versions) in env
+ *    - "env-attach": Fallback for any other usage of NODE_OPTIONS='-r elastic-apm-node/start'
+ *    - "preload": For usage of `node -r elastic-apm-node/start` without `NODE_OPTIONS`.
+ */
+function agentActivationMethodFromStartStack(startStack, log) {
+  /* @param {require('stackframe').StackFrame[]} frames */
+  let frames;
+  try {
+    frames = errorStackParser.parse(startStack);
+  } catch (parseErr) {
+    log.trace(
+      parseErr,
+      'could not determine metadata.service.agent.activation_method',
+    );
+    return 'unknown';
+  }
+  if (frames.length < 2) {
+    return 'unknown';
+  }
+
+  // frames[0].fileName = "$topDir/lib/agent.js"
+  //    at Agent.start (/Users/trentm/tmp/asdf/node_modules/elastic-apm-node/lib/agent.js:241:11)
+  const topDir = path.dirname(path.dirname(frames[0].fileName));
+
+  // If this was a preload (i.e. using `-r elastic-apm-node/start`), then
+  // there will be a frame with `functionName` equal to:
+  // - node >=12: 'loadPreloadModules'
+  // - node <12: 'preloadModules'
+  const functionName = semver.gte(process.version, '12.0.0', {
+    includePrerelease: true,
+  })
+    ? 'loadPreloadModules'
+    : 'preloadModules';
+  let isPreload = false;
+  for (let i = frames.length - 1; i >= 2; i--) {
+    if (frames[i].functionName === functionName) {
+      isPreload = true;
+      break;
+    }
+  }
+  if (isPreload) {
+    if (
+      isLambdaExecutionEnvironment &&
+      topDir === '/opt/nodejs/node_modules/elastic-apm-node'
+    ) {
+      // This path is defined by https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html#configuration-layers-path
+      // and created by "dev-utils/make-distribution.sh".
+      return 'aws-lambda-layer';
+    } else if (
+      process.env.ELASTIC_APM_ACTIVATION_METHOD === 'K8S_ATTACH' ||
+      process.env.ELASTIC_APM_ACTIVATION_METHOD === 'K8S'
+    ) {
+      // apm-k8s-attacher v0.1.0 started setting value to K8S.
+      // v0.4.0 will start using 'K8S_ATTACH'.
+      return 'k8s-attach';
+    } else if (
+      process.env.NODE_OPTIONS &&
+      CONTAINS_R_ELASTIC_APM_NODE_START.test(process.env.NODE_OPTIONS)
+    ) {
+      return 'env-attach';
+    } else {
+      return 'preload';
+    }
+  }
+
+  // To tell if elastic-apm-node was `import`d or `require`d we look for a
+  // frame with `functionName` equal to 'ModuleJob.run'. This has consistently
+  // been the name of this method back to at least Node v8.
+  const esmImportFunctionName = 'ModuleJob.run';
+  if (esmImportFunctionName) {
+    for (let i = frames.length - 1; i >= 2; i--) {
+      if (frames[i].functionName === esmImportFunctionName) {
+        return 'import';
+      }
+    }
+  }
+
+  // Otherwise this was a manual `require(...)` of the agent in user code.
+  return 'require';
+}
+
+module.exports = {
+  agentActivationMethodFromStartStack,
+};