@redthreadlabs/tracelog 1.4.0

package/LICENSE

@@ -0,0 +1,26 @@
+BSD 2-Clause License
+
+Copyright (c) 2012, Matt Robenolt
+Copyright (c) 2013-2014, Thomas Watson Steen and Elasticsearch B.V.
+Copyright (c) 2015-2023, Elasticsearch B.V.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,126 @@
+# Tracelog
+
+Node.js APM instrumentation that writes traces to local JSONL files, with automatic rotation and optional S3 upload.
+
+Forked from [elastic-apm-node](https://github.com/elastic/apm-agent-nodejs) v4.15.0. All 43 auto-instrumentation modules are preserved (Express, Fastify, Koa, PostgreSQL, MongoDB, Redis, AWS SDK, etc.), but instead of shipping data to an Elastic APM server, everything is written to timestamped `.jsonl` files on disk with time-based and size-based rotation.
+
+## Installation
+
+```
+npm install tracelog
+```
+
+## Usage
+
+Start tracelog at the very top of your application, before importing anything else:
+
+```js
+require('tracelog').start({
+  serviceName: 'my-api',
+  serviceVersion: '1.0.0',
+  logDir: '/var/log/myapp',
+  s3Bucket: 'my-traces',
+  s3Region: 'us-east-1',
+  s3KeyTemplate: '{serviceName}/{environment}/{date}/{hostname}-{pid}-{timestamp}.jsonl',
+});
+```
+
+Or use the auto-start entry point with environment variables:
+
+```bash
+TRACELOG_SERVICE_NAME=my-api \
+node -r tracelog/start app.js
+```
+
+That's it. Tracelog will automatically instrument your HTTP servers, database clients, and other modules, writing transaction, span, error, and metric data to the JSONL file. If `s3Bucket` is set, completed (rotated) files are gzipped and uploaded to S3, then deleted locally.
+
+## Custom events
+
+Tracelog adds a custom **event** type that has no equivalent in Elastic APM or OpenTelemetry. Events are free-form records for anything that isn't a trace, error, or metric — user analytics, audit logs, client-side telemetry from mobile or browser apps, or structured log lines.
+
+```js
+// Single event
+apm.captureEvent('page_view', {
+  message: 'User viewed dashboard',
+  level: 'info',
+  user: { id: 'u-abc123', username: 'jane_doe' },
+  client: { name: 'duiduidui-ios', version: '2.4.1' },
+  params: { page: '/dashboard', referrer: '/home' },
+});
+```
+
+Events support standardized fields for user identity (`user`), client environment (`client`), severity (`level`), timing (`duration`), and an open-ended `params` object for anything else. Only `type` is required.
+
+For server endpoints that receive batches of events from client devices, use `captureEvents`:
+
+```js
+// Batch — e.g. from a mobile app uploading queued events
+app.post('/events', (req, res) => {
+  apm.captureEvents(req.body.events, () => res.sendStatus(202));
+});
+```
+
+Each event in the batch is individually filtered (via `addEventFilter`) and written as a separate JSONL line. See **[SCHEMA.md](SCHEMA.md)** for the full event schema.
+
+## Output format
+
+Each line is a self-contained JSON object with one top-level key identifying the event type. There are six event types: `metadata`, `transaction`, `span`, `error`, `metricset`, and `event`. Files start with a metadata line:
+
+```jsonl
+{"metadata":{"service":{"name":"my-api","version":"1.0.0"},"process":{"pid":1234},"system":{"hostname":"ip-10-0-1-42"},"cloud":{"provider":"aws","instance":{"id":"i-0abc123"},"availability_zone":"us-east-1a"}}}
+{"transaction":{"id":"abc123","trace_id":"def456","name":"GET /users","type":"request","duration":42.5,"result":"HTTP 2xx","sampled":true,"outcome":"success","span_count":{"started":1}}}
+{"span":{"id":"ghi789","transaction_id":"abc123","trace_id":"def456","parent_id":"abc123","name":"SELECT * FROM users","type":"db","subtype":"postgresql","duration":12.3,"sync":true,"outcome":"success"}}
+{"error":{"id":"err001","timestamp":1709740800000000,"exception":{"message":"Something broke","type":"TypeError","handled":false,"stacktrace":[...]}}}
+{"metricset":{"timestamp":1709740800000000,"samples":{"system.process.cpu.total.norm.pct":{"value":0.023},"nodejs.memory.heap.used.bytes":{"value":52428800}}}}
+{"event":{"type":"page_view","timestamp":1719484200000,"message":"User viewed dashboard","level":"info","user":{"id":"u-abc123","username":"jane_doe"},"client":{"name":"duiduidui-ios","version":"2.4.1","os":{"name":"iOS","version":"18.2"},"device":{"model":"iPhone 16 Pro","type":"phone"}},"params":{"page":"/dashboard"}}}
+```
+
+For the complete schema of every field in each event type, see **[SCHEMA.md](SCHEMA.md)**.
+
+## Configuration
+
+All options can be set via `require('tracelog').start({...})`, via environment variables, or in a `tracelog.config.js` file.
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `serviceName` | `TRACELOG_SERVICE_NAME` | from package.json | Name of your service |
+| `serviceVersion` | `TRACELOG_SERVICE_VERSION` | from package.json | Version of your service |
+| `environment` | `TRACELOG_ENVIRONMENT` | `NODE_ENV` or `development` | Deployment environment |
+| `logDir` | `TRACELOG_LOG_DIR` | `.` (cwd) | Directory for JSONL output files |
+| `logFilePrefix` | `TRACELOG_LOG_FILE_PREFIX` | `tracelog` | Filename prefix (files are named `{prefix}-{date}.jsonl`) |
+| `logMaxFileSize` | — | `104857600` (100MB) | Rotate when file exceeds this size in bytes |
+| `logRotationSchedule` | `TRACELOG_LOG_ROTATION_SCHEDULE` | `daily` | Time-based rotation: `daily` or `hourly` |
+| `s3Bucket` | `TRACELOG_S3_BUCKET` | — | S3 bucket for log upload (disabled if not set) |
+| `active` | `TRACELOG_ACTIVE` | `true` | Enable/disable the agent entirely |
+| `logLevel` | `TRACELOG_LOG_LEVEL` | `info` | Agent log level |
+
+For the complete list of all configuration options (instrumentation, sampling, error capture, stack traces, span compression, metrics, S3 upload, cloud, and more), see **[CONFIG.md](CONFIG.md)**.
+
+## Filtering
+
+Filter functions let you modify or drop events before they are written. Return the (possibly modified) object to keep it, or return a falsy value to drop it.
+
+```js
+const apm = require('tracelog').start({ serviceName: 'my-api' });
+
+// Drop all debug-level custom events
+apm.addEventFilter((event) => {
+  return event.level === 'debug' ? false : event;
+});
+
+// Redact user emails from custom events
+apm.addEventFilter((event) => {
+  if (event.user) event.user.email = '[REDACTED]';
+  return event;
+});
+```
+
+Available filter methods: `addFilter(fn)` (adds to all types), `addTransactionFilter(fn)`, `addSpanFilter(fn)`, `addErrorFilter(fn)`, `addEventFilter(fn)`, `addMetadataFilter(fn)`.
+
+## Auto-instrumented modules
+
+Express, Fastify, Koa, Hapi, Connect, Restify, HTTP/HTTPS, fetch/undici, PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch, Cassandra, Memcached, AWS SDK (v2 & v3), GraphQL, Apollo Server, Kafka, WebSockets, generic-pool, Knex, Tedious (MSSQL), Handlebars, Pug, and more.
+
+## License
+
+[BSD-2-Clause](LICENSE) — forked from Elastic APM Node.js Agent.

package/index.d.ts

@@ -0,0 +1,464 @@
+/*
+ * 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;
+
+    // Write methods (primary API)
+    writeError (err: Error | string | ParameterizedMessageObject, callback?: CaptureErrorCallback): void;
+    writeError (err: Error | string | ParameterizedMessageObject, options?: CaptureErrorOptions, callback?: CaptureErrorCallback): void;
+    writeEvent (type: string, options?: CaptureEventOptions, callback?: Function): void;
+    writeEvents (events: CaptureEventData[], callback?: Function): void;
+    writeTransaction (transaction: object): void;
+    writeSpan (span: object): void;
+
+    // Backward compat aliases
+    captureError (err: Error | string | ParameterizedMessageObject, callback?: CaptureErrorCallback): void;
+    captureError (err: Error | string | ParameterizedMessageObject, options?: CaptureErrorOptions, callback?: CaptureErrorCallback): void;
+    captureEvent (type: string, options?: CaptureEventOptions, callback?: Function): void;
+    captureEvents (events: CaptureEventData[], callback?: Function): void;
+    writeClientTransaction (transaction: object): void;
+    writeClientSpan (span: object): void;
+
+    // Channels — route records to separate JSONL files
+    getChannel (name: string): Channel;
+
+    // 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;
+    addEventFilter (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;
+
+    // Tracelog: output & rotation
+    logDir?: string;
+    logFilePrefix?: string;
+    logMaxFileSize?: number;
+    logFlushIntervalMs?: number;
+    logRotationSchedule?: 'daily' | 'hourly' | string;
+    maxLocalRetentionDays?: number;
+    maxBufferSize?: number;
+
+    // Tracelog: S3 upload
+    s3Bucket?: string;
+    s3Region?: string;
+    s3KeyTemplate?: string;
+    s3UploadIntervalMs?: number;
+    s3GzipCompleted?: boolean;
+    s3GzipCurrent?: boolean;
+    s3AccessKeyId?: string;
+    s3SecretAccessKey?: string;
+    s3SessionToken?: string;
+  }
+
+  interface Channel {
+    writeEvent (type: string, options?: CaptureEventOptions, callback?: Function): void;
+    writeEvents (events: CaptureEventData[], callback?: Function): void;
+    writeError (err: Error | string | ParameterizedMessageObject, options?: CaptureErrorOptions, callback?: CaptureErrorCallback): void;
+    writeTransaction (transaction: object): void;
+    writeSpan (span: object): void;
+  }
+
+  interface CaptureEventOptions {
+    message?: string;
+    level?: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    timestamp?: number;
+    duration?: number;
+    error?: Error | any;
+    user?: EventUserInfo;
+    client?: EventClientInfo;
+    params?: { [key: string]: any };
+  }
+
+  interface CaptureEventData extends CaptureEventOptions {
+    type: string;
+  }
+
+  interface EventUserInfo {
+    id?: string;
+    email?: string;
+    username?: string;
+  }
+
+  interface EventClientInfo {
+    name?: string;
+    version?: string;
+    os?: { name?: string; version?: string };
+    device?: { model?: string; type?: string };
+    runtime?: { name?: string; version?: string };
+  }
+
+  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,
+};