chore(otlp-exporter-base): use an http agent factory

Author: raphael-theriault-swi

.mocharc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  require: `${__dirname}/ts-node.js`,
+};

.mocharc.yml

@@ -16,18 +16,22 @@
 import { OTLPExporterNodeConfigBase } from './legacy-node-configuration';
 import {
   getHttpConfigurationDefaults,
+  HttpAgentFactory,
+  httpAgentFactoryFromOptions,
   mergeOtlpHttpConfigurationWithDefaults,
   OtlpHttpConfiguration,
 } from './otlp-http-configuration';
 import { getHttpConfigurationFromEnvironment } from './otlp-http-env-configuration';
-import type * as http from 'http';
-import type * as https from 'https';
 import { diag } from '@opentelemetry/api';
 import { wrapStaticHeadersInFunction } from './shared-configuration';
 
 function convertLegacyAgentOptions(
   config: OTLPExporterNodeConfigBase
-): http.AgentOptions | https.AgentOptions | undefined {
+): HttpAgentFactory | undefined {
+  if (typeof config.httpAgentOptions === 'function') {
+    return config.httpAgentOptions;
+  }
+
   // populate keepAlive for use with new settings
   if (config?.keepAlive != null) {
     if (config.httpAgentOptions != null) {
@@ -44,7 +48,11 @@ function convertLegacyAgentOptions(
     }
   }
 
-  return config.httpAgentOptions;
+  if (config.httpAgentOptions != null) {
+    return httpAgentFactoryFromOptions(config.httpAgentOptions);
+  } else {
+    return undefined;
+  }
 }
 
 /**
@@ -72,8 +80,7 @@ export function convertLegacyHttpOptions(
       concurrencyLimit: config.concurrencyLimit,
       timeoutMillis: config.timeoutMillis,
       compression: config.compression,
-      agentOptions: convertLegacyAgentOptions(config),
-      agent: config.httpAgent,
+      agent: convertLegacyAgentOptions(config),
     },
     getHttpConfigurationFromEnvironment(signalIdentifier, signalResourcePath),
     getHttpConfigurationDefaults(requiredHeaders, signalResourcePath)

experimental/packages/otlp-exporter-base/src/configuration/convert-legacy-node-http-options.ts

@@ -18,26 +18,16 @@
 import type * as http from 'http';
 import type * as https from 'https';
 
-import { OTLPExporterConfigBase } from './legacy-base-configuration';
+import type { OTLPExporterConfigBase } from './legacy-base-configuration';
+import type { HttpAgentFactory } from './otlp-http-configuration';
 
 /**
  * Collector Exporter node base config
  */
 export interface OTLPExporterNodeConfigBase extends OTLPExporterConfigBase {
   keepAlive?: boolean;
   compression?: CompressionAlgorithm;
-  httpAgentOptions?: http.AgentOptions | https.AgentOptions;
-  /**
-   * {@link httpAgentOptions} should be preferred in almost all cases.
-   *
-   * This option exists to allow passing an instance of a custom HTTP agent
-   * class for advanced use cases.
-   * Great care must be taken not to require the `http` module before it is
-   * instrumented (for instance by importing the `Agent` class to extend it)
-   * in CommonJS code, as this will break the instrumentation and no telemetry
-   * data will be collected.
-   */
-  httpAgent?: http.Agent | https.Agent;
+  httpAgentOptions?: http.AgentOptions | https.AgentOptions | HttpAgentFactory;
 }
 
 export enum CompressionAlgorithm {

experimental/packages/otlp-exporter-base/src/configuration/legacy-node-configuration.ts

@@ -25,11 +25,16 @@ import { validateAndNormalizeHeaders } from '../util';
 import type * as http from 'http';
 import type * as https from 'https';
 
+export type HttpAgentFactory =
+  | ((protocol: string) => http.Agent)
+  | ((protocol: string) => https.Agent)
+  | ((protocol: string) => Promise<http.Agent>)
+  | ((protocol: string) => Promise<https.Agent>);
+
 export interface OtlpHttpConfiguration extends OtlpSharedConfiguration {
   url: string;
   headers: () => Record<string, string>;
-  agentOptions: http.AgentOptions | https.AgentOptions;
-  agent?: http.Agent | https.Agent;
+  agent: HttpAgentFactory;
 }
 
 function mergeHeaders(
@@ -72,6 +77,16 @@ function validateUserProvidedUrl(url: string | undefined): string | undefined {
   }
 }
 
+export function httpAgentFactoryFromOptions(
+  options: http.AgentOptions | https.AgentOptions
+): HttpAgentFactory {
+  return async protocol => {
+    const { Agent } =
+      protocol === 'http:' ? await import('http') : await import('https');
+    return new Agent(options);
+  };
+}
+
 /**
  * @param userProvidedConfiguration  Configuration options provided by the user in code.
  * @param fallbackConfiguration Fallback to use when the {@link userProvidedConfiguration} does not specify an option.
@@ -97,10 +112,10 @@ export function mergeOtlpHttpConfigurationWithDefaults(
       validateUserProvidedUrl(userProvidedConfiguration.url) ??
       fallbackConfiguration.url ??
       defaultConfiguration.url,
-    agentOptions:
-      userProvidedConfiguration.agentOptions ??
-      fallbackConfiguration.agentOptions ??
-      defaultConfiguration.agentOptions,
+    agent:
+      userProvidedConfiguration.agent ??
+      fallbackConfiguration.agent ??
+      defaultConfiguration.agent,
   };
 }
 
@@ -112,6 +127,6 @@ export function getHttpConfigurationDefaults(
     ...getSharedConfigurationDefaults(),
     headers: () => requiredHeaders,
     url: 'http://localhost:4318/' + signalResourcePath,
-    agentOptions: { keepAlive: true },
+    agent: httpAgentFactoryFromOptions({ keepAlive: true }),
   };
 }

experimental/packages/otlp-exporter-base/src/configuration/otlp-http-configuration.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+export { httpAgentFactoryFromOptions } from './configuration/otlp-http-configuration';
 export { createOtlpHttpExportDelegate } from './otlp-http-export-delegate';
 export { getSharedConfigurationFromEnvironment } from './configuration/shared-env-configuration';
 export { convertLegacyHttpOptions } from './configuration/convert-legacy-node-http-options';

experimental/packages/otlp-exporter-base/src/index-node-http.ts

@@ -37,7 +37,7 @@ class HttpExporterTransport implements IExporterTransport {
   constructor(private _parameters: HttpRequestParameters) {}
 
   async send(data: Uint8Array, timeoutMillis: number): Promise<ExportResponse> {
-    const { agent, send } = this._loadUtils();
+    const { agent, send } = await this._loadUtils();
 
     return new Promise<ExportResponse>(resolve => {
       send(
@@ -56,22 +56,20 @@ class HttpExporterTransport implements IExporterTransport {
     // intentionally left empty, nothing to do.
   }
 
-  private _loadUtils(): Utils {
+  private async _loadUtils(): Promise<Utils> {
     let utils = this._utils;
 
     if (utils === null) {
-      // Lazy require to ensure that http/https is not required before instrumentations can wrap it.
-      const {
-        sendWithHttp,
-        createHttpAgent,
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-      } = require('./http-transport-utils');
+      // Lazy import to ensure that http/https is not required before instrumentations can wrap it.
+      const imported = await import('./http-transport-utils.js');
 
       utils = this._utils = {
-        agent:
-          this._parameters.agent ??
-          createHttpAgent(this._parameters.url, this._parameters.agentOptions),
-        send: sendWithHttp,
+        agent: await this._parameters.agent(
+          new URL(this._parameters.url).protocol
+        ),
+        // @ts-expect-error dynamic imports are never transpiled, but named exports only work when
+        // dynamically importing an esm file, and the utils file might be transpiled to cjs
+        send: imported.sendWithHttp ?? imported.default.sendWithHttp,
       };
     }
 

experimental/packages/otlp-exporter-base/src/transport/http-exporter-transport.ts

@@ -17,6 +17,7 @@
 import type * as http from 'http';
 import type * as https from 'https';
 import { ExportResponse } from '../export-response';
+import { HttpAgentFactory } from '../configuration/otlp-http-configuration';
 
 export type sendWithHttp = (
   params: HttpRequestParameters,
@@ -30,6 +31,5 @@ export interface HttpRequestParameters {
   url: string;
   headers: () => Record<string, string>;
   compression: 'gzip' | 'none';
-  agentOptions: http.AgentOptions | https.AgentOptions;
-  agent?: http.Agent | https.Agent;
+  agent: HttpAgentFactory;
 }

experimental/packages/otlp-exporter-base/src/transport/http-transport-types.ts

@@ -141,12 +141,3 @@ function readableFromUint8Array(buff: string | Uint8Array): Readable {
 
   return readable;
 }
-
-export function createHttpAgent(
-  rawUrl: string,
-  agentOptions: http.AgentOptions | https.AgentOptions
-) {
-  const parsedUrl = new URL(rawUrl);
-  const Agent = parsedUrl.protocol === 'http:' ? http.Agent : https.Agent;
-  return new Agent(agentOptions);
-}

experimental/packages/otlp-exporter-base/src/transport/http-transport-utils.ts

@@ -19,6 +19,7 @@ import {
   OtlpHttpConfiguration,
 } from '../../../src/configuration/otlp-http-configuration';
 import * as assert from 'assert';
+import * as http from 'http';
 import { testSharedConfigBehavior } from './shared-configuration.test';
 
 describe('mergeOtlpHttpConfigurationWithDefaults', function () {
@@ -28,7 +29,7 @@ describe('mergeOtlpHttpConfigurationWithDefaults', function () {
     compression: 'none',
     concurrencyLimit: 2,
     headers: () => ({ 'User-Agent': 'default-user-agent' }),
-    agentOptions: { keepAlive: true },
+    agent: () => new http.Agent({ keepAlive: true }),
   };
 
   describe('headers', function () {