Skip to content

Commit

Permalink
Merge branch 'next' into dluna/4175-replace-attrib-interfaces-sdk-tra…
Browse files Browse the repository at this point in the history
…ce-base
  • Loading branch information
david-luna authored Sep 24, 2024
2 parents 51f997b + 1804925 commit b834fa8
Show file tree
Hide file tree
Showing 144 changed files with 14,172 additions and 11,296 deletions.
13 changes: 9 additions & 4 deletions .github/workflows/unit-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,9 @@ jobs:
export NODE_OPTIONS=--openssl-legacy-provider
npm run test
- name: Report Coverage
run: npm run codecov
if: ${{ matrix.node_version == '18' }}
uses: codecov/codecov-action@v4
with:
verbose: true
node-windows-tests:
runs-on: windows-latest
env:
Expand Down Expand Up @@ -98,7 +99,9 @@ jobs:
- name: Unit tests
run: npm run test:browser
- name: Report Coverage
run: npm run codecov:browser
uses: codecov/codecov-action@v4
with:
verbose: true
webworker-tests:
runs-on: ubuntu-latest
env:
Expand All @@ -122,7 +125,9 @@ jobs:
- name: Unit tests
run: npm run test:webworker
- name: Report Coverage
run: npm run codecov:webworker
uses: codecov/codecov-action@v4
with:
verbose: true
api-eol-node-test:
strategy:
fail-fast: false
Expand Down
1 change: 1 addition & 0 deletions .nycrc
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
"extension": [
".ts"
],
"reporter": ["text", "json"],
"exclude": [
"**/*.d.ts",
"build/**/*.*",
Expand Down
18 changes: 16 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,21 @@ For semantic convention package changes, see the [semconv CHANGELOG](packages/se

### :rocket: (Enhancement)

* feat: add processors for adding session.id attribute to spans and logs [#4972](https://github.com/open-telemetry/opentelemetry-js/pull/4972)

### :bug: (Bug Fix)

### :books: (Refine Doc)

### :house: (Internal)

* deps: set `@opentelemetry/api` dependency min version to 1.3.0 in `examples`, `experimental/packages`, `integration-tests` and `selenium-tests`
[#4992](https://github.com/open-telemetry/opentelemetry-js/pull/4992)

## 1.26.0

### :rocket: (Enhancement)

* feat: include instrumentation scope info in console span and log record exporters [#4848](https://github.com/open-telemetry/opentelemetry-js/pull/4848) @blumamir
* feat(semconv): update semantic conventions to 1.27 (from 1.7.0) [#4690](https://github.com/open-telemetry/opentelemetry-js/pull/4690) @dyladan
* Exported names have changed to `ATTR_{name}` for attributes (e.g. `ATTR_HTTP_REQUEST_METHOD`), `{name}_VALUE_{value}` for enumeration values (e.g. `HTTP_REQUEST_METHOD_VALUE_POST`), and `METRIC_{name}` for metrics. Exported names from previous versions are deprecated.
Expand All @@ -28,8 +43,7 @@ For semantic convention package changes, see the [semconv CHANGELOG](packages/se
* fix(sdk-node): avoid spurious diag errors for unknown OTEL_NODE_RESOURCE_DETECTORS values [#4879](https://github.com/open-telemetry/opentelemetry-js/pull/4879) @trentm
* deps(opentelemetry-instrumentation): Bump `shimmer` types to 1.2.0 [#4865](https://github.com/open-telemetry/opentelemetry-js/pull/4865) @lforst
* fix(instrumentation): Fix optional property types [#4833](https://github.com/open-telemetry/opentelemetry-js/pull/4833) @alecmev

### :books: (Refine Doc)
* fix(sdk-metrics): fix(sdk-metrics): use inclusive upper bounds in histogram [#4829](https://github.com/open-telemetry/opentelemetry-js/pull/4829)

### :house: (Internal)

Expand Down
6 changes: 1 addition & 5 deletions api/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,6 @@
"repository": "open-telemetry/opentelemetry-js",
"scripts": {
"clean": "tsc --build --clean tsconfig.json tsconfig.esm.json tsconfig.esnext.json",
"codecov:browser": "nyc report --reporter=json && codecov -f coverage/*.json -p ../",
"codecov:webworker": "nyc report --reporter=json && codecov -f coverage/*.json -p ../",
"codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../",
"precompile": "cross-var lerna run version --scope $npm_package_name --include-dependencies",
"compile": "tsc --build tsconfig.json tsconfig.esm.json tsconfig.esnext.json",
"docs": "typedoc",
Expand Down Expand Up @@ -86,7 +83,6 @@
"@types/webpack": "5.28.5",
"@types/webpack-env": "1.16.3",
"babel-plugin-istanbul": "7.0.0",
"codecov": "3.8.3",
"cross-var": "1.1.0",
"dpdm": "3.13.1",
"karma": "6.4.4",
Expand All @@ -104,7 +100,7 @@
"ts-loader": "9.5.1",
"typescript": "4.4.4",
"unionfs": "4.5.4",
"webpack": "5.89.0"
"webpack": "5.94.0"
},
"homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/api",
"sideEffects": false
Expand Down
7 changes: 4 additions & 3 deletions api/test/tree-shaking/tree-shaking.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -88,9 +88,10 @@ describe('tree-shaking', () => {
const fs = new Union();
fs.use(mfs as any).use(realFs);

//direct webpack to use unionfs for file input
compiler.inputFileSystem = fs;
//direct webpack to output to memoryfs rather than to disk
// direct webpack to use unionfs for file input
// needs workaround from https://github.com/webpack/webpack/issues/18242#issuecomment-2018116985 since webpack 5.91.0
compiler.inputFileSystem = fs as any as typeof compiler.inputFileSystem;
// direct webpack to output to memoryfs rather than to disk
compiler.outputFileSystem = {
...mfs,
join: path.join,
Expand Down
131 changes: 131 additions & 0 deletions doc/esm-support.md
Original file line number Diff line number Diff line change
@@ -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` |
2 changes: 1 addition & 1 deletion examples/basic-tracer-node/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
"url": "https://github.com/open-telemetry/opentelemetry-js/issues"
},
"dependencies": {
"@opentelemetry/api": "^1.0.2",
"@opentelemetry/api": "^1.3.0",
"@opentelemetry/exporter-jaeger": "0.25.0",
"@opentelemetry/resources": "0.25.0",
"@opentelemetry/semantic-conventions": "^1.22.0",
Expand Down
16 changes: 8 additions & 8 deletions examples/esm-http-ts/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "esm-http-ts",
"private": true,
"version": "0.52.1",
"version": "0.53.0",
"description": "Example of HTTP integration with OpenTelemetry using ESM and TypeScript",
"main": "build/index.js",
"type": "module",
Expand Down Expand Up @@ -32,12 +32,12 @@
"homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/",
"dependencies": {
"@opentelemetry/api": "1.9.0",
"@opentelemetry/exporter-trace-otlp-proto": "0.52.1",
"@opentelemetry/instrumentation": "0.52.1",
"@opentelemetry/instrumentation-http": "0.52.1",
"@opentelemetry/resources": "1.25.1",
"@opentelemetry/sdk-trace-base": "1.25.1",
"@opentelemetry/sdk-trace-node": "1.25.1",
"@opentelemetry/semantic-conventions": "1.25.1"
"@opentelemetry/exporter-trace-otlp-proto": "0.53.0",
"@opentelemetry/instrumentation": "0.53.0",
"@opentelemetry/instrumentation-http": "0.53.0",
"@opentelemetry/resources": "1.26.0",
"@opentelemetry/sdk-trace-base": "1.26.0",
"@opentelemetry/sdk-trace-node": "1.26.0",
"@opentelemetry/semantic-conventions": "1.27.0"
}
}
2 changes: 1 addition & 1 deletion examples/grpc-js/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
},
"dependencies": {
"@grpc/grpc-js": "^1.3.7",
"@opentelemetry/api": "^1.0.2",
"@opentelemetry/api": "^1.3.0",
"@opentelemetry/exporter-jaeger": "^1.0.1",
"@opentelemetry/exporter-zipkin": "^1.0.1",
"@opentelemetry/instrumentation": "^0.27.0",
Expand Down
18 changes: 9 additions & 9 deletions examples/http/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "http-example",
"private": true,
"version": "0.52.1",
"version": "0.53.0",
"description": "Example of HTTP integration with OpenTelemetry",
"main": "index.js",
"scripts": {
Expand Down Expand Up @@ -30,14 +30,14 @@
},
"dependencies": {
"@opentelemetry/api": "^1.3.0",
"@opentelemetry/exporter-jaeger": "1.25.1",
"@opentelemetry/exporter-zipkin": "1.25.1",
"@opentelemetry/instrumentation": "0.52.1",
"@opentelemetry/instrumentation-http": "0.52.1",
"@opentelemetry/resources": "1.25.1",
"@opentelemetry/sdk-trace-base": "1.25.1",
"@opentelemetry/sdk-trace-node": "1.25.1",
"@opentelemetry/semantic-conventions": "1.25.1"
"@opentelemetry/exporter-jaeger": "1.26.0",
"@opentelemetry/exporter-zipkin": "1.26.0",
"@opentelemetry/instrumentation": "0.53.0",
"@opentelemetry/instrumentation-http": "0.53.0",
"@opentelemetry/resources": "1.26.0",
"@opentelemetry/sdk-trace-base": "1.26.0",
"@opentelemetry/sdk-trace-node": "1.26.0",
"@opentelemetry/semantic-conventions": "1.27.0"
},
"homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/http",
"devDependencies": {
Expand Down
20 changes: 10 additions & 10 deletions examples/https/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "https-example",
"private": true,
"version": "0.52.1",
"version": "0.53.0",
"description": "Example of HTTPs integration with OpenTelemetry",
"main": "build/src/index.js",
"types": "build/src/index.d.ts",
Expand Down Expand Up @@ -33,15 +33,15 @@
"url": "https://github.com/open-telemetry/opentelemetry-js/issues"
},
"dependencies": {
"@opentelemetry/api": "^1.0.0",
"@opentelemetry/exporter-jaeger": "1.25.1",
"@opentelemetry/exporter-zipkin": "1.25.1",
"@opentelemetry/instrumentation": "0.52.1",
"@opentelemetry/instrumentation-http": "0.52.1",
"@opentelemetry/resources": "1.25.1",
"@opentelemetry/sdk-trace-base": "1.25.1",
"@opentelemetry/sdk-trace-node": "1.25.1",
"@opentelemetry/semantic-conventions": "1.25.1"
"@opentelemetry/api": "^1.3.0",
"@opentelemetry/exporter-jaeger": "1.26.0",
"@opentelemetry/exporter-zipkin": "1.26.0",
"@opentelemetry/instrumentation": "0.53.0",
"@opentelemetry/instrumentation-http": "0.53.0",
"@opentelemetry/resources": "1.26.0",
"@opentelemetry/sdk-trace-base": "1.26.0",
"@opentelemetry/sdk-trace-node": "1.26.0",
"@opentelemetry/semantic-conventions": "1.27.0"
},
"homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/https",
"devDependencies": {
Expand Down
Loading

0 comments on commit b834fa8

Please sign in to comment.