Skip to content

Commit 32b8402

Browse files
aryamohananaryamohanan
committed
chore: improved the comments
1 parent 44f10d3 commit 32b8402

File tree

9 files changed

+76
-77
lines changed

9 files changed

+76
-77
lines changed

‎CONTRIBUTING.md

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -322,12 +322,19 @@ REGIONS=<region> SKIP_DOCKER_IMAGE=true BUILD_LAYER_WITH=local LAYER_NAME=experi
322322
```
323323
## ESM Support
324324

325+
We have added the ESM support for all Node.js versions, Since version 18.19, [ESM loaders are off-thread](https://github.com/nodejs/node/pull/44710), loaded separately, a shift from previous setups where the Instana collector was loaded within the loader, leading to a disruption in existing implementation. To resolve this, we've replaced the deprecated `--experimental-loader` with `--import`, facilitating the loading of the collector in the main thread. However, note that `--import` is only compatible with Node.js v18.19 and later, necessitating the maintenance of both styles for different Node.js versions.
326+
327+
Efforts are ongoing to integrate native ESM support, detailed in ref 117183.
328+
325329
Use the following command to enable experimental ESM support:
326330

327331
- For Node.js versions greater than or equal to 18.19:
328332

329-
node --import /path/to/instana/node_modules/@instana/collector/register.mjs entry-point
330-
333+
```sh
334+
node --import /path/to/instana/node_modules/@instana/collector/register.mjs entry-point
335+
```
331336
- For Node.js versions less than 18.19:
332337

333-
node --experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs entry-point
338+
```sh
339+
node --experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs entry-point
340+
```

‎packages/aws-fargate/esm-loader.mjs

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,12 @@
55
'use strict';
66

77
/**
8-
* We currently only instrument CJS modules. As soon as we want
9-
* to instrument ES modules (such as `got` v12), the requireHook will
10-
* no longer work. Therefor we would need to wrap the target ES module
11-
* with our instrumentations using the resolve & load hook.
8+
* IMPORTANT NOTE: From Node.js version 18.19 and above, the ESM loaders operate off-thread.
9+
* Consequently, ESM instrumentation using '--experimental-loader' becomes obsolete.
10+
* Instead, we recommend using '--import' for loading instrumentation and relocating the
11+
* Instana collector loading to './register' file.
12+
* Please note that '--import' flag is unavailable in earlier versions, hence we maintain both setups.
13+
* We will incorporate the native ESM support by using 'import-in-the-middle'.
1214
*
1315
* Usage:
1416
* ENV NODE_OPTIONS='--experimental-loader=/instana/node_modules/
@@ -22,12 +24,3 @@
2224
*/
2325

2426
import './src/index.js';
25-
/*
26-
export async function resolve(specifier, context, nextResolve) {
27-
return nextResolve(specifier, context, nextResolve);
28-
}
29-
30-
export async function load(url, context, nextLoad) {
31-
return nextLoad(url, context, nextLoad);
32-
}
33-
*/

‎packages/aws-fargate/register.mjs

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,22 @@
33
*/
44

55
/**
6-
* ESM hooks supplied via loaders (--experimental-loader=@instana/collector/esm-loader.mjs) run in a dedicated thread from v20 and above,
7-
* isolated from the main thread. Reference: https://github.com/nodejs/node/pull/44710
8-
* We loaded the tracer in the main thread with --import, we can extend the ESM hook with register method
9-
* in the future to extend the ESM support.
6+
* As of Node.js version 18.19 and above, ESM loaders (--experimental-loader)
7+
* are executed in a dedicated thread, separate from the main thread.
8+
* see https://github.com/nodejs/node/pull/44710.
9+
* Previously, loading the Instana collector within the loader and after the update ESM support
10+
* no longer working with v18.19 and above. To address this, we've opted to load the Instana
11+
* collector in the main thread using --import.
12+
* Additionally, we aim to incorporate native ESM
13+
* support by utilizing the node register method, enabling customization of the ESM loader
14+
* with 'import-in-the-middle'.
1015
*
1116
* Usage:
1217
* ENV NODE_OPTIONS='--import /instana/node_modules/@instana/aws-fargate/register.mjs
1318
*/
14-
19+
// We plan to utilize this for adding native ESM support in the near future
1520
// import { register } from 'node:module';
1621
// register(./loader.mjs, import.meta.url);
1722

18-
// Importing the Instana trace initialization module here, as this is the main thread.
23+
// Importing the Instana trace initialization module here, as this is executed in the main thread.
1924
import './src/index.js';

‎packages/azure-container-services/esm-loader.mjs

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,12 @@
55
'use strict';
66

77
/**
8-
* We currently only instrument CJS modules. As soon as we want
9-
* to instrument ES modules (such as `got` v12), the requireHook will
10-
* no longer work. Therefor we would need to wrap the target ES module
11-
* with our instrumentations using the resolve & load hook.
8+
* IMPORTANT NOTE: From Node.js version 18.19 and above, the ESM loaders operate off-thread.
9+
* Consequently, ESM instrumentation using '--experimental-loader' becomes obsolete.
10+
* Instead, we recommend using '--import' for loading instrumentation and relocating the
11+
* Instana collector loading to './register' file.
12+
* Please note that '--import' flag is unavailable in earlier versions, hence we maintain both setups.
13+
* We will incorporate the native ESM support by using 'import-in-the-middle'.
1214
*
1315
* Usage:
1416
* ENV NODE_OPTIONS='--experimental-loader=/instana/node_modules/
@@ -22,12 +24,4 @@
2224
*/
2325

2426
import './src/index.js';
25-
/*
26-
export async function resolve(specifier, context, nextResolve) {
27-
return nextResolve(specifier, context, nextResolve);
28-
}
2927

30-
export async function load(url, context, nextLoad) {
31-
return nextLoad(url, context, nextLoad);
32-
}
33-
*/

‎packages/azure-container-services/register.mjs

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,22 @@
33
*/
44

55
/**
6-
* ESM hooks supplied via loaders (--experimental-loader=@instana/collector/esm-loader.mjs) run in a dedicated thread from v20 and above,
7-
* isolated from the main thread. Reference: https://github.com/nodejs/node/pull/44710
8-
* We loaded the tracer in the main thread with --import, we can extend the ESM hook with register method
9-
* in the future to extend the ESM support.
6+
* As of Node.js version 18.19 and above, ESM loaders (--experimental-loader)
7+
* are executed in a dedicated thread, separate from the main thread.
8+
* see https://github.com/nodejs/node/pull/44710.
9+
* Previously, loading the Instana collector within the loader and after the update ESM support
10+
* no longer working with v18.19 and above. To address this, we've opted to load the Instana
11+
* collector in the main thread using --import. Additionally, we aim to incorporate native ESM
12+
* support by utilizing the node register method, enabling customization of the ESM loader
13+
* with 'import-in-the-middle'.
1014
*
1115
* Usage:
1216
* ENV NODE_OPTIONS='--import /instana/node_modules/@instana/azure-container-services/register.mjs server.js
1317
*/
1418

19+
// We plan to utilize this for adding native ESM support in the near future
1520
// import { register } from 'node:module';
1621
// register(./loader.mjs, import.meta.url);
1722

18-
// Importing the Instana trace initialization module here, as this is the main thread.
23+
// Importing the Instana trace initialization module here, as this is executed in the main thread.
1924
import './src/index.js';

‎packages/collector/esm-loader.mjs

Lines changed: 6 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,12 @@
55
'use strict';
66

77
/**
8-
* We currently only instrument CJS modules. As soon as we want
9-
* to instrument ES modules (such as `got` v12), the requireHook will
10-
* no longer work. Therefor we would need to wrap the target ES module
11-
* with our instrumentations using the resolve & load hook.
8+
* IMPORTANT NOTE: From Node.js version 18.19 and above, the ESM loaders operate off-thread.
9+
* Consequently, ESM instrumentation using '--experimental-loader' becomes obsolete.
10+
* Instead, we recommend using '--import' for loading instrumentation and relocating the
11+
* Instana collector loading to './register' file.
12+
* Please note that '--import' flag is unavailable in earlier versions, hence we maintain both setups.
13+
* We will incorporate the native ESM support by using 'import-in-the-middle'.
1214
*
1315
* Usage:
1416
* node --experimental-loader=@instana/collector/esm-loader.mjs server.js
@@ -19,13 +21,3 @@
1921

2022
import instana from './src/index.js';
2123
instana();
22-
23-
/*
24-
export async function resolve(specifier, context, nextResolve) {
25-
return nextResolve(specifier, context, nextResolve);
26-
}
27-
28-
export async function load(url, context, nextLoad) {
29-
return nextLoad(url, context, nextLoad);
30-
}
31-
*/

‎packages/collector/register.mjs

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,22 @@
33
*/
44

55
/**
6-
* ESM hooks supplied via loaders (--experimental-loader=@instana/collector/esm-loader.mjs) run in a dedicated thread from v20 and above,
7-
* isolated from the main thread. Reference: https://github.com/nodejs/node/pull/44710
8-
* We loaded the tracer in the main thread with --import, we can extend the ESM hook with register method
9-
* in the future to extend the ESM support.
6+
* As of Node.js version 18.19 and above, ESM loaders (--experimental-loader)
7+
* are executed in a dedicated thread, separate from the main thread.
8+
* see https://github.com/nodejs/node/pull/44710.
9+
* Previously, loading the Instana collector within the loader and after the update ESM support
10+
* no longer working with v18.19 and above. To address this, we've opted to load the Instana
11+
* collector in the main thread using --import. Additionally, we aim to incorporate native ESM
12+
* support by utilizing the node register method, enabling customization of the ESM loader
13+
* with 'import-in-the-middle'.
1014
*
1115
* Usage:
1216
* node --import @instana/collector/register.mjs server.js
1317
*/
14-
18+
// We plan to utilize this for adding native ESM support in the near future
1519
// import { register } from 'node:module';
1620
// register(./loader.mjs, import.meta.url);
1721

18-
// Importing the Instana trace initialization module here, as this is the main thread.
22+
// Importing the Instana trace initialization module here, as this is executed in the main thread.
1923
import instana from './src/index.js';
2024
instana();

‎packages/google-cloud-run/esm-loader.mjs

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,12 @@
55
'use strict';
66

77
/**
8-
* We currently only instrument CJS modules. As soon as we want
9-
* to instrument ES modules (such as `got` v12), the requireHook will
10-
* no longer work. Therefor we would need to wrap the target ES module
11-
* with our instrumentations using the resolve & load hook.
8+
* IMPORTANT NOTE: From Node.js version 18.19 and above, the ESM loaders operate off-thread.
9+
* Consequently, ESM instrumentation using '--experimental-loader' becomes obsolete.
10+
* Instead, we recommend using '--import' for loading instrumentation and relocating the
11+
* Instana collector loading to './register' file.
12+
* Please note that '--import' flag is unavailable in earlier versions, hence we maintain both setups.
13+
* We will incorporate the native ESM support by using 'import-in-the-middle'.
1214
*
1315
* Usage:
1416
* ENV NODE_OPTIONS='--experimental-loader=/instana/node_modules/
@@ -21,12 +23,4 @@
2123
* can be invoked from this context.
2224
*/
2325

24-
import './src/index.js';
25-
/*
26-
export async function resolve(specifier, context, nextResolve) {
27-
return nextResolve(specifier, context, nextResolve);
28-
}
29-
export async function load(url, context, nextLoad) {
30-
return nextLoad(url, context, nextLoad);
31-
}
32-
*/
26+
import './src/index.js';

‎packages/google-cloud-run/register.mjs

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,22 @@
33
*/
44

55
/**
6-
* ESM hooks supplied via loaders (--experimental-loader=@instana/collector/esm-loader.mjs) run in a dedicated thread from v20 and above,
7-
* isolated from the main thread. Reference: https://github.com/nodejs/node/pull/44710
8-
* We loaded the tracer in the main thread with --import, we can extend the ESM hook with register method
9-
* in the future to extend the ESM support.
6+
* As of Node.js version 18.19 and above, ESM loaders (--experimental-loader)
7+
* are executed in a dedicated thread, separate from the main thread.
8+
* see https://github.com/nodejs/node/pull/44710.
9+
* Previously, loading the Instana collector within the loader and after the update ESM support
10+
* no longer working with v18.19 and above. To address this, we've opted to load the Instana
11+
* collector in the main thread using --import. Additionally, we aim to incorporate native ESM
12+
* support by utilizing the node register method, enabling customization of the ESM loader
13+
* with 'import-in-the-middle'.
1014
*
1115
* Usage:
1216
* ENV NODE_OPTIONS='--import /instana/node_modules/@instana/google-cloud-run/register.mjs
1317
*/
1418

19+
// We plan to utilize this for adding native ESM support in the near future
1520
// import { register } from 'node:module';
1621
// register(./loader.mjs, import.meta.url);
1722

18-
// Importing the Instana trace initialization module here, as this is the main thread.
23+
// Importing the Instana trace initialization module here, as this is executed in the main thread.
1924
import './src/index.js';

0 commit comments

Comments
 (0)