@saidsef/tracing-node 5.0.1 → 6.1.0

package/README.md

@@ -15,7 +15,7 @@
 Full documentation: [tracing-node.readthedocs.io](https://tracing-node.readthedocs.io/).
 
 ## Prerequisites
-- NodeJS
+- NodeJS >= 24.0.0
 - Observability
 - ...
 - Profit?
@@ -29,12 +29,32 @@ npm install @saidsef/tracing-node --save
 ## 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
+
+The exporter speaks OTLP over gRPC, so any OpenTelemetry-compatible collector accepts all three signals. Point `url` at yours.
+
+[**grafana-loki-on-k8s**](https://github.com/saidsef/grafana-loki-on-k8s) is the companion stack, and the one the end to end harness in [`test/e2e/`](./test/e2e) targets. It deploys Grafana, Prometheus, Mimir, Loki, Tempo, Pyroscope, Alloy and Beyla to Kubernetes as small composable manifests.
+
+```shell
+git clone https://github.com/saidsef/grafana-loki-on-k8s
+kubectl apply -k grafana-loki-on-k8s/deployment
+```
+
+Traces sent to its Alloy OTLP receiver on port 4317 land in Tempo, log records in Loki and metrics in Mimir. Tempo's metrics generator turns the spans into RED and service graph metrics, which is what the `peer.service` attribute this library sets exists to feed.
 
 ## Documentation
 

package/deployment/base/job.yml

@@ -12,7 +12,7 @@ spec:
   preemptionPolicy: PreemptLowerPriority
   containers:
   - name: tracing-node
-    image: docker.io/node:20-alpine3.19
+    image: docker.io/node:24-alpine
     workingDir: "/app"
     command:
       - /bin/sh

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,6 +14,9 @@
  * 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';
@@ -41,6 +44,12 @@ 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}`);
+}
+
 // Set a non-negative integer span attribute from a header value; ignore invalid input.
 const setIntAttribute = (span, name, value) => {
   if (!value) return;

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": "5.0.1",
+  "version": "6.1.0",
   "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
   "main": "libs/index.mjs",
   "scripts": {
@@ -25,7 +25,7 @@
   "author": "Said Sef <saidsef@gmail.com>",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">= 20.6.0"
+    "node": ">= 24.0.0"
   },
   "bugs": {
     "url": "https://github.com/saidsef/tracing-node/issues"
@@ -54,6 +54,7 @@
     "@opentelemetry/sdk-trace-base": "^2.11.0",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
+    "import-in-the-middle": "^3.0.0",
     "opentelemetry-instrumentation-elasticsearch": "^0.41.0"
   },
   "devDependencies": {