feat(auto-instrumentations-node): Add "@opentelemetry/auto-instrumentations-node/register" for an agent-like experience (open-telemetry#1400)

* feat(auto-instrumentation-agent): added intrumentation-agent package

* feat(auto-instrumentation-agent): added api peer dependency

* feat(auto-instrumentation-agent): updated test

* feat(auto-instrumentation-agent): updated release please config

* feat(auto-instrumentation-agent): updated .release-please-manifest

* feat(auto-instrumentation-agent): updated test timeout

* feat(auto-instrumentation-agent): removed timeout, added pretest script

* feat(auto-instrumentation-agent): moved agent to auto-instrumentations-node

* feat(auto-instrumentation-agent): reverted release please config

* feat(auto-instrumentation-agent): updated README.md

* feat(auto-instrumentation-agent): added env variable for resource detector configuration

* feat(auto-instrumentation-agent): removed no-process-exit

* feat(auto-instrumentation-agent): removed pretest script

* feat(auto-instrumentation-agent): fixed lint issues

* feat(auto-instrumentation-agent): updated register test

* feat(auto-instrumentation-agent): fixed typo in test

* feat(auto-instrumentation-agent): using env instead of export

* feat(auto-instrumentation-agent): updated eslint.config.js

* feat(auto-instrumentation-agent): updated test

* feat(auto-instrumentation-agent): using language specific env var name

* feat(auto-instrumentation-agent): updated README.md

* feat(auto-instrumentation-agent): updated dependencies

* feat(auto-instrumentation-agent): fixed detector test

* feat(auto-instrumentation-agent): added comment to test app

* feat(auto-instrumentation-agent): small refactor

* feat(auto-instrumentation-agent): updated log messages

* feat(auto-instrumentation-agent): added missing aws detectors

* feat(auto-instrumentation-agent): updated tests

* feat(auto-instrumentation-agent): updated getResourceDetectorsFromEnv()

* feat(auto-instrumentation-agent): revert unnecessary changes

* feat(auto-instrumentation-agent): added reference to supported instrumentations

* feat(auto-instrumentation-agent): added reference to env var spec

* feat(auto-instrumentation-agent): added reference node documentation

* feat(auto-instrumentation-agent): added note for unsupported config

* feat(auto-instrumentation-agent): added note to the debug section

* feat(auto-instrumentation-agent): moved opentelemetry/api to regular dependency

* feat(auto-instrumentation-agent): fixed lint issue

* feat(auto-instrumentation-agent): re-added peer dep

* feat(auto-instrumentation-agent): re-added api dev dep

* feat(auto-instrumentation-agent): fixed lint issue

* feat(auto-instrumentation-agent): fixed lint issue

* feat(auto-instrumentation-agent): updated README.md

* feat(auto-instrumentation-agent): added exporters reference in README.md

* feat(auto-instrumentation-agent): updated debug notes

* feat(auto-instrumentation-agent): updated installation section to include the api dependency

* feat(auto-instrumentation-agent): reordered aws resource detectors

* feat(auto-instrumentation-agent): removed process.exit(0)

* feat(auto-instrumentation-agent): reordered aws resource detectors

* feat(auto-instrumentation-agent): replaced type any with actual types

* feat(auto-instrumentation-agent): updated utils test

* feat(auto-instrumentation-agent): updated register test

* feat(auto-instrumentation-agent): updated README.md

* feat(auto-instrumentation-agent): updated shutdown logs

* feat(auto-instrumentation-agent): fixed sinon issue

Author: samimusallam

metapackages/auto-instrumentations-node/README.md

@@ -3,17 +3,97 @@
 [![NPM Published Version][npm-img]][npm-url]
 [![Apache License][license-image]][license-url]
 
-This module provides a simple way to initialize multiple Node instrumentations.
+## About
+
+This module provides a way to auto instrument any Node application to capture telemetry from a number of popular libraries and frameworks.
+You can export the telemetry data in a variety of formats. Exporters, samplers, and more can be configured via [environment variables][env-var-url].
+The net result is the ability to gather telemetry data from a Node application without any code changes.
+
+This module also provides a simple way to manually initialize multiple Node instrumentations for use with the OpenTelemetry SDK.
 
 Compatible with OpenTelemetry JS API and SDK `1.0+`.
 
 ## Installation
 
 ```bash
+npm install --save @opentelemetry/api
 npm install --save @opentelemetry/auto-instrumentations-node
 ```
 
-## Usage
+## Usage: Auto Instrumentation
+
+This module includes auto instrumentation for all supported instrumentations and [all available data exporters][exporter-url].
+It provides a completely automatic, out-of-the-box experience.
+Please see the [Supported Instrumentations](#supported-instrumentations) section for more information.
+
+Enable auto instrumentation by requiring this module using the [--require flag][require-url]:
+
+```shell
+node --require '@opentelemetry/auto-instrumentations-node/register' app.js
+```
+
+If your Node application is encapsulated in a complex run script, you can also set it via an environment variable before running Node.
+
+```shell
+env NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
+```
+
+The module is highly configurable using environment variables.
+Many aspects of the auto instrumentation's behavior can be configured for your needs, such as resource detectors, exporter choice, exporter configuration, trace context propagation headers, and much more.
+Instrumentation configuration is not yet supported through environment variables. Users that require instrumentation configuration must initialize OpenTelemetry programmatically.
+
+```shell
+export OTEL_TRACES_EXPORTER="otlp"
+export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
+export OTEL_EXPORTER_OTLP_COMPRESSION="gzip"
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://your-endpoint"
+export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
+export OTEL_EXPORTER_OTLP_TRACES_HEADERS="x-api-key=your-api-key"
+export OTEL_RESOURCE_ATTRIBUTES="service.namespace=my-namespace"
+export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
+export OTEL_SERVICE_NAME="client"
+export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
+node app.js
+```
+
+By default, all SDK resource detectors are used, but you can use the environment variable OTEL_NODE_RESOURCE_DETECTORS to enable only certain detectors, or completely disable them:
+
+- `env`
+- `host`
+- `os`
+- `process`
+- `container`
+- `alibaba`
+- `aws`
+- `gcp`
+- `all` - enable all resource detectors
+- `none` - disable resource detection
+
+For example, to enable only the `env`, `host` detectors:
+
+```shell
+export OTEL_NODE_RESOURCE_DETECTORS="env,host"
+```
+
+To enable logging for troubleshooting, set the log level by setting the `OTEL_LOG_LEVEL` environment variable to one of the following:
+
+- `none`
+- `error`
+- `warn`
+- `info`
+- `debug`
+- `verbose`
+- `all`
+
+The default level is `info`.
+
+Notes:
+
+- In a production environment, it is recommended to set `OTEL_LOG_LEVEL`to `info`.
+- Logs are always sent to console, no matter the environment, or debug level.
+- Debug logs are extremely verbose. Enable debug logging only when needed. Debug logging negatively impacts the performance of your application.
+
+## Usage: Instrumentation Initialization
 
 OpenTelemetry Meta Packages for Node automatically loads instrumentations for Node builtin modules and common packages.
 
@@ -100,3 +180,6 @@ APACHE 2.0 - See [LICENSE][license-url] for more information.
 [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
 [npm-url]: https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node
 [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fauto-instrumentations-node.svg
+[env-var-url]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration
+[exporter-url]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#otlp-exporter
+[require-url]: https://nodejs.org/api/cli.html#-r---require-module

metapackages/auto-instrumentations-node/package.json

@@ -13,6 +13,10 @@
   },
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
+  "exports": {
+    ".": "./build/src/index.js",
+    "./register": "./build/src/register.js"
+  },
   "repository": "open-telemetry/opentelemetry-js-contrib",
   "scripts": {
     "clean": "rimraf build/*",
@@ -30,10 +34,10 @@
     "url": "https://github.com/open-telemetry/opentelemetry-js-contrib/issues"
   },
   "peerDependencies": {
-    "@opentelemetry/api": "^1.3.0"
+    "@opentelemetry/api": "^1.4.1"
   },
   "devDependencies": {
-    "@opentelemetry/api": "^1.3.0",
+    "@opentelemetry/api": "^1.4.1",
     "@types/mocha": "7.0.2",
     "@types/node": "18.11.7",
     "@types/sinon": "10.0.2",
@@ -82,6 +86,12 @@
     "@opentelemetry/instrumentation-router": "^0.32.2",
     "@opentelemetry/instrumentation-socket.io": "^0.33.2",
     "@opentelemetry/instrumentation-tedious": "^0.5.2",
-    "@opentelemetry/instrumentation-winston": "^0.31.2"
+    "@opentelemetry/instrumentation-winston": "^0.31.2",
+    "@opentelemetry/resource-detector-alibaba-cloud": "^0.27.4",
+    "@opentelemetry/resource-detector-aws": "^1.2.2",
+    "@opentelemetry/resource-detector-container": "^0.2.2",
+    "@opentelemetry/resource-detector-gcp": "^0.28.0",
+    "@opentelemetry/resources": "^1.12.0",
+    "@opentelemetry/sdk-node": "^0.38.0"
   }
 }

metapackages/auto-instrumentations-node/src/register.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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 * as opentelemetry from '@opentelemetry/sdk-node';
+import { diag, DiagConsoleLogger } from '@opentelemetry/api';
+import {
+  getNodeAutoInstrumentations,
+  getResourceDetectorsFromEnv,
+} from './utils';
+
+diag.setLogger(
+  new DiagConsoleLogger(),
+  opentelemetry.core.getEnv().OTEL_LOG_LEVEL
+);
+
+const sdk = new opentelemetry.NodeSDK({
+  instrumentations: getNodeAutoInstrumentations(),
+  resourceDetectors: getResourceDetectorsFromEnv(),
+});
+
+try {
+  sdk.start();
+  diag.info('OpenTelemetry automatic instrumentation started successfully');
+} catch (error) {
+  diag.error(
+    'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
+    error
+  );
+}
+
+process.on('SIGTERM', () => {
+  sdk
+    .shutdown()
+    .then(() => diag.debug('OpenTelemetry SDK terminated'))
+    .catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
+});

metapackages/auto-instrumentations-node/src/utils.ts

@@ -54,6 +54,34 @@ import { SocketIoInstrumentation } from '@opentelemetry/instrumentation-socket.i
 import { TediousInstrumentation } from '@opentelemetry/instrumentation-tedious';
 import { WinstonInstrumentation } from '@opentelemetry/instrumentation-winston';
 
+import { alibabaCloudEcsDetector } from '@opentelemetry/resource-detector-alibaba-cloud';
+import {
+  awsBeanstalkDetector,
+  awsEc2Detector,
+  awsEcsDetector,
+  awsEksDetector,
+  awsLambdaDetector,
+} from '@opentelemetry/resource-detector-aws';
+import { containerDetector } from '@opentelemetry/resource-detector-container';
+import { gcpDetector } from '@opentelemetry/resource-detector-gcp';
+import {
+  Detector,
+  DetectorSync,
+  envDetectorSync,
+  hostDetectorSync,
+  osDetectorSync,
+  processDetectorSync,
+} from '@opentelemetry/resources';
+
+const RESOURCE_DETECTOR_CONTAINER = 'container';
+const RESOURCE_DETECTOR_ENVIRONMENT = 'env';
+const RESOURCE_DETECTOR_HOST = 'host';
+const RESOURCE_DETECTOR_OS = 'os';
+const RESOURCE_DETECTOR_PROCESS = 'process';
+const RESOURCE_DETECTOR_ALIBABA = 'alibaba';
+const RESOURCE_DETECTOR_AWS = 'aws';
+const RESOURCE_DETECTOR_GCP = 'gcp';
+
 const InstrumentationMap = {
   '@opentelemetry/instrumentation-amqplib': AmqplibInstrumentation,
   '@opentelemetry/instrumentation-aws-lambda': AwsLambdaInstrumentation,
@@ -136,3 +164,49 @@ export function getNodeAutoInstrumentations(
 
   return instrumentations;
 }
+
+export function getResourceDetectorsFromEnv(): Array<Detector | DetectorSync> {
+  const resourceDetectors = new Map<
+    string,
+    Detector | DetectorSync | Detector[]
+  >([
+    [RESOURCE_DETECTOR_CONTAINER, containerDetector],
+    [RESOURCE_DETECTOR_ENVIRONMENT, envDetectorSync],
+    [RESOURCE_DETECTOR_HOST, hostDetectorSync],
+    [RESOURCE_DETECTOR_OS, osDetectorSync],
+    [RESOURCE_DETECTOR_PROCESS, processDetectorSync],
+    [RESOURCE_DETECTOR_ALIBABA, alibabaCloudEcsDetector],
+    [RESOURCE_DETECTOR_GCP, gcpDetector],
+    [
+      RESOURCE_DETECTOR_AWS,
+      [
+        awsEc2Detector,
+        awsEcsDetector,
+        awsEksDetector,
+        awsBeanstalkDetector,
+        awsLambdaDetector,
+      ],
+    ],
+  ]);
+
+  const resourceDetectorsFromEnv =
+    process.env.OTEL_NODE_RESOURCE_DETECTORS?.split(',') ?? ['all'];
+
+  if (resourceDetectorsFromEnv.includes('all')) {
+    return [...resourceDetectors.values()].flat();
+  }
+
+  if (resourceDetectorsFromEnv.includes('none')) {
+    return [];
+  }
+
+  return resourceDetectorsFromEnv.flatMap(detector => {
+    const resourceDetector = resourceDetectors.get(detector);
+    if (!resourceDetector) {
+      diag.error(
+        `Invalid resource detector "${detector}" specified in the environment variable OTEL_NODE_RESOURCE_DETECTORS`
+      );
+    }
+    return resourceDetector || [];
+  });
+}

metapackages/auto-instrumentations-node/test/register.test.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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 { promisify } from 'util';
+import * as childProcess from 'child_process';
+import * as assert from 'assert';
+
+const exec = promisify(childProcess.exec);
+
+describe('Register', function () {
+  this.timeout(5000);
+  it('can load auto instrumentation from command line', async () => {
+    process.env.OTEL_NODE_RESOURCE_DETECTORS = 'none';
+    process.env.OTEL_TRACES_EXPORTER = 'console';
+
+    const { stdout } = await exec(
+      'node --require ./build/src/register.js ./test/test-app/app.js'
+    );
+
+    assert.ok(
+      stdout.includes(
+        'OpenTelemetry automatic instrumentation started successfully'
+      )
+    );
+
+    //Check a span has been generated for the GET request done in app.js
+    assert.ok(stdout.includes("name: 'GET'"));
+
+    delete process.env.OTEL_NODE_RESOURCE_DETECTORS;
+    delete process.env.OTEL_TRACES_EXPORTER;
+  });
+});

metapackages/auto-instrumentations-node/test/test-app/app.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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.
+ */
+
+//Used in register.test.ts to mimic a JS app.
+const http = require('http');
+
+const options = {
+  hostname: 'example.com',
+  port: 80,
+  path: '/',
+  method: 'GET'
+};
+
+const req = http.request(options);
+
+req.end();