docs: Describe support for ESM (#4876)
Co-authored-by: Trent Mick <trentm@gmail.com>
This commit is contained in:
parent
2ca2459414
commit
966ac176af
|
@ -41,6 +41,9 @@ This is the JavaScript version of [OpenTelemetry](https://opentelemetry.io/), a
|
|||
|
||||
## Quick Start
|
||||
|
||||
**Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS.**
|
||||
For more details on ECMAScript Modules vs CommonJS, refer to [esm-support](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md).
|
||||
|
||||
The following describes how to set up tracing for a basic web application.
|
||||
For more detailed documentation, see the website at <https://opentelemetry.io/docs/instrumentation/js/>.
|
||||
|
||||
|
@ -110,7 +113,7 @@ If you are a library author looking to build OpenTelemetry into your library, pl
|
|||
## Supported Runtimes
|
||||
|
||||
| Platform Version | Supported |
|
||||
|---------------------|-----------------------------------------------|
|
||||
| ------------------- | --------------------------------------------- |
|
||||
| Node.JS `v22` | :heavy_check_mark: |
|
||||
| Node.JS `v20` | :heavy_check_mark: |
|
||||
| Node.JS `v18` | :heavy_check_mark: |
|
||||
|
@ -144,7 +147,7 @@ All stable packages are released with the same version, and all experimental pac
|
|||
The below table describes which versions of each set of packages are expected to work together.
|
||||
|
||||
| Stable Packages | Experimental Packages |
|
||||
|-----------------------------------------------------------------|-----------------------|
|
||||
| --------------- | --------------------- |
|
||||
| 1.21.x | 0.48.x |
|
||||
| 1.20.x | 0.47.x |
|
||||
| 1.19.x | 0.46.x |
|
||||
|
|
|
@ -0,0 +1,131 @@
|
|||
# ECMAScript Modules vs. CommonJS
|
||||
|
||||
Node.js uses a different module loader for ECMAScript Modules (ESM) vs. CommonJS (CJS).
|
||||
To verify whether your application is ESM or CJS, refer to [Node.js docs for Determining Module System](https://nodejs.org/api/packages.html#determining-module-system).
|
||||
|
||||
An `.mjs` extension or `type:module` in the built app's `package.json` indicates the app is ESM.
|
||||
|
||||
**Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CJS.**
|
||||
ESM support is ongoing; a few adjustments are needed for configuration and startup commands.
|
||||
|
||||
For more explanation about CJS and ESM, see the [Node.js docs](https://nodejs.org/api/modules.html#enabling).
|
||||
|
||||
## TypeScript
|
||||
|
||||
Many TypeScript projects today are written using ESM syntax, regardless of how they are compiled.
|
||||
In the `tsconfig.json`, there is an option to compile to ESM or CJS.
|
||||
If the compiled code is ESM, those import statements will remain the same (e.g. `import { foo } from 'bar';`).
|
||||
If the compiled code is CJS, those import statements will become `require()` statements (e.g. `const { foo } = require('bar');`)
|
||||
|
||||
## Initializing the SDK
|
||||
|
||||
Instrumentation setup and configuration must be run before your application code.
|
||||
If the SDK is initialized in a separate file (recommended), ensure it is imported first in application startup, or use the `--require` or `--import` flag during startup to preload the module.
|
||||
|
||||
For CJS, the `NODE_OPTIONS` for the startup command should include `--require ./telemetry.js`.
|
||||
|
||||
For ESM, minimum Node.js version of `18.19.0` is required.
|
||||
The `NODE_OPTIONS` for the startup command should include `--import ./telemetry.js`.
|
||||
|
||||
## Instrumentation Hook Required for ESM
|
||||
|
||||
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.
|
||||
|
||||
### Additional Notes on Experimental Loaders
|
||||
|
||||
Though the OpenTelemetry loader currently relies on `import-in-the-middle`, direct usage of `import-in-the-middle/hook.mjs` may cease to work in the future.
|
||||
The only currently supported loader hook is `@opentelemetry/instrumentation/hook.mjs`.
|
||||
|
||||
**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(...)`.
|
||||
Refer to this [issue](https://github.com/open-telemetry/opentelemetry-js/issues/4933) for details.
|
||||
|
||||
Because of ongoing issues with loaders running TypeScript code as ESM in development environments, results may vary.
|
||||
|
||||
To use `ts-node` to run the uncompiled TypeScript code, the module must be CJS.
|
||||
To use `tsx` to run the uncompiled TypeScript code as ESM, the `--import` flag must be used.
|
||||
|
||||
## Using the Zero Code Option with `auto-instrumentations-node`
|
||||
|
||||
The `auto-instrumentations-node` package contains a `register` entry-point that can be used with `--require` or `--import` to setup and start the SDK easily, without application code changes.
|
||||
For ESM, the package also requires the usage of the loader hook.
|
||||
|
||||
Startup command for CJS:
|
||||
|
||||
```sh
|
||||
node --require @opentelemetry/auto-instrumentations-node/register app.js
|
||||
```
|
||||
|
||||
Startup command for ESM:
|
||||
|
||||
```sh
|
||||
node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import @opentelemetry/auto-instrumentations-node/register app.js
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example Written in JavaScript as CJS
|
||||
|
||||
```javascript
|
||||
/*telemetry.cjs*/
|
||||
const { NodeSDK } = require('@opentelemetry/sdk-node');
|
||||
const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-node');
|
||||
const {
|
||||
getNodeAutoInstrumentations,
|
||||
} = require('@opentelemetry/auto-instrumentations-node');
|
||||
|
||||
const sdk = new NodeSDK({
|
||||
traceExporter: new ConsoleSpanExporter(),
|
||||
instrumentations: [getNodeAutoInstrumentations()],
|
||||
});
|
||||
|
||||
sdk.start();
|
||||
```
|
||||
|
||||
Startup command:
|
||||
|
||||
```sh
|
||||
node --require ./telemetry.cjs app.js
|
||||
```
|
||||
|
||||
### Example Written in JavaScript as ESM or TypeScript
|
||||
|
||||
```typescript
|
||||
/*telemetry.ts | telemetry.mjs*/
|
||||
import { NodeSDK } from '@opentelemetry/sdk-node';
|
||||
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
|
||||
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
|
||||
|
||||
const sdk = new NodeSDK({
|
||||
traceExporter: new ConsoleSpanExporter(),
|
||||
instrumentations: [getNodeAutoInstrumentations()],
|
||||
});
|
||||
|
||||
sdk.start();
|
||||
```
|
||||
|
||||
Startup command for compiled CJS:
|
||||
|
||||
```sh
|
||||
node --require ./telemetry.js app.js
|
||||
```
|
||||
|
||||
Startup command for compiled ESM:
|
||||
|
||||
```sh
|
||||
node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import ./telemetry.js app.js
|
||||
```
|
||||
|
||||
### ESM Options for Different Versions of Node.js
|
||||
|
||||
The entire startup command should include the following `NODE_OPTIONS`:
|
||||
|
||||
| Node.js Version | NODE_OPTIONS |
|
||||
| ----------------- | ----------------------------------------------------------------------------------------- |
|
||||
| 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.x | `--import ./telemetry.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
|
||||
| 22.x | `--import ./telemetry.mjs --experimental-loader=@opentelemetry/instrumentation/hook.mjs` |
|
|
@ -7,6 +7,9 @@
|
|||
|
||||
## Installation
|
||||
|
||||
**Note: Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS.**
|
||||
For more details on ECMAScript Modules vs CommonJS, refer to [esm-support](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md).
|
||||
|
||||
```bash
|
||||
npm install --save @opentelemetry/instrumentation
|
||||
```
|
||||
|
@ -108,7 +111,7 @@ export class MyInstrumentation extends InstrumentationBase {
|
|||
|
||||
// Later, but before the module to instrument is required
|
||||
|
||||
const myInstrumentationn = new MyInstrumentation();
|
||||
const myInstrumentation = new MyInstrumentation();
|
||||
myInstrumentation.setTracerProvider(provider); // this is optional, only if global TracerProvider shouldn't be used
|
||||
myInstrumentation.setMeterProvider(meterProvider); // this is optional
|
||||
myInstrumentation.enable();
|
||||
|
@ -219,12 +222,17 @@ If nothing is specified the global registered provider is used. Usually this is
|
|||
There might be use case where someone has the need for more providers within an application. Please note that special care must be takes in such setups
|
||||
to avoid leaking information from one provider to the other because there are a lot places where e.g. the global `ContextManager` or `Propagator` is used.
|
||||
|
||||
## Instrumentation for ES Modules In Node.js (experimental)
|
||||
## Instrumentation for ECMAScript Modules (ESM) in Node.js (experimental)
|
||||
|
||||
As the module loading mechanism for ESM is different than CJS, you need to select a custom loader so instrumentation can load hook on the ESM module it want to patch. To do so, you must provide the `--experimental-loader=@opentelemetry/instrumentation/hook.mjs` flag to the `node` binary. Alternatively you can set the `NODE_OPTIONS` environment variable to `NODE_OPTIONS="--experimental-loader=@opentelemetry/instrumentation/hook.mjs"`.
|
||||
As the ESM module loader from Node.js is experimental, so is our support for it. Feel free to provide feedback or report issues about it.
|
||||
Node.js uses a different module loader for ECMAScript Modules (ESM) vs. CommonJS (CJS).
|
||||
A `require()` call will cause Node.js to use the CommonJS module loader.
|
||||
An `import ...` statement or `import()` call will cause Node.js to use the ECMAScript module loader.
|
||||
|
||||
**Note**: ESM Instrumentation is not yet supported for Node 20.
|
||||
If your application is written in JavaScript as ESM, or it must compile 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.
|
||||
|
||||
For more details on ECMAScript Modules vs CommonJS, refer to [esm-support](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md).
|
||||
|
||||
## Limitations
|
||||
|
||||
|
|
|
@ -9,6 +9,9 @@ This package provides the full OpenTelemetry SDK for Node.js including tracing a
|
|||
|
||||
## Quick Start
|
||||
|
||||
**Note: Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS.**
|
||||
For more details on ECMAScript Modules vs CommonJS, refer to [esm-support](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md).
|
||||
|
||||
To get started you need to install `@opentelemetry/sdk-node`, a metrics and/or tracing exporter, and any appropriate instrumentation for the node modules used by your application.
|
||||
|
||||
### Installation
|
||||
|
@ -192,14 +195,14 @@ This is an alternative to programmatically configuring an exporter or span proce
|
|||
### Exporters
|
||||
|
||||
| Environment variable | Description |
|
||||
|----------------------|-------------|
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| OTEL_TRACES_EXPORTER | List of exporters to be used for tracing, separated by commas. Options include `otlp`, `jaeger`, `zipkin`, and `none`. Default is `otlp`. `none` means no autoconfigured exporter. |
|
||||
| OTEL_LOGS_EXPORTER | List of exporters to be used for logging, separated by commas. Options include `otlp`, `console` and `none`. Default is `otlp`. `none` means no autoconfigured exporter. |
|
||||
|
||||
### OTLP Exporter
|
||||
|
||||
| Environment variable | Description |
|
||||
|----------------------|-------------|
|
||||
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| OTEL_EXPORTER_OTLP_PROTOCOL | The transport protocol to use on OTLP trace, metric, and log requests. Options include `grpc`, `http/protobuf`, and `http/json`. Default is `http/protobuf`. |
|
||||
| OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | The transport protocol to use on OTLP trace requests. Options include `grpc`, `http/protobuf`, and `http/json`. Default is `http/protobuf`. |
|
||||
| OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | The transport protocol to use on OTLP metric requests. Options include `grpc`, `http/protobuf`, and `http/json`. Default is `http/protobuf`. |
|
||||
|
|
|
@ -8,6 +8,9 @@ This module provides *automated instrumentation and tracing* for Node.js applica
|
|||
For manual instrumentation see the
|
||||
[@opentelemetry/sdk-trace-base](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-base) package.
|
||||
|
||||
**Note: Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS.**
|
||||
For more details on ECMAScript Modules vs CommonJS, refer to [esm-support](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md).
|
||||
|
||||
## How auto instrumentation works
|
||||
|
||||
This package exposes a `NodeTracerProvider`.
|
||||
|
|
Loading…
Reference in New Issue