@saidsef/tracing-node 6.0.0 → 7.0.0

package/README.md

@@ -26,15 +26,30 @@ Full documentation: [tracing-node.readthedocs.io](https://tracing-node.readthedo
 npm install @saidsef/tracing-node --save
 ```
 
+Elasticsearch spans carrying the query, the operation and the index name need an optional peer dependency:
+
+```shell
+npm install opentelemetry-instrumentation-elasticsearch --save
+```
+
+That package pins `@opentelemetry/core` to the 1.x line, so installing it brings [GHSA-8988-4f7v-96qf](https://github.com/advisories/GHSA-8988-4f7v-96qf) into the dependency tree. Without it, an Elasticsearch call is still traced as an HTTP client span and still appears on the service graph. See [Instrumentation](https://tracing-node.readthedocs.io/en/latest/instrumentation/) for what each option records.
+
 ## Usage
 
 ```javascript
+// instrument.mjs
 import { setupTracing } from '@saidsef/tracing-node';
 
 setupTracing({hostname: 'hostname', serviceName: 'service_name', url: 'endpoint'});
 ```
 
-`serviceName` and `url` are required, and both fall back to the `SERVICE_NAME` and `ENDPOINT` environment variables. `setupTracing` has to run before the application imports the libraries being traced.
+```shell
+node --import ./instrument.mjs ./app.mjs
+```
+
+`serviceName` and `url` are required, and both fall back to the `SERVICE_NAME` and `ENDPOINT` environment variables.
+
+`setupTracing` has to run before the application imports the libraries being traced, which is what the `--import` preload guarantees. The library registers the `import-in-the-middle` loader hook on import, so ES modules and CommonJS modules are both patched. Importing an instrumented package statically in the same file as the library loads it too early to be patched, so the preload is the form to reach for. [Initialisation order](https://tracing-node.readthedocs.io/en/latest/usage/#initialisation-order) covers the alternatives.
 
 ## Collector and backend
 

package/libs/esm-hook.mjs

@@ -0,0 +1,42 @@
+/*
+ * Copyright Said Sef
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {register} from 'node:module';
+
+// A loader hook only reaches modules imported after it registers, so this lives
+// in its own module and is the first import of index.mjs, ahead of every
+// instrumentation. import.meta.url resolves the hook against this package:
+// import-in-the-middle sits in the library's own tree, not the consumer's.
+
+const FALSEY = ['false', '0'];
+
+const enabled = !FALSEY.includes((process.env.TRACING_NODE_ESM_HOOK ?? '').toLowerCase());
+
+let failure = null;
+
+if (enabled) {
+  try {
+    register('import-in-the-middle/hook.mjs', import.meta.url);
+  } catch (error) {
+    failure = error;
+  }
+}
+
+/** Whether the ESM loader hook is in place, so ES module imports get patched. */
+export const esmHookRegistered = enabled && failure === null;
+
+/** The error that stopped registration, reported by index.mjs once diag has a logger. */
+export const esmHookFailure = failure;

package/libs/index.mjs

@@ -14,13 +14,15 @@
  * limitations under the License.
  */
 
+// First, and deliberately: registering the ESM loader hook has to happen before
+// any instrumented module is imported.
+import {esmHookFailure} from './esm-hook.mjs';
 import {AwsInstrumentation} from '@opentelemetry/instrumentation-aws-sdk';
 import {BatchSpanProcessor} from '@opentelemetry/sdk-trace-base';
 import {ConnectInstrumentation} from '@opentelemetry/instrumentation-connect';
 import {diag, DiagConsoleLogger, DiagLogLevel, metrics} from '@opentelemetry/api';
 import {HttpInstrumentation} from '@opentelemetry/instrumentation-http';
 import {DnsInstrumentation} from '@opentelemetry/instrumentation-dns';
-import {ElasticsearchInstrumentation} from 'opentelemetry-instrumentation-elasticsearch';
 import {ExpressInstrumentation, ExpressLayerType} from '@opentelemetry/instrumentation-express';
 import {logs} from '@opentelemetry/api-logs';
 import {NodeTracerProvider} from '@opentelemetry/sdk-trace-node';
@@ -41,6 +43,27 @@ import {ATTR_CONTAINER_NAME} from '@opentelemetry/semantic-conventions/incubatin
 
 diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);
 
+// Reported here rather than where it happens, because the hook registers before
+// this logger exists and the warning would go nowhere.
+if (esmHookFailure) {
+  diag.warn(`ESM loader hook not registered, so ES module imports are not instrumented: ${esmHookFailure.message}`);
+}
+
+// An optional peer dependency: it pins @opentelemetry/core 1.x, which carries a
+// published advisory. Absent, an Elasticsearch call still gets a client span from
+// the http or undici instrumentation. See #576.
+let ElasticsearchInstrumentation = null;
+try {
+  ({ElasticsearchInstrumentation} = await import('opentelemetry-instrumentation-elasticsearch'));
+} catch (error) {
+  // Absence is the expected case. An installed but unloadable package would
+  // otherwise vanish silently, and tracing must not take the application down.
+  if (error?.code !== 'ERR_MODULE_NOT_FOUND') {
+    diag.warn('opentelemetry-instrumentation-elasticsearch failed to load:', error);
+  }
+}
+
+
 // Set a non-negative integer span attribute from a header value; ignore invalid input.
 const setIntAttribute = (span, name, value) => {
   if (!value) return;
@@ -107,9 +130,10 @@ let loggerProvider = null;
 *
 * This function configures a NodeTracerProvider with various instrumentations
 * and span processors to enable tracing for the application. It supports
-* tracing for HTTP, Express, AWS, Pino, DNS, Elasticsearch, and IORedis.
-* The IORedis instrumentation includes peer.service attributes for proper
-* service map visualization in distributed tracing tools like Tempo.
+* tracing for HTTP, Express, AWS, Pino, DNS, and IORedis, and for Elasticsearch
+* when the optional opentelemetry-instrumentation-elasticsearch package is
+* installed. The IORedis instrumentation includes peer.service attributes for
+* proper service map visualization in distributed tracing tools like Tempo.
 *
 * A MeterProvider is registered alongside it, which is what makes the
 * instrumentations record the request duration histograms they already
@@ -347,7 +371,7 @@ export function setupTracing(options = {}) {
         return `${cmdName} ${args.join(' ')}`;
       },
     }),
-    new ElasticsearchInstrumentation(),
+    ...(ElasticsearchInstrumentation ? [new ElasticsearchInstrumentation()] : []),
     // Event loop delay, GC pauses and heap occupancy are metric-only, and they
     // are what explains a whole service slowing at once. Constructed only with
     // metrics on, since the collectors start sampling on construction.

package/libs/index.test.mjs

@@ -1,6 +1,7 @@
 // index.test.mjs
 import { describe, it, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert';
+import { execFileSync } from 'node:child_process';
 import { metrics } from '@opentelemetry/api';
 import { logs } from '@opentelemetry/api-logs';
 import { MeterProvider } from '@opentelemetry/sdk-metrics';
@@ -262,3 +263,36 @@ describe('express request hook', () => {
     assert.deepStrictEqual(span.attributes, {});
   });
 });
+
+// A loader hook registers once per process, so the opt-out cannot be exercised
+// in this one. Each case reads the module in a child process instead.
+describe('ESM loader hook', () => {
+  const hookModule = new URL('./esm-hook.mjs', import.meta.url).href;
+
+  const registeredWith = (value) => {
+    const env = {...process.env};
+    delete env.TRACING_NODE_ESM_HOOK;
+    if (value !== undefined) {
+      env.TRACING_NODE_ESM_HOOK = value;
+    }
+    return execFileSync(process.execPath, [
+      '--input-type=module',
+      '--eval',
+      `import {esmHookRegistered} from ${JSON.stringify(hookModule)}; console.log(esmHookRegistered);`,
+    ], {env, encoding: 'utf8'}).trim();
+  };
+
+  it('should register by default', () => {
+    assert.strictEqual(registeredWith(undefined), 'true');
+  });
+
+  it('should skip registration when opted out', () => {
+    assert.strictEqual(registeredWith('false'), 'false');
+    assert.strictEqual(registeredWith('0'), 'false');
+  });
+
+  it('should register for any other value', () => {
+    assert.strictEqual(registeredWith('true'), 'true');
+    assert.strictEqual(registeredWith(''), 'true');
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saidsef/tracing-node",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
   "main": "libs/index.mjs",
   "scripts": {
@@ -54,14 +54,21 @@
     "@opentelemetry/sdk-trace-base": "^2.11.0",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
-    "opentelemetry-instrumentation-elasticsearch": "^0.41.0"
+    "import-in-the-middle": "^3.0.0"
   },
   "devDependencies": {
     "eslint": "^10.10.0"
   },
+  "peerDependencies": {
+    "opentelemetry-instrumentation-elasticsearch": "^0.41.0"
+  },
+  "peerDependenciesMeta": {
+    "opentelemetry-instrumentation-elasticsearch": {
+      "optional": true
+    }
+  },
   "overrides": {
-    "protobufjs": "^7.5.3",
-    "@opentelemetry/core": "^2.11.0"
+    "protobufjs": "^7.5.3"
   },
   "allowScripts": {
     "protobufjs@7.6.6": true