docs: Describe support for ESM

[JamieDanielson]

Which problem is this PR solving?

Updates #4845

Short description of the changes

• Adds dedicated doc with notes for ESM vs CJS, including
  • TypeScript setup
  • Supported table of Node.js versions and necessary NODE_OPTIONS
  • Details about experimental loader
  • Examples initializing SDK and adding instrumentation
• Adds references to the new doc in a few READMEs

I am thinking it makes sense to tidy up the content here, and once approved I can move some of the notes into the public docs for the website.

Type of change

Please delete options that are not relevant.

• This change requires a documentation update

How Has This Been Tested?

• Manual testing of example apps using various Node versions

relevant tsconfig compiler options

"target": "ESNext"
"module": "NodeNext"
"moduleResolution": "NodeNext"
"allowSyntheticDefaultImports": true
"esModuleInterop": true

package.json scripts

"scripts": {
  "start-sdk": "node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import ./build/telemetry.js ./build/app.js",
  "start-auto": "node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import @opentelemetry/auto-instrumentations-node/register ./build/app.js"
}

Checklist:

• Followed the style guidelines of this project
• Documentation has been updated

[trentm]

This is great. Thank you.
Some nits and suggestions below.

[trentm]

I wonder if this section could be replaced with a note something like:

**Note:** Eventually the recommendation for how to setup OpenTelemetry for usage with ESM will change to no longer require `--experimental-loader=@opentelemetry/instrumentation/hook.mjs`. Instead the bootstrap code (in "./telemetry.js") will use Node.js's newer `module.register(...)`. See https://github.com/open-telemetry/opentelemetry-js/issues/4933 for details.

If not, then at least we should correct this:

and will be replaced with something like --import=@opentelemetry/instrumentation/hook.mjs

We won't have users do that. Instead we'll have them use module.register(...) in their ./telemetry.mjs bootstrap file and then no longer need to have a separate --experimental-loader argument.

[JamieDanielson]

I used your verbiage. When we're ready to make the new recommendation we can update separately.

[trentm]

Suggested change

	| >=16.0.0 | `--require ./telemetry.cjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| >=18.1.0 <18.19.0 | `--require ./telemetry.cjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| >=18.19.0 | `--import ./telemetry.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| 20.x | `--import ./telemetry.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| 22.x | `--import ./telemetry.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| 16.x | `--require ./telemetry.cjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| >=18.1.0 <18.19.0 | `--require ./telemetry.cjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| ^18.19.0 | `--import ./telemetry.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| ^20.6.0 | `--import ./telemetry.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
	| 22.x | `--import ./telemetry.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |

I suppose I left out the >=20.0.0 <20.6.0 case.

[JamieDanielson]

Is the ^20.6.0 case a known cutoff or just not something you have tried? I just tested v20.0.0 and 20.3.0 and 20.9.0 and they all seem to work with this start command.

[trentm]

Ah, my bad. ^20.6.0 is needed for module.register(...). https://nodejs.org/en/blog/release/v20.6.0#new-nodemodule-api-register-for-module-customization-hooks-new-initialize-hook

But we're not talking about module.register() here yet.
I think we do want to limit our supported Node.js versions for ESM support to ^20.6.0 if we do add a statement about supported node.js versions -- on the expectation that we'll be moving official recommendation to module.register(...) usage.

[trentm]

Side note: It is also fine to use --require here, even for ESM support.
I don't think we need to mention that here, however.

[trentm]

The table cleanup is cool. This makes me realize this section is way out of date and a maintenance pain.

The "semconv" package is now a new category for the "OpenTelemetry is released as a set of distinct packages in 3 categories:" sentence at the start of this section.

Anyway... not for this PR.

[JamieDanielson]

Oh actually I didn't mean to reformat anything in this doc. It must have auto-formatted when I added the first section and saved.

[pichlermarc]

Thanks for working on this 👍