diff --git a/examples/express-mysql/package.json b/examples/express-mysql/package.json index 5754a6e0..ce60922a 100644 --- a/examples/express-mysql/package.json +++ b/examples/express-mysql/package.json @@ -5,7 +5,7 @@ "start": "node --import solarwinds-apm index.js" }, "dependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "express": "^4.21.1", "mysql2": "^3.11.3", "solarwinds-apm": "workspace:^", diff --git a/examples/fastify-postgres/package.json b/examples/fastify-postgres/package.json index 47a484a1..e44231c8 100644 --- a/examples/fastify-postgres/package.json +++ b/examples/fastify-postgres/package.json @@ -7,7 +7,7 @@ }, "dependencies": { "@fastify/postgres": "^6.0.1", - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "fastify": "^5.0.0", "pg": "^8.13.0", "pino": "^9.5.0", diff --git a/examples/hello-distributed/package.json b/examples/hello-distributed/package.json index c01f3f42..19fcd89e 100644 --- a/examples/hello-distributed/package.json +++ b/examples/hello-distributed/package.json @@ -6,7 +6,7 @@ "start": "concurrently \"node --import solarwinds-apm external.js\" \"node --import solarwinds-apm internal.js\"" }, "dependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "solarwinds-apm": "workspace:^" }, "devDependencies": { diff --git a/examples/hello-manual/package.json b/examples/hello-manual/package.json index 046f2ca6..302f9055 100644 --- a/examples/hello-manual/package.json +++ b/examples/hello-manual/package.json @@ -6,7 +6,7 @@ "start": "node --import solarwinds-apm index.js" }, "dependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "solarwinds-apm": "workspace:^" } } diff --git a/examples/hello/package.json b/examples/hello/package.json index fa9d5d39..9aa66214 100644 --- a/examples/hello/package.json +++ b/examples/hello/package.json @@ -6,7 +6,7 @@ "start": "node --import solarwinds-apm index.js" }, "dependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "solarwinds-apm": "workspace:^" } } diff --git a/examples/next-prisma/package.json b/examples/next-prisma/package.json index 2a2601bd..0b13feac 100644 --- a/examples/next-prisma/package.json +++ b/examples/next-prisma/package.json @@ -7,7 +7,7 @@ "start": "prisma generate && prisma migrate deploy && next start" }, "dependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "@prisma/client": "^6.0.1", "@prisma/instrumentation": "^5.21.1", "next": "^14.2.15", diff --git a/packages/compat/package.json b/packages/compat/package.json index 2c41b74c..691b3903 100644 --- a/packages/compat/package.json +++ b/packages/compat/package.json @@ -34,7 +34,7 @@ "test": "swtest -p test/tsconfig.json -c src" }, "peerDependencies": { - "@opentelemetry/api": "^1.3.0" + "@opentelemetry/api": "^1.9.0" }, "peerDependenciesMeta": { "@opentelemetry/api": { @@ -42,7 +42,7 @@ } }, "devDependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "@opentelemetry/semantic-conventions": "~1.28.0", "@solarwinds-apm/eslint-config": "workspace:^", "@solarwinds-apm/test": "workspace:^", diff --git a/packages/histogram/package.json b/packages/histogram/package.json index 56e1be4a..b6cc2f98 100644 --- a/packages/histogram/package.json +++ b/packages/histogram/package.json @@ -35,7 +35,7 @@ "scan": "node ../../scripts/scan.js" }, "devDependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "@opentelemetry/sdk-metrics": "~1.28.0", "@solarwinds-apm/eslint-config": "workspace:^", "@types/node": "^18.19.0", diff --git a/packages/instrumentations/package.json b/packages/instrumentations/package.json index fdd396c2..f5d3082d 100644 --- a/packages/instrumentations/package.json +++ b/packages/instrumentations/package.json @@ -85,7 +85,7 @@ "@solarwinds-apm/module": "workspace:^" }, "peerDependencies": { - "@opentelemetry/api": "^1.3.0" + "@opentelemetry/api": "^1.9.0" }, "peerDependenciesMeta": { "@opentelemetry/api": { @@ -93,7 +93,7 @@ } }, "devDependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "@solarwinds-apm/eslint-config": "workspace:^", "@solarwinds-apm/test": "workspace:^", "@types/semver": "^7.5.8", diff --git a/packages/sampling/package.json b/packages/sampling/package.json index ad512aa6..04fd2b59 100644 --- a/packages/sampling/package.json +++ b/packages/sampling/package.json @@ -39,7 +39,7 @@ "@opentelemetry/sdk-trace-base": "~1.28.0" }, "peerDependencies": { - "@opentelemetry/api": "^1.3.0" + "@opentelemetry/api": "^1.9.0" }, "peerDependenciesMeta": { "@opentelemetry/api": { @@ -47,7 +47,7 @@ } }, "devDependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "@opentelemetry/sdk-metrics": "~1.28.0", "@solarwinds-apm/eslint-config": "workspace:^", "@solarwinds-apm/test": "workspace:^", diff --git a/packages/solarwinds-apm/CHANGELOG.md b/packages/solarwinds-apm/CHANGELOG.md index 8dede092..97fc65e4 100644 --- a/packages/solarwinds-apm/CHANGELOG.md +++ b/packages/solarwinds-apm/CHANGELOG.md @@ -1,15 +1,51 @@ +# [15.0.0](https://github.com/solarwinds/apm-js/releases/tag/v15.0.0) + +## Breaking changes + +- `@opentelemetry/api` dependency upgraded to `^1.9.0`. +- Removed support for initialisation via `--require` and `--loader` flags. The only supported initialisation method is now `--import`. +- Removed support for Node.js 16. The supported versions are now 18 (`^18.19.0`), 20 (`^20.8.0`), 22 and future LTS releases. +- `waitUntilReady` changed to return a promise. + +## New features and improvements + +- Added support for exporting logs. +- Added support for non-Linux platforms (Windows, macOS, etc). + +## Internal changes + +- Upgraded liboboe to `15.0.2`. +- Use OTLP as default export protocol. + +# [14.1.0](https://github.com/solarwinds/apm-js/releases/tag/v14.1.0) + +## New features and improvements + +- Support ESM handlers in AWS Lambda. + +## Fixes + +- Do not insert invalid trace context in prepared PostgreSQL statements. +- Properly handle custom gauge metrics. + +# [14.0.4](https://github.com/solarwinds/apm-js/releases/tag/v14.0.3) + +## Fixes + +- Update `import-in-the-middle` transitive dependency to fix ESM loader issues. + # [14.0.3](https://github.com/solarwinds/apm-js/releases/tag/v14.0.3) ## Fixes - Properly support user-provided `@opentelemetry/api` in Lambda. -# [14.0.2](https://github.com/solarwinds/apm-js/releases/tag/v14.0.2) +# [14.0.0](https://github.com/solarwinds/apm-js/releases/tag/v14.0.0) ## Breaking changes - This is a completely new version of the instrumentation library built upon OpenTelemetry. -- The library now requires the `@opentelemetry/api` package to be installed alongside it, with the version range `^1.3.0`. +- The library now requires the `@opentelemetry/api` package to be installed alongside it, with the version range `^1.9.0`. - The public API surface of the library has been greatly reduced. The `@opentelemetry/api` package can instead be used for all custom instrumentation needs. - The configuration file name has changed and some options have been renamed or altered. Check out [the configuration guide](./CONFIGURATION.md) for more details. - The list of instrumented libraries has changed as the library now uses OpenTelemetry instrumentation. Custom instrumentations can now also be provided by the user. See [the updated list of bundled instrumentations](../instrumentations/COMPATIBILITY.md) for more details. diff --git a/packages/solarwinds-apm/CONFIGURATION.md b/packages/solarwinds-apm/CONFIGURATION.md index fedd4ae3..f21f06f0 100644 --- a/packages/solarwinds-apm/CONFIGURATION.md +++ b/packages/solarwinds-apm/CONFIGURATION.md @@ -9,7 +9,7 @@ All configuration options are optional except for the service key which is alway When required, the package will look for the file in the current working directory under three possible formats, in the following order: - `solarwinds.apm.config.ts` - TypeScript config, supports all options, requires a TypeScript loader such as `ts-node` or `tsx` -- `solarwinds.apm.config.js` - JavaScript config, supports all options, `.cjs` extension also accepted +- `solarwinds.apm.config.js` - JavaScript config, supports all options, `.cjs` and `.mjs` extensions also accepted - `solarwinds.apm.config.json` - JSON config, doesn't support option settings such as functions or custom classes since only valid JSON syntax is accepted It's also possible to use a custom name for the configuration file using the `SW_APM_CONFIG_FILE` environment variable. The file must have one of the three supported extensions or it will be ignored. diff --git a/packages/solarwinds-apm/README.md b/packages/solarwinds-apm/README.md index 5e771c6a..1c54a086 100644 --- a/packages/solarwinds-apm/README.md +++ b/packages/solarwinds-apm/README.md @@ -1,35 +1,33 @@ # solarwinds-apm -The new OpenTelemetry-based SolarWinds APM Node.js library. Currently supports Node.js 16 LTS, 18 LTS and 20. +The new OpenTelemetry-based SolarWinds APM Node.js library. Currently supports Node.js `^18.19.0`, `^20.8.0` and `22` or any later LTS release. This library automatically instruments a wide set of frameworks and libraries, see the [Module Compatibility table](../instrumentations/COMPATIBILITY.md) for details. ## Installation and Setup ```sh -npm install --save "solarwinds-apm" "@opentelemetry/api@^1.3.0" +npm install --save "solarwinds-apm" "@opentelemetry/api@^1.9.0" ``` Install using your package manager then follow the [configuration guide](./CONFIGURATION.md). Make sure to install the matching version of `@opentelmetry/api` as it is required for the library to work. The two packages should be updated at the same time and kept in sync. -The library can then be initialised either from the command line or the environment. Depending on the Node version the `--loader solarwinds-apm/loader` (<`18.19.0` | <`20.6.0`) or `--import solarwinds-apm` (>=`18.19.0` | >=`20.6.0`) flag should be used. +The library can then be initialised either from the command line or the environment. ```sh -# <18.19.0 | <20.6.0 -node --loader solarwinds-apm/loader script.js -# >=18.19.0 | >=20.6.0 node --import solarwinds-apm script.js ``` ```sh -# <18.19.0 | <20.6.0 -export NODE_OPTIONS="--loader solarwinds-apm/loader" -# >=18.19.0 | >=20.6.0 export NODE_OPTIONS="--import solarwinds-apm" npm start ``` +## Legacy mode + +With the 15.0.0 release, major parts of the library were rewritten in pure JavaScript to replace the previously used native library. The new codebase makes it possible to run the library on platforms other than Linux, however it is not compatible with AppOptics and some niche features might be unimplemented. The legacy code can be turned back on manually by setting the `SW_APM_LEGACY` environment variable to `true`. + ## Custom Instrumentation and Metrics Unlike previous non-OpenTelemetry version, all manual instrumentation and metrics collection are handled through the OpenTelemetry API using the `@opentelemetry/api` packages. The [OpenTelemetry JS documentation](https://opentelemetry.io/docs/instrumentation/js/manual/) for manual instrumentation provides instructions (note that `solarwinds-apm` takes care of the initial registration of all components), and the [SDK docs](https://open-telemetry.github.io/opentelemetry-js/modules/_opentelemetry_api.html) are available to see all that the API provides. @@ -46,7 +44,7 @@ import { waitUntilReady } from "solarwinds-apm" const { waitUntilReady } = require("solarwinds-apm") // wait up to 10 seconds -waitUntilReady(10_000) +await waitUntilReady(10_000) ``` ## Custom Transaction Names @@ -63,9 +61,13 @@ function calledFromWithinTransaction() { } ``` +## Migrating from 14.x.x + +Any use of the `--require solarwinds-apm` or `--loader solarwinds-apm/loader` flags must be replaced by `--import solarwinds-apm`. The `waitUntilReady` function now returns a promise instead of blocking, which might require code which uses it to be refactored. + ## Migrating from legacy versions -When migrating from older versions not built on top of OTel, `@opentelemetry/api@^1.3.0` must be added as an extra dependency. The config file will also need to be renamed and updated as some of the fields have changed, see the [configuration guide](./CONFIGURATION.md) for details. Manual instrumentation and metrics will also need to be migrated to use the OTel API, except for the `instrument` and `pInstrument` methods which are provided by the `@solarwinds-apm/compat` package to facilitate migrating. +When migrating from older versions not built on top of OTel, `@opentelemetry/api@^1.9.0` must be added as an extra dependency. The config file will also need to be renamed and updated as some of the fields have changed, see the [configuration guide](./CONFIGURATION.md) for details. Manual instrumentation and metrics will also need to be migrated to use the OTel API, except for the `instrument` and `pInstrument` methods which are provided by the `@solarwinds-apm/compat` package to facilitate migrating. ```diff - const { instrument, pInstrument } = require("solarwinds-apm") diff --git a/packages/solarwinds-apm/package.json b/packages/solarwinds-apm/package.json index 08697f27..14b87460 100644 --- a/packages/solarwinds-apm/package.json +++ b/packages/solarwinds-apm/package.json @@ -82,7 +82,7 @@ "zod": "^3.23.8" }, "peerDependencies": { - "@opentelemetry/api": "^1.3.0" + "@opentelemetry/api": "^1.9.0" }, "peerDependenciesMeta": { "@opentelemetry/api": { @@ -90,7 +90,7 @@ } }, "devDependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "@solarwinds-apm/eslint-config": "workspace:^", "@solarwinds-apm/test": "workspace:^", "@types/json-stringify-safe": "^5.0.3", diff --git a/packages/test/package.json b/packages/test/package.json index 0f14e667..8b9bbbb7 100644 --- a/packages/test/package.json +++ b/packages/test/package.json @@ -56,7 +56,7 @@ "ts-node": "^11.0.0-beta.1" }, "devDependencies": { - "@opentelemetry/api": "^1.3.0", + "@opentelemetry/api": "^1.9.0", "@opentelemetry/sdk-metrics": "~1.28.0", "@opentelemetry/sdk-trace-base": "~1.28.0", "@opentelemetry/sdk-trace-node": "~1.28.0", diff --git a/yarn.lock b/yarn.lock index 07b8727d..345c7396 100644 --- a/yarn.lock +++ b/yarn.lock @@ -526,7 +526,7 @@ __metadata: languageName: node linkType: hard -"@opentelemetry/api@npm:^1.0.0, @opentelemetry/api@npm:^1.3.0, @opentelemetry/api@npm:^1.8": +"@opentelemetry/api@npm:^1.0.0, @opentelemetry/api@npm:^1.3.0, @opentelemetry/api@npm:^1.8, @opentelemetry/api@npm:^1.9.0": version: 1.9.0 resolution: "@opentelemetry/api@npm:1.9.0" checksum: 10c0/9aae2fe6e8a3a3eeb6c1fdef78e1939cf05a0f37f8a4fae4d6bf2e09eb1e06f966ece85805626e01ba5fab48072b94f19b835449e58b6d26720ee19a58298add @@ -1565,7 +1565,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/compat@workspace:packages/compat" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" "@opentelemetry/semantic-conventions": "npm:~1.28.0" "@solarwinds-apm/eslint-config": "workspace:^" "@solarwinds-apm/test": "workspace:^" @@ -1574,7 +1574,7 @@ __metadata: prettier: "npm:^3.3.3" typescript: "npm:~5.7.2" peerDependencies: - "@opentelemetry/api": ^1.3.0 + "@opentelemetry/api": ^1.9.0 peerDependenciesMeta: "@opentelemetry/api": optional: false @@ -1625,7 +1625,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/example-express-mysql@workspace:examples/express-mysql" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" express: "npm:^4.21.1" mysql2: "npm:^3.11.3" solarwinds-apm: "workspace:^" @@ -1638,7 +1638,7 @@ __metadata: resolution: "@solarwinds-apm/example-fastify-postgres@workspace:examples/fastify-postgres" dependencies: "@fastify/postgres": "npm:^6.0.1" - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" fastify: "npm:^5.0.0" pg: "npm:^8.13.0" pino: "npm:^9.5.0" @@ -1650,7 +1650,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/example-hello-distributed@workspace:examples/hello-distributed" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" concurrently: "npm:^9.0.1" solarwinds-apm: "workspace:^" languageName: unknown @@ -1660,7 +1660,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/example-hello-manual@workspace:examples/hello-manual" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" solarwinds-apm: "workspace:^" languageName: unknown linkType: soft @@ -1669,7 +1669,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/example-hello@workspace:examples/hello" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" solarwinds-apm: "workspace:^" languageName: unknown linkType: soft @@ -1678,7 +1678,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/example-next-prisma@workspace:examples/next-prisma" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" "@prisma/client": "npm:^6.0.1" "@prisma/instrumentation": "npm:^5.21.1" "@types/node": "npm:^18.19.0" @@ -1709,7 +1709,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/histogram@workspace:packages/histogram" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" "@opentelemetry/sdk-metrics": "npm:~1.28.0" "@solarwinds-apm/eslint-config": "workspace:^" "@types/node": "npm:^18.19.0" @@ -1723,7 +1723,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/instrumentations@workspace:packages/instrumentations" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" "@opentelemetry/core": "npm:~1.28.0" "@opentelemetry/instrumentation": "npm:~0.55.0" "@opentelemetry/instrumentation-amqplib": "npm:^0.44.0" @@ -1779,7 +1779,7 @@ __metadata: semver: "npm:^7.6.3" typescript: "npm:~5.7.2" peerDependencies: - "@opentelemetry/api": ^1.3.0 + "@opentelemetry/api": ^1.9.0 peerDependenciesMeta: "@opentelemetry/api": optional: false @@ -1815,7 +1815,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/sampling@workspace:packages/sampling" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" "@opentelemetry/sdk-metrics": "npm:~1.28.0" "@opentelemetry/sdk-trace-base": "npm:~1.28.0" "@solarwinds-apm/eslint-config": "workspace:^" @@ -1825,7 +1825,7 @@ __metadata: prettier: "npm:^3.3.3" typescript: "npm:~5.7.2" peerDependencies: - "@opentelemetry/api": ^1.3.0 + "@opentelemetry/api": ^1.9.0 peerDependenciesMeta: "@opentelemetry/api": optional: false @@ -1862,7 +1862,7 @@ __metadata: version: 0.0.0-use.local resolution: "@solarwinds-apm/test@workspace:packages/test" dependencies: - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" "@opentelemetry/sdk-metrics": "npm:~1.28.0" "@opentelemetry/sdk-trace-base": "npm:~1.28.0" "@opentelemetry/sdk-trace-node": "npm:~1.28.0" @@ -7508,7 +7508,7 @@ __metadata: resolution: "solarwinds-apm@workspace:packages/solarwinds-apm" dependencies: "@grpc/grpc-js": "npm:^1.12.2" - "@opentelemetry/api": "npm:^1.3.0" + "@opentelemetry/api": "npm:^1.9.0" "@opentelemetry/api-logs": "npm:~0.55.0" "@opentelemetry/core": "npm:~1.28.0" "@opentelemetry/exporter-logs-otlp-proto": "npm:~0.55.0" @@ -7540,7 +7540,7 @@ __metadata: typescript: "npm:~5.7.2" zod: "npm:^3.23.8" peerDependencies: - "@opentelemetry/api": ^1.3.0 + "@opentelemetry/api": ^1.9.0 peerDependenciesMeta: "@opentelemetry/api": optional: false