Merge branch 'main' into mock-otlp-server-proxy

packages/opentelemetry-node/docs/supported-technologies.md

@@ -33,16 +33,16 @@ requires:
 
 ## Instrumentations
 
-| Name | Packages instrumented | Reference |
+| Name | Packages instrumented | Notes |
 |---|---|---|
 | `@elastic/opentelemetry-instrumentation-openai` | `openai` version range `>=4.19.0 <5` | [README](https://github.com/elastic/elastic-otel-node/tree/main/packages/instrumentation-openai#readme) |
 | `@opentelemetry/instrumentation-amqplib` | `amqplib` version range `>=0.5.5 <1` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-amqplib#readme) |
 | `@opentelemetry/instrumentation-aws-sdk` | `aws-sdk` v2 and `@aws-sdk/client-*` v3 | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-aws-sdk#readme) |
 | `@opentelemetry/instrumentation-bunyan` | `bunyan` version range `^1.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-bunyan#readme) |
 | `@opentelemetry/instrumentation-cassandra-driver` | `cassandra-driver` version range `>=4.4.0 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-cassandra#readme) |
 | `@opentelemetry/instrumentation-express` | `express` version range `^4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express#readme) |
-| `@opentelemetry/instrumentation-fastify` | `fastify` version range `>=3 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-fastify#readme) |
-| `@opentelemetry/instrumentation-fs` | `fs` module for suppported Node.js versions | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-fs#readme) |
+| `@opentelemetry/instrumentation-fastify` | `fastify` version range `>=3 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-fastify#readme), [disabled by default](#disabled-instrumentations) |
+| `@opentelemetry/instrumentation-fs` | `fs` module for suppported Node.js versions | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-fs#readme), [disabled by default](#disabled-instrumentations) |
 | `@opentelemetry/instrumentation-generic-pool` | `generic-pool` version range `2 - 2.3, ^2.4, >=3` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-generic-pool#readme) |
 | `@opentelemetry/instrumentation-graphql` | `graphql` version range `>=14.0.0 <17` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-graphql#readme) |
 | `@opentelemetry/instrumentation-grpc` | `@grpc/grpc-js` version range `^1.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc#readme) |
@@ -70,6 +70,25 @@ requires:
 | `@opentelemetry/instrumentation-undici` | `undici` version range `>=5.12.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-undici#readme) |
 | `@opentelemetry/instrumentation-winston` | `winston` version range `>1 <4` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-winston#readme) |
 
+### Disabled instrumentations
+
+The following instrumentations are included in EDOT Node.js, but *disabled by default*:
+
+- `@opentelemetry/instrumentation-fs` (Disabled upstream in [open-telemetry/opentelemetry-js-contrib#2467](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2467).)
+- `@opentelemetry/instrumentation-fastify` (Deprecated upstream and slated for removal. See [open-telemetry/opentelemetry-js-contrib#2652](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2652))
+
+To enable these instrumentations, use the `OTEL_NODE_ENABLED_INSTRUMENTATIONS` environment variable, as documented [here in the OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/js/configuration/#excluding-instrumentation-libraries). Make sure you list all the instrumentations you need for your service since only the ones in that list will be enabled. For example:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l"
+export OTEL_NODE_ENABLED_INSTRUMENTATIONS="fs,http,fastify" # only the ones in the list would be enabled
+node --import @elastic/opentelemetry-node my-service.js
+```
+
+EDOT Node.js uses the upstream [`@opentelemetry/auto-instrumentations-node` package's set of instrumentations](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-instrumentations-node/README.md#supported-instrumentations) as a guide for instrumentations to include, exclude, or disable by default. This is to maximize compatibility between usage of EDOT Node.js and the vanilla OpenTelemetry JS SDK.
+
+
 ## Native Instrumentations
 
 "Native" instrumentation refers to OpenTelemetry instrumentation that is built into a library. When a library includes native OTel instrumentation, it will provide telemetry data to providers registered by a running OTel SDK. Native instrumentations of note are listed in the table below. To benefit from these instrumentations you only need to (a) use the library and (b) start the EDOT Node.js SDK:

packages/opentelemetry-node/lib/instrumentations.js

@@ -164,6 +164,11 @@ const INSTRUMENTATIONS = {
 };
 /* eslint-enable prettier/prettier */
 
+const EXCLUDED_INSTRUMENTATIONS = new Set([
+    '@opentelemetry/instrumentation-fastify',
+    '@opentelemetry/instrumentation-fs',
+]);
+
 /**
  * Reads a string in the format `value1,value2` and parses
  * it into an array. This is the format specified for comma separated
@@ -288,9 +293,9 @@ function getInstrumentations(opts = {}) {
 
         if (enabledFromEnv) {
             instrConfig = {...instrConfig, enabled: true};
-        } else if (name === '@opentelemetry/instrumentation-fs') {
-            // if `fs` not present in envvar instrumentation is disabled
-            // unless an explicit config says the opposite
+        } else if (EXCLUDED_INSTRUMENTATIONS.has(name)) {
+            // if excluded instrumentations not present in envvar the instrumentation
+            // is disabled unless an explicit config says the opposite
             // ref: https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2467
             instrConfig = {enabled: false, ...instrConfig};
         }

packages/opentelemetry-node/test/instr-fastify.test.js

@@ -29,7 +29,7 @@ const {
 /** @type {import('./testutils').TestFixture[]} */
 const testFixtures = [
     {
-        name: 'use-fastify',
+        name: 'use-fastify (default disabled)',
         args: ['./fixtures/use-fastify.js'],
         cwd: __dirname,
         env: {
@@ -40,6 +40,40 @@ const testFixtures = [
             node: '>=20.0.0',
         },
         // verbose: true,
+        checkTelemetry: (t, col) => {
+            const spans = filterOutDnsNetSpans(col.sortedSpans);
+
+            t.equal(spans.length, 4);
+            t.ok(
+                spans.every(
+                    (s) =>
+                        s.scope.name === '@opentelemetry/instrumentation-http'
+                )
+            );
+            t.ok(spans.every((s) => s.name === 'GET'));
+            t.equal(
+                spans.filter((s) => s.kind === 'SPAN_KIND_CLIENT').length,
+                2
+            );
+            t.equal(
+                spans.filter((s) => s.kind === 'SPAN_KIND_SERVER').length,
+                2
+            );
+        },
+    },
+    {
+        name: 'use-fastify (enabled via env var)',
+        args: ['./fixtures/use-fastify.js'],
+        cwd: __dirname,
+        env: {
+            NODE_OPTIONS: '--require=@elastic/opentelemetry-node',
+            OTEL_NODE_ENABLED_INSTRUMENTATIONS: 'http,fastify',
+        },
+        versionRanges: {
+            // Ref: https://fastify.dev/docs/latest/Guides/Migration-Guide-V5/#long-term-support-cycle
+            node: '>=20.0.0',
+        },
+        // verbose: true,
         checkTelemetry: (t, col) => {
             // We expect spans like this
             // ------ trace 9042af (3 spans) ------