diff --git a/content/en/docs/languages/js/getting-started/nodejs.md b/content/en/docs/languages/js/getting-started/nodejs.md index 4197b9118e0f..ebdd1a8787a1 100644 --- a/content/en/docs/languages/js/getting-started/nodejs.md +++ b/content/en/docs/languages/js/getting-started/nodejs.md @@ -24,6 +24,10 @@ Ensure that you have the following installed locally: - [TypeScript](https://www.typescriptlang.org/download), if you will be using TypeScript. +{{% alert title="Note" color="info" %}} +Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS. +{{% /alert %}} + ## Example Application The following example uses a basic [Express](https://expressjs.com/) @@ -247,6 +251,17 @@ Listening for requests on http://localhost:8080 {{% /tab %}} {{< /tabpane >}} +### Instrumentation for ECMAScript Modules + +If your application is written in JavaScript as ESM, or compiled to ESM from TypeScript, then a loader hook is required to properly patch instrumentation. +The custom hook for ESM instrumentation is `--experimental-loader=@opentelemetry/instrumentation/hook.mjs`. +This flag must be passed to the `node` binary, which is often done as a startup command and/or in the `NODE_OPTIONS` environment variable. + +```console +$ node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --require ./instrumentation.js app.js +Listening for requests on http://localhost:8080 +``` + Open in your web browser and reload the page a few times. After a while you should see the spans printed in the console by the `ConsoleSpanExporter`. diff --git a/content/en/docs/languages/js/instrumentation.md b/content/en/docs/languages/js/instrumentation.md index 3cd001056f1d..de461da14c4f 100644 --- a/content/en/docs/languages/js/instrumentation.md +++ b/content/en/docs/languages/js/instrumentation.md @@ -33,6 +33,10 @@ about manual instrumentation. You don't have to use the example app: if you want to instrument your own app or library, follow the instructions here to adapt the process to your own code. +{{% alert title="Note" color="info" %}} +Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS. +{{% /alert %}} + ### Dependencies {#example-app-dependencies} Create an empty NPM `package.json` file in a new directory: diff --git a/content/en/docs/languages/js/libraries.md b/content/en/docs/languages/js/libraries.md index 874c186e8525..8dd08598fd77 100644 --- a/content/en/docs/languages/js/libraries.md +++ b/content/en/docs/languages/js/libraries.md @@ -19,6 +19,11 @@ For example, will automatically create [spans](/docs/concepts/signals/traces/#spans) based on the inbound HTTP requests. +{{% alert title="Note" color="info" %}} +Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS. +If the application runs as ESM, add the loader hook as specified in [Getting Started](/docs/languages/js/getting-started/nodejs/#instrumentation-for-ecmascript-modules). +{{% /alert %}} + ### Setup Each instrumentation library is an NPM package. For example, here’s how you can diff --git a/content/en/docs/languages/js/propagation.md b/content/en/docs/languages/js/propagation.md index 98223415eecf..deaef6eb1dbe 100644 --- a/content/en/docs/languages/js/propagation.md +++ b/content/en/docs/languages/js/propagation.md @@ -7,6 +7,10 @@ cSpell:ignore: rolldice {{% docs/languages/propagation js %}} +{{% alert title="Note" color="info" %}} +Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS. +{{% /alert %}} + ## Automatic context propagation [Instrumentation libraries](../libraries/) like diff --git a/content/en/docs/languages/js/resources.md b/content/en/docs/languages/js/resources.md index f0dc34e02c6e..bc57325cd604 100644 --- a/content/en/docs/languages/js/resources.md +++ b/content/en/docs/languages/js/resources.md @@ -15,6 +15,10 @@ Node.js SDK. Follow the instructions in the [Getting Started - Node.js][], so that you have the files `package.json`, `app.js` and `tracing.js`. +{{% alert title="Note" color="info" %}} +Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS. +{{% /alert %}} + ## Process & Environment Resource Detection Out of the box, the Node.js SDK detects [process and process diff --git a/content/en/docs/languages/js/serverless.md b/content/en/docs/languages/js/serverless.md index c418b95e00c3..222af217db43 100644 --- a/content/en/docs/languages/js/serverless.md +++ b/content/en/docs/languages/js/serverless.md @@ -8,6 +8,10 @@ cSpell:ignore: otelwrapper This guide shows how to get started with tracing serverless functions using OpenTelemetry instrumentation libraries. +{{% alert title="Note" color="info" %}} +Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS. +{{% /alert %}} + ## AWS Lambda {{% alert title="Note" color="info" %}}