@unito/integration-sdk 5.0.0 → 5.1.1

package/dist/test/middlewares/finish.test.js

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import onFinish from '../../src/middlewares/finish.js';
+import { RequestMetrics } from '../../src/resources/requestMetrics.js';
 describe('finish middleware', () => {
     it('logs info', () => {
         let expected = '';
@@ -11,7 +12,7 @@ describe('finish middleware', () => {
                 eventHandler = func;
             },
             locals: {
-                requestStartTime: 0n,
+                requestMetrics: RequestMetrics.startRequest(),
                 logger: {
                     info: (_message) => {
                         expected = 'works!';
@@ -33,7 +34,7 @@ describe('finish middleware', () => {
                 eventHandler = func;
             },
             locals: {
-                requestStartTime: 0n,
+                requestMetrics: RequestMetrics.startRequest(),
                 logger: {
                     error: (_message) => {
                         expected = 'works!';
@@ -55,7 +56,7 @@ describe('finish middleware', () => {
                 eventHandler = func;
             },
             locals: {
-                requestStartTime: 0n,
+                requestMetrics: RequestMetrics.startRequest(),
                 logger: {
                     info: (_message) => {
                         expected = 'ohoh!';
@@ -77,7 +78,7 @@ describe('finish middleware', () => {
                 eventHandler = func;
             },
             locals: {
-                requestStartTime: 0n,
+                requestMetrics: RequestMetrics.startRequest(),
                 logger: {
                     error: (_message) => {
                         expected = 'works!';

package/dist/test/middlewares/start.test.js

@@ -1,11 +1,22 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import start from '../../src/middlewares/start.js';
+import { RequestMetrics } from '../../src/resources/requestMetrics.js';
 describe('start middleware', () => {
-    it('adds request start time to locals', () => {
+    it('initializes request metrics on locals', () => {
         const request = {};
         const response = { locals: {} };
         start(request, response, () => { });
-        assert.ok(response.locals.requestStartTime);
+        assert.ok(response.locals.requestMetrics instanceof RequestMetrics);
+    });
+    it('records request start time in metrics', () => {
+        const request = {};
+        const response = { locals: {} };
+        const before = process.hrtime.bigint();
+        start(request, response, () => { });
+        const result = response.locals.requestMetrics.endRequest();
+        const after = process.hrtime.bigint();
+        assert.ok(result.durationNs >= 0n);
+        assert.ok(result.durationNs <= after - before);
     });
 });

package/dist/test/resources/provider.test.js

@@ -7,6 +7,7 @@ import https from 'https';
 import { Provider } from '../../src/resources/provider.js';
 import * as HttpErrors from '../../src/httpErrors.js';
 import Logger from '../../src/resources/logger.js';
+import { RequestMetrics } from '../../src/resources/requestMetrics.js';
 // There is currently an issue with node 20.12 and fetch mocking. A quick fix is to first call fetch so it's getter
 // get properly instantiated, which allow it to be mocked properly.
 // Issue: https://github.com/nodejs/node/issues/52015
@@ -1336,4 +1337,98 @@ describe('Provider', () => {
             }
         });
     });
+    describe('request metrics', () => {
+        it('records api call duration in requestMetrics via fetchWrapper', async (context) => {
+            const metrics = RequestMetrics.startRequest();
+            const response = new Response('{"data": "value"}', {
+                status: 200,
+                headers: new Headers({ 'Content-Type': 'application/json' }),
+            });
+            context.mock.method(global, 'fetch', () => Promise.resolve(response));
+            await provider.get('/endpoint', {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                requestMetrics: metrics,
+            });
+            const result = metrics.endRequest();
+            assert.equal(result.apiCallCount, 1);
+            assert.ok(result.totalApiDurationNs >= 0, 'Duration should be recorded');
+        });
+        it('records multiple api calls in the same requestMetrics', async (context) => {
+            const metrics = RequestMetrics.startRequest();
+            context.mock.method(global, 'fetch', () => Promise.resolve(new Response('{"data": "value"}', {
+                status: 200,
+                headers: new Headers({ 'Content-Type': 'application/json' }),
+            })));
+            await provider.get('/endpoint1', {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                requestMetrics: metrics,
+            });
+            await provider.post('/endpoint2', { key: 'value' }, {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                requestMetrics: metrics,
+            });
+            const result = metrics.endRequest();
+            assert.equal(result.apiCallCount, 2);
+            assert.ok(result.totalApiDurationNs >= 0);
+        });
+        it('works without requestMetrics (backward compatible)', async (context) => {
+            const response = new Response('{"data": "value"}', {
+                status: 200,
+                headers: new Headers({ 'Content-Type': 'application/json' }),
+            });
+            context.mock.method(global, 'fetch', () => Promise.resolve(response));
+            // No requestMetrics passed — should not throw
+            const result = await provider.get('/endpoint', {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+            });
+            assert.equal(result.status, 200);
+        });
+        it('records api call duration from postForm', async () => {
+            const metrics = RequestMetrics.startRequest();
+            const httpsProvider = new Provider({
+                prepareRequest: () => ({
+                    url: 'https://www.myApi.com',
+                    headers: {},
+                }),
+            });
+            const scope = nock('https://www.myApi.com').post('/upload').reply(201, { success: true });
+            const FormData = (await import('form-data')).default;
+            const form = new FormData();
+            form.append('file', Buffer.from('test data'), 'test.txt');
+            await httpsProvider.postForm('/upload', form, {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                requestMetrics: metrics,
+            });
+            const postFormResult = metrics.endRequest();
+            assert.equal(postFormResult.apiCallCount, 1);
+            assert.ok(postFormResult.totalApiDurationNs > 0);
+            scope.isDone();
+        });
+        it('records api call duration from postStream', async () => {
+            const metrics = RequestMetrics.startRequest();
+            const testData = 'binary stream data';
+            const httpsProvider = new Provider({
+                prepareRequest: () => ({
+                    url: 'https://www.myApi.com',
+                    headers: {},
+                }),
+            });
+            const scope = nock('https://www.myApi.com').post('/upload', testData).reply(201, { success: true });
+            const stream = Readable.from(Buffer.from(testData));
+            await httpsProvider.postStream('/upload', stream, {
+                credentials: { apiKey: 'apikey#1111', unitoCredentialId: '123' },
+                logger,
+                requestMetrics: metrics,
+            });
+            const postStreamResult = metrics.endRequest();
+            assert.equal(postStreamResult.apiCallCount, 1);
+            assert.ok(postStreamResult.totalApiDurationNs > 0);
+            scope.isDone();
+        });
+    });
 });

package/dist/test/resources/requestMetrics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/resources/requestMetrics.test.js

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { RequestMetrics } from '../../src/resources/requestMetrics.js';
+describe('RequestMetrics', () => {
+    describe('initial state', () => {
+        it('starts with zero api call count', () => {
+            const metrics = RequestMetrics.startRequest();
+            const result = metrics.endRequest();
+            assert.equal(result.apiCallCount, 0);
+        });
+        it('starts with zero total api duration', () => {
+            const metrics = RequestMetrics.startRequest();
+            const result = metrics.endRequest();
+            assert.equal(result.totalApiDurationNs, 0);
+        });
+    });
+    describe('endRequest', () => {
+        it('returns elapsed duration since construction', () => {
+            const before = process.hrtime.bigint();
+            const metrics = RequestMetrics.startRequest();
+            const result = metrics.endRequest();
+            const after = process.hrtime.bigint();
+            assert.ok(result.durationNs >= 0n);
+            assert.ok(result.durationNs <= after - before);
+        });
+    });
+    describe('recordExternalApiCall', () => {
+        it('increments api call count', () => {
+            const metrics = RequestMetrics.startRequest();
+            const start1 = process.hrtime.bigint();
+            metrics.recordExternalApiCall(start1);
+            const start2 = process.hrtime.bigint();
+            metrics.recordExternalApiCall(start2);
+            const result = metrics.endRequest();
+            assert.equal(result.apiCallCount, 2);
+        });
+        it('accumulates api duration', () => {
+            const metrics = RequestMetrics.startRequest();
+            const start = process.hrtime.bigint();
+            metrics.recordExternalApiCall(start);
+            const result = metrics.endRequest();
+            assert.ok(result.totalApiDurationNs >= 0);
+        });
+    });
+});

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/errors.ts","../src/handler.ts","../src/helpers.ts","../src/httpErrors.ts","../src/index.ts","../src/integration.ts","../src/middlewares/correlationId.ts","../src/middlewares/credentials.ts","../src/middlewares/errors.ts","../src/middlewares/filters.ts","../src/middlewares/finish.ts","../src/middlewares/health.ts","../src/middlewares/logger.ts","../src/middlewares/notFound.ts","../src/middlewares/relations.ts","../src/middlewares/search.ts","../src/middlewares/secrets.ts","../src/middlewares/selects.ts","../src/middlewares/signal.ts","../src/middlewares/start.ts","../src/resources/cache.ts","../src/resources/context.ts","../src/resources/logger.ts","../src/resources/provider.ts","../test/errors.test.ts","../test/handler.test.ts","../test/helpers.test.ts","../test/integration.test.ts","../test/middlewares/correlationId.test.ts","../test/middlewares/credentials.test.ts","../test/middlewares/errors.test.ts","../test/middlewares/filters.test.ts","../test/middlewares/finish.test.ts","../test/middlewares/health.test.ts","../test/middlewares/logger.test.ts","../test/middlewares/notFound.test.ts","../test/middlewares/relations.test.ts","../test/middlewares/search.test.ts","../test/middlewares/secrets.test.ts","../test/middlewares/selects.test.ts","../test/middlewares/signal.test.ts","../test/middlewares/start.test.ts","../test/resources/cache.test.ts","../test/resources/logger.test.ts","../test/resources/provider.test.ts"],"version":"5.9.3"}
+{"root":["../src/errors.ts","../src/handler.ts","../src/helpers.ts","../src/httpErrors.ts","../src/index.ts","../src/integration.ts","../src/middlewares/correlationId.ts","../src/middlewares/credentials.ts","../src/middlewares/errors.ts","../src/middlewares/filters.ts","../src/middlewares/finish.ts","../src/middlewares/health.ts","../src/middlewares/logger.ts","../src/middlewares/notFound.ts","../src/middlewares/relations.ts","../src/middlewares/search.ts","../src/middlewares/secrets.ts","../src/middlewares/selects.ts","../src/middlewares/signal.ts","../src/middlewares/start.ts","../src/resources/cache.ts","../src/resources/context.ts","../src/resources/logger.ts","../src/resources/provider.ts","../src/resources/requestMetrics.ts","../src/resources/tracer.ts","../test/errors.test.ts","../test/handler.test.ts","../test/helpers.test.ts","../test/integration.test.ts","../test/middlewares/correlationId.test.ts","../test/middlewares/credentials.test.ts","../test/middlewares/errors.test.ts","../test/middlewares/filters.test.ts","../test/middlewares/finish.test.ts","../test/middlewares/health.test.ts","../test/middlewares/logger.test.ts","../test/middlewares/notFound.test.ts","../test/middlewares/relations.test.ts","../test/middlewares/search.test.ts","../test/middlewares/secrets.test.ts","../test/middlewares/selects.test.ts","../test/middlewares/signal.test.ts","../test/middlewares/start.test.ts","../test/resources/cache.test.ts","../test/resources/logger.test.ts","../test/resources/provider.test.ts","../test/resources/requestMetrics.test.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-sdk",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "description": "Integration SDK",
   "type": "module",
   "types": "dist/src/index.d.ts",
@@ -56,6 +56,7 @@
     "@unito/integration-api": "7.x",
     "busboy": "^1.6.0",
     "cachette": "4.x",
+    "dd-trace": "5.x",
     "express": "^5.1",
     "form-data": "^4.0.0"
   },

package/src/handler.ts

@@ -308,6 +308,7 @@ export class Handler {
           filters: res.locals.filters,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
           relations: res.locals.relations,
@@ -335,6 +336,7 @@ export class Handler {
           body: req.body,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
         });
@@ -383,6 +385,7 @@ export class Handler {
               body,
               logger: res.locals.logger,
               signal: res.locals.signal,
+              requestMetrics: res.locals.requestMetrics,
               params: req.params,
               query: req.query,
             });
@@ -417,6 +420,7 @@ export class Handler {
           secrets: res.locals.secrets,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
         });
@@ -443,6 +447,7 @@ export class Handler {
           body: req.body,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
         });
@@ -466,6 +471,7 @@ export class Handler {
           secrets: res.locals.secrets,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
         });
@@ -489,6 +495,7 @@ export class Handler {
           secrets: res.locals.secrets,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
         });
@@ -533,6 +540,7 @@ export class Handler {
           secrets: res.locals.secrets,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
         });
@@ -553,6 +561,7 @@ export class Handler {
           secrets: res.locals.secrets,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
           body: req.body,
@@ -574,6 +583,7 @@ export class Handler {
           secrets: res.locals.secrets,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
           body: req.body,
@@ -601,6 +611,7 @@ export class Handler {
           body: req.body,
           logger: res.locals.logger,
           signal: res.locals.signal,
+          requestMetrics: res.locals.requestMetrics,
           params: req.params,
           query: req.query,
         });

package/src/index.ts

@@ -10,6 +10,7 @@ export {
   type RequestOptions as ProviderRequestOptions,
   type RateLimiter,
 } from './resources/provider.js';
+export { RequestMetrics } from './resources/requestMetrics.js';
 export type { Secrets } from './middlewares/secrets.js';
 export type { Credentials } from './middlewares/credentials.js';
 export type { Filter } from './middlewares/filters.js';
@@ -17,4 +18,5 @@ export * as HttpErrors from './httpErrors.js';
 export { buildCollectionQueryParams, getApplicableFilters } from './helpers.js';
 export * from './resources/context.js';
 export { type default as Logger, NULL_LOGGER } from './resources/logger.js';
+export { DD_TRACER } from './resources/tracer.js';
 /* c8 ignore stop */

package/src/integration.ts

@@ -1,3 +1,6 @@
+// Must be the very first import so dd-trace instruments all subsequent modules.
+import './resources/tracer.js';
+
 import { Server, IncomingMessage, ServerResponse } from 'http';
 import express from 'express';
 

package/src/middlewares/finish.ts

@@ -8,7 +8,6 @@ declare global {
     interface Locals {
       logger: Logger;
       error?: ApiError;
-      requestStartTime: bigint;
     }
   }
 }
@@ -18,12 +17,15 @@ function onFinish(req: Request, res: Response, next: NextFunction) {
     const logger = res.locals.logger ?? new Logger();
     const error = res.locals.error;
 
-    const durationInNs = Number(process.hrtime.bigint() - res.locals.requestStartTime);
+    const endMetrics = res.locals.requestMetrics.endRequest();
+    const durationInNs = Number(endMetrics.durationNs);
     const durationInMs = (durationInNs / 1_000_000) | 0;
 
     const message = `${req.method} ${req.originalUrl} ${res.statusCode} - ${durationInMs} ms`;
     const metadata: Metadata = {
       duration: durationInNs,
+      externalApiCount: endMetrics.apiCallCount,
+      externalApiTotalDuration: endMetrics.totalApiDurationNs,
       // Use reserved and standard attributes of Datadog
       // https://app.datadoghq.com/logs/pipelines/standard-attributes
       http: { method: req.method, status_code: res.statusCode, url_details: { path: req.originalUrl } },

package/src/middlewares/start.ts

@@ -1,16 +1,17 @@
 import { Request, Response, NextFunction } from 'express';
+import { RequestMetrics } from '../resources/requestMetrics.js';
 
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace Express {
     interface Locals {
-      requestStartTime: bigint;
+      requestMetrics: RequestMetrics;
     }
   }
 }
 
 function start(_: Request, res: Response, next: NextFunction) {
-  res.locals.requestStartTime = process.hrtime.bigint();
+  res.locals.requestMetrics = RequestMetrics.startRequest();
 
   next();
 }

package/src/resources/context.ts

@@ -1,6 +1,7 @@
 /* c8 ignore start */
 import * as API from '@unito/integration-api';
 import Logger from './logger.js';
+import { RequestMetrics } from './requestMetrics.js';
 import { Credentials } from '../middlewares/credentials.js';
 import { Secrets } from '../middlewares/secrets.js';
 import { Filter } from '../middlewares/filters.js';
@@ -43,6 +44,11 @@ export type Context<P extends Maybe<Params> = Maybe<Params>, Q extends Maybe<Que
    * to be timed out. You can use this signal to abort any operation that would exceed this time frame.
    */
   signal: AbortSignal | undefined;
+  /**
+   * Per-request metrics accumulator for Provider API calls.
+   * Automatically populated by the SDK middleware and used by Provider to track call count and duration.
+   */
+  requestMetrics: RequestMetrics | undefined;
   /**
    * The request params.
    *

package/src/resources/provider.ts

@@ -7,6 +7,7 @@ import { buildHttpError } from '../errors.js';
 import * as HttpErrors from '../httpErrors.js';
 import { Credentials } from '../middlewares/credentials.js';
 import Logger from '../resources/logger.js';
+import { RequestMetrics } from './requestMetrics.js';
 
 /**
  * RateLimiter is a wrapper function that you can provide to limit the rate of calls to the provider based on the
@@ -44,6 +45,7 @@ export type RequestOptions = {
   queryParams?: { [key: string]: string };
   additionnalheaders?: { [key: string]: string };
   rawBody?: boolean;
+  requestMetrics?: RequestMetrics;
 };
 
 /**
@@ -278,7 +280,7 @@ export class Provider {
       });
     };
 
-    return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
+    return this.timedCallToProvider(callToProvider, options);
   }
 
   /**
@@ -406,7 +408,7 @@ export class Provider {
       });
     };
 
-    return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
+    return this.timedCallToProvider(callToProvider, options);
   }
 
   /**
@@ -687,7 +689,7 @@ export class Provider {
       return { status: response.status, headers: Object.fromEntries(response.headers.entries()), body };
     };
 
-    return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
+    return this.timedCallToProvider(callToProvider, options);
   }
 
   /**
@@ -702,6 +704,21 @@ export class Provider {
     );
   }
 
+  private async timedCallToProvider<T>(
+    callToProvider: () => Promise<Response<T>>,
+    options: RequestOptions,
+  ): Promise<Response<T>> {
+    const timedCall = async (): Promise<Response<T>> => {
+      const start = process.hrtime.bigint();
+      try {
+        return await callToProvider();
+      } finally {
+        options.requestMetrics?.recordExternalApiCall(start);
+      }
+    };
+    return this.rateLimiter ? this.rateLimiter(options, timedCall) : timedCall();
+  }
+
   private handleError(responseStatus: number, message: string, options: RequestOptions): HttpErrors.HttpError {
     const customError = this.customErrorHandler?.(responseStatus, message, options);
 

package/src/resources/requestMetrics.ts

@@ -0,0 +1,37 @@
+/**
+ * Accumulates per-request metrics for Provider API calls.
+ *
+ * Created once per incoming request (in the start middleware), threaded through Context and RequestOptions,
+ * incremented by Provider on each API call, and logged by the finish middleware.
+ */
+export class RequestMetrics {
+  private _apiCallCount = 0;
+  private _totalApiDurationNs = 0;
+  private _requestStartTime: bigint;
+
+  private constructor() {
+    this._requestStartTime = process.hrtime.bigint();
+  }
+
+  static startRequest(): RequestMetrics {
+    return new RequestMetrics();
+  }
+
+  endRequest(): { durationNs: bigint; apiCallCount: number; totalApiDurationNs: number } {
+    return {
+      durationNs: process.hrtime.bigint() - this._requestStartTime,
+      apiCallCount: this._apiCallCount,
+      totalApiDurationNs: this._totalApiDurationNs,
+    };
+  }
+
+  /**
+   * Record a completed API call.
+   * Computes the duration from the given start timestamp, increments the call counter,
+   * and accumulates the duration.
+   */
+  recordExternalApiCall(startTime: bigint): void {
+    this._apiCallCount++;
+    this._totalApiDurationNs += Number(process.hrtime.bigint() - startTime);
+  }
+}

package/src/resources/tracer.ts

@@ -0,0 +1,50 @@
+import tracer, { TracerOptions } from 'dd-trace';
+
+if (process.env.NODE_ENV === 'production' && process.env.DD_TRACE_ENABLED === 'true') {
+  // List of options available to the tracer: https://datadoghq.dev/dd-trace-js/interfaces/export_.TracerOptions.html
+  const apmConfig: TracerOptions = { logInjection: false, profiling: false, sampleRate: 0 };
+
+  if (process.env.DD_APM_ENABLED == 'true') {
+    apmConfig.logInjection = true;
+    apmConfig.sampleRate = 1;
+  } else {
+    // The "enable tracing" boolean is not exposed as part of the TracerOptions so we
+    // have to do so through env vars. Setting here instead of in services' config
+    // to avoid too many env vars to "flip" when enabling / disabling APM.
+    process.env.DD_TRACING_ENABLED = 'false';
+  }
+
+  // Profiling is extra $$$ so we're setting it as an "extra" when needed
+  if (process.env.DD_APM_PROFILING_ENABLED == 'true') {
+    apmConfig.profiling = true;
+  }
+
+  const tags: { [key: string]: any } = {};
+  // Using DD_TRACE_AGENT_URL as a hack to know if we're running inside of Kubernetes
+  // since this variable is not needed in Elastic Beanstalk of Lambda
+  if (process.env.DD_TRACE_AGENT_URL) {
+    tags.pod_name = process.env.HOSTNAME;
+  }
+
+  tracer.init({
+    ...apmConfig, // Conditionally enable APM tracing & profiling
+    runtimeMetrics: true, // Always enable runtime metrics https://docs.datadoghq.com/tracing/metrics/runtime_metrics/nodejs/?tab=environmentvariables
+    tags,
+  }); // initialized in a different file to avoid hoisting.
+}
+
+/**
+ * WARNING to projects importing this
+ * Even if dd-tracer documents that instrumentation happens at **.init() time**
+ * (see https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs/#import-and-initialize-the-tracer ),
+ *   1. dd-tracer has no choice but to do some stuff **at import time**
+ *   2. dd-tracer is not exempt from bugs, like https://github.com/DataDog/dd-trace-js/issues/5211
+ *
+ * So, do not assume that dd-trace is *fully off* by default! Some of it runs!
+ * If you want to entirely disable all of dd-trace (e.g. during unit tests),
+ * then you must set `DD_TRACE_ENABLED=false`
+ *
+ * Q: Why not move the dd-trace import inside the `if DD_TRACE_ENABLED` condition, then?
+ * A: Because the future is ESM, and ESM imports must be static and top-level.
+ */
+export const DD_TRACER = tracer;