@saidsef/tracing-node 6.1.0 → 7.0.1

package/CONTRIBUTING.md

@@ -1,15 +1,16 @@
 # Contributing
 
-When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
+Please open an issue to discuss a change before you make it, or reach the owners of this repository by email or whatever other route you prefer. Agreeing the shape of a change first saves rework on both sides.
 
-Please note we have a code of conduct, please follow it in all your interactions with the project.
+This project has a code of conduct. It applies to every interaction with the project, so please follow it.
 
 ## Pull Request Process
 
-1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
-2. Update the `package.json`, run `npm run rebuild` and add commit message with details of changes, this includes new environment variables, useful file locations and parameters.
-3. Increase the version numbers is managed by the GitHub Actions CI workflow via `tagging.yml` and `release.yml`
-4. You may merge the Pull Request in once you have the sign-off of from the project team, or if you do not have permission to do that, you may request a reviewer to merge it for you.
+1. Run `npm run lint` and `npm test` locally. Both need to pass before you open the pull request.
+2. Bump the version in `package.json`, with the increment matching the scope of your change. Run `npm run rebuild` where you have changed a dependency, which refreshes `package-lock.json`.
+3. Describe the change in the commit message. Name any new environment variable, option or file path that a user of the library will need to know about.
+4. The `Release` workflow reads the version from `package.json`, tags `v<version>`, publishes the GitHub release and pushes the package to npm. You do not need to create a tag yourself.
+5. A member of the project team signs the pull request off before it merges. Ask a reviewer to merge it for you where you do not have permission to do it yourself.
 
 ## Code of Conduct
 

package/README.md

@@ -8,9 +8,9 @@
 ![GitHub release(latest by date)](https://img.shields.io/github/v/release/saidsef/tracing-node)
 ![Commits](https://img.shields.io/github/commits-since/saidsef/tracing-node/latest.svg)
 
-**Traces, metrics and logs from one function call.** Add two lines to a service, and its requests, its calls to Redis, Elasticsearch, AWS and other services, its runtime counters and its Pino log records all arrive at your collector, already correlated by trace id and stitched into a service graph.
+**Traces, metrics and logs from one function call.** Add two lines to a service and everything it does arrives at your collector: its requests, its calls to Redis, Elasticsearch and AWS, its runtime counters, its Pino log records. All of it correlated by trace id and stitched into a service graph.
 
-`@saidsef/tracing-node` wraps the OpenTelemetry Node SDK. One call to `setupTracing` builds the tracer, meter and logger providers, registers them globally, and turns on a fixed set of instrumentations, so an application gets all three signals without assembling exporters, span processors, resource detectors and instrumentation packages itself. A second call logs a warning and returns the tracer that already exists, which makes initialisation idempotent.
+`@saidsef/tracing-node` wraps the OpenTelemetry Node SDK. One call to `setupTracing` builds the tracer, meter and logger providers, registers them globally, and turns on a fixed set of instrumentations. An application gets all three signals without assembling exporters, span processors, resource detectors and instrumentation packages itself. A second call logs a warning and returns the tracer that already exists, which makes initialisation idempotent.
 
 Full documentation: [tracing-node.readthedocs.io](https://tracing-node.readthedocs.io/).
 
@@ -26,6 +26,14 @@ 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. Leave it out and an Elasticsearch call is still traced as an HTTP client span, still on the service graph. See [Instrumentation](https://tracing-node.readthedocs.io/en/latest/instrumentation/) for what each option records.
+
 ## Usage
 
 ```javascript
@@ -41,11 +49,11 @@ 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.
+`setupTracing` has to run before the application imports the libraries being traced, and the `--import` preload guarantees it. The library registers the `import-in-the-middle` loader hook on import, which covers ES modules and CommonJS modules alike. Importing an instrumented package statically in the same file as the library loads it too early to patch, so reach for the preload. [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.
+The exporter speaks OTLP over gRPC, which any OpenTelemetry-compatible collector accepts for 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.
 
@@ -54,7 +62,7 @@ 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.
+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. Feeding those is why this library sets the `peer.service` attribute.
 
 ## Documentation
 

package/libs/index.mjs

@@ -23,7 +23,6 @@ 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';
@@ -50,6 +49,21 @@ 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;
@@ -116,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
@@ -356,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saidsef/tracing-node",
-  "version": "6.1.0",
+  "version": "7.0.1",
   "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
   "main": "libs/index.mjs",
   "scripts": {
@@ -54,15 +54,21 @@
     "@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"
+    "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