feat: ESM support for instrumentation

examples/esm-http-ts/README.md

@@ -0,0 +1,25 @@
+# Overview
+
+This is a simple example that demonstrates tracing HTTP request, with an app written in TypeScript and transpiled to ES Modules.
+
+## Installation
+
+```sh
+# from this directory
+npm install
+npm run build
+npm start
+```
+
+In a separate terminal, `curl localhost:3000`.
+
+See two spans in the console (one manual, one for http instrumentation)
+
+## Useful links
+
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on OpenTelemetry for Node.js, visit: <https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node>
+
+## LICENSE
+
+Apache License 2.0

examples/esm-http-ts/index.ts

@@ -0,0 +1,43 @@
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import { trace, DiagConsoleLogger, DiagLogLevel, diag } from '@opentelemetry/api';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import {
+  ConsoleSpanExporter,
+  SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { Resource } from '@opentelemetry/resources';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+import http from 'http';
+
+diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
+const tracerProvider = new NodeTracerProvider({
+  resource: new Resource({
+    [SemanticResourceAttributes.SERVICE_NAME]: 'esm-http-ts-example',
+  }),
+});
+const exporter = new ConsoleSpanExporter();
+const processor = new SimpleSpanProcessor(exporter);
+tracerProvider.addSpanProcessor(processor);
+tracerProvider.register();
+
+registerInstrumentations({
+  instrumentations: [new HttpInstrumentation()],
+});
+
+const hostname = '0.0.0.0';
+const port = 3000;
+
+const server = http.createServer((req, res) => {
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/plain');
+  const tracer = trace.getTracer('esm-tracer');
+  tracer.startActiveSpan('manual', span => {
+    span.end();
+  });
+  res.end('Hello, World!\n');
+});
+
+server.listen(port, hostname, () => {
+  console.log(`Server running at http://${hostname}:${port}/`);
+});

examples/esm-http-ts/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "esm-http-ts",
+  "private": true,
+  "version": "0.38.0",
+  "description": "Example of HTTP integration with OpenTelemetry using ESM and TypeScript",
+  "main": "build/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc --build",
+    "start": "node --experimental-import-meta-resolve --experimental-loader=@opentelemetry/instrumentation/hook.mjs ./build/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://[email protected]/open-telemetry/opentelemetry-js.git"
+  },
+  "keywords": [
+    "opentelemetry",
+    "http",
+    "tracing",
+    "esm",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/open-telemetry/opentelemetry-js/issues"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/",
+  "dependencies": {
+    "@opentelemetry/api": "^1.4.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.36.0",
+    "@opentelemetry/instrumentation": "0.38.0",
+    "@opentelemetry/instrumentation-http": "0.38.0",
+    "@opentelemetry/resources": "^1.9.1",
+    "@opentelemetry/sdk-trace-base": "^1.9.1",
+    "@opentelemetry/sdk-trace-node": "^1.9.1",
+    "@opentelemetry/semantic-conventions": "^1.9.1"
+  }
+}

examples/esm-http-ts/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    /* Language and Environment */
+    "target": "ES2020" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+
+    /* Modules */
+    "module": "ESNext" /* Specify what module code is generated. */,
+    "rootDir": "." /* Specify the root folder within your source files. */,
+    "moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
+    "resolveJsonModule": true /* Enable importing .json files. */,
+
+    /* Emit */
+    "outDir": "build" /* Specify an output folder for all emitted files. */,
+
+    /* Interop Constraints */
+    "allowSyntheticDefaultImports": true /* Allow 'import x from y' when a module doesn't have a default export. */,
+    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
+    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+
+    /* Completeness */
+    "skipLibCheck": true /* Skip type checking all .d.ts files. */
+  },
+  "include": ["**/*.ts", "**/*.js", "*.config.js"],
+  "exclude": ["node_modules"]
+}

experimental/CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to experimental packages in this project will be documented
 
 ### :rocket: (Enhancement)
 
+* feat(instrumentation): add ESM support for instrumentation [#3698](https://github.com/open-telemetry/opentelemetry-js/pull/3698) @JamieDanielson, @pkanal, @vmarchaud, @lizthegrey, @bengl
 * feat(otlp-transformer): support log records. [#3712](https://github.com/open-telemetry/opentelemetry-js/pull/3712/) @llc1123
 * feat(otlp-grpc-exporter-base): support log records. [#3712](https://github.com/open-telemetry/opentelemetry-js/pull/3712/) @llc1123
 * feat(exporter-logs-otlp-grpc): otlp-grpc exporter for logs. [#3712](https://github.com/open-telemetry/opentelemetry-js/pull/3712/) @llc1123

experimental/packages/opentelemetry-instrumentation-http/src/http.ts

@@ -66,7 +66,6 @@ import { SemanticAttributes } from '@opentelemetry/semantic-conventions';
 export class HttpInstrumentation extends InstrumentationBase<Http> {
   /** keep track on spans not ended */
   private readonly _spanNotEnded: WeakSet<Span> = new WeakSet<Span>();
-  private readonly _version = process.versions.node;
   private _headerCapture;
   private _httpServerDurationHistogram!: Histogram;
   private _httpClientDurationHistogram!: Histogram;
@@ -112,11 +111,12 @@ export class HttpInstrumentation extends InstrumentationBase<Http> {
   }
 
   private _getHttpInstrumentation() {
+    const version = process.versions.node;
     return new InstrumentationNodeModuleDefinition<Http>(
       'http',
       ['*'],
       moduleExports => {
-        this._diag.debug(`Applying patch for http@${this._version}`);
+        this._diag.debug(`Applying patch for http@${version}`);
         if (isWrapped(moduleExports.request)) {
           this._unwrap(moduleExports, 'request');
         }
@@ -145,7 +145,7 @@ export class HttpInstrumentation extends InstrumentationBase<Http> {
       },
       moduleExports => {
         if (moduleExports === undefined) return;
-        this._diag.debug(`Removing patch for http@${this._version}`);
+        this._diag.debug(`Removing patch for http@${version}`);
 
         this._unwrap(moduleExports, 'request');
         this._unwrap(moduleExports, 'get');
@@ -155,11 +155,12 @@ export class HttpInstrumentation extends InstrumentationBase<Http> {
   }
 
   private _getHttpsInstrumentation() {
+    const version = process.versions.node;
     return new InstrumentationNodeModuleDefinition<Https>(
       'https',
       ['*'],
       moduleExports => {
-        this._diag.debug(`Applying patch for https@${this._version}`);
+        this._diag.debug(`Applying patch for https@${version}`);
         if (isWrapped(moduleExports.request)) {
           this._unwrap(moduleExports, 'request');
         }
@@ -188,7 +189,7 @@ export class HttpInstrumentation extends InstrumentationBase<Http> {
       },
       moduleExports => {
         if (moduleExports === undefined) return;
-        this._diag.debug(`Removing patch for https@${this._version}`);
+        this._diag.debug(`Removing patch for https@${version}`);
 
         this._unwrap(moduleExports, 'request');
         this._unwrap(moduleExports, 'get');

experimental/packages/opentelemetry-instrumentation/README.md

@@ -263,6 +263,12 @@ If nothing is specified the global registered provider is used. Usually this is
 There might be usecase where someone has the need for more providers within an application. Please note that special care must be takes in such setups
 to avoid leaking information from one provider to the other because there are a lot places where e.g. the global `ContextManager` or `Propagator` is used.
 
+## Instrumentation for ES Modules In NodeJS (experimental)
+
+As the module loading mechanism for ESM is different than CJS, you need to select a custom loader so instrumentation can load hook on the esm module it want to patch. To do so, you must provide the `--experimental-loader=@opentelemetry/instrumentation/hook.mjs --experimental-import-meta-resolve` flag to the `node` binary. Alternatively you can set the `NODE_OPTIONS` environment variable to `NODE_OPTIONS="--experimental-loader=@opentelemetry/instrumentation/hook.mjs --experimental-import-meta-resolve"`.
+To avoid using the `--experimental-import-meta-resolve` flag, the hook file can be referenced directly from the `import-in-the-middle` library as `--experimental-loader=import-in-the-middle/hook.mjs`.
+As the ESM module loader from NodeJS is experimental, so is our support for it. Feel free to provide feedback or report issues about it.
+
 ## License
 
 Apache 2.0 - See [LICENSE][license-url] for more information.