Merge branch 'main' into feat/drop-jaeger-exporter

Author: pichlermarc

.github/workflows/ossf-scorecard.yml

@@ -23,7 +23,7 @@ jobs:
  with:
  persist-credentials: false
 
- - uses: ossf/scorecard-action@05b42c624433fc40578a4040d5cf5e36ddca8cde # v2.4.2
+ - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
  with:
  results_file: results.sarif
  results_format: sarif

CHANGELOG.md

@@ -14,14 +14,24 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 
 ### :rocket: Features
 
+* feat(web): add session handling implementation [5173](https://github.com/open-telemetry/opentelemetry-js/pull/5173) @martinkuba
+
 ### :bug: Bug Fixes
 
-* test(shim-opentracing): add comparison thresholds in flaky assertions [#5974](https://github.com/open-telemetry/opentelemetry-js/pull/5974) @cjihrig
+* fix(core): avoid leaking Node.js types via `unrefTimer()` util [#5986](https://github.com/open-telemetry/opentelemetry-js/pull/5986)
+* fix(core): avoid leaking Node.js types via otperformance [#5987](https://github.com/open-telemetry/opentelemetry-js/pull/5987) @pichlermarc
+ * **important:** this bug fix may be breaking for certain uses of `otperformnace`
+ * `otperformance.now()` and `otperformance.timeOrigin` are not affected.
+ * the previously used type was incorrect and overly broad, leading to unexpected run-time behavior runtimes that are not Node.js.
+ * these problems are now caught on compile-time: if you have been using this API and this change is breaking to you, please consider using your target platform's `performance` implementation instead.
 
 ### :books: Documentation
 
 ### :house: Internal
 
+* test(shim-opentracing): add comparison thresholds in flaky assertions [#5974](https://github.com/open-telemetry/opentelemetry-js/pull/5974) @cjihrig
+* test(exporter-jaeger): clean up OTEL_EXPORTER_JAEGER_AGENT_PORT between tests [#6003](https://github.com/open-telemetry/opentelemetry-js/pull/6003) @cjihrig
+
 ## 2.1.0
 
 ### :rocket: Features

README.md

@@ -106,6 +106,23 @@ node -r ./tracing.js app.js
 
 The above example will emit auto-instrumented telemetry about your Node.js application to the console. For a more in-depth example, see the [Getting Started Guide](https://opentelemetry.io/docs/languages/js/getting-started/). For more information about automatic instrumentation see [@opentelemetry/sdk-trace-node][otel-node], which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see [@opentelemetry/sdk-trace-base][otel-tracing]
 
+#### Debugging The Setup
+
+It's possible that an application instrumented as outlined above may not be behaving in an expected manner.
+For example, if the application is meant to be sending data to an Open Telemetry collector, that collector
+may not be receiving any data. Insight into such issues can be gained by enabling a diagnostics logger:
+
+```js
+// Added as additional configuration to tracing.js
+
+const {
+ diag,
+ DiagConsoleLogger,
+ DiagLogLevel
+} = require('@opentelemetry/api');
+diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
+```
+
 ## Library Author
 
 If you are a library author looking to build OpenTelemetry into your library, please see [the documentation][docs]. As a library author, it is important that you only depend on properties and methods published on the public API. If you use any properties or methods from the SDK that are not officially a part of the public API, your library may break if an application owner uses a different SDK implementation.
@@ -218,7 +235,7 @@ For a more detailed breakdown of feature support see the [specification complian
 
 ## Contributing
 
-We'd love your help!. Use tags [up-for-grabs][up-for-grabs-issues] and
+We'd love your help! Use tags [up-for-grabs][up-for-grabs-issues] and
 [good first issue][good-first-issues] to get started with the project. For
 instructions to build and make changes to this project, see the
 [CONTRIBUTING][CONTRIBUTING] guide.

api/package.json

@@ -87,7 +87,7 @@
  "karma-spec-reporter": "0.0.36",
  "karma-webpack": "5.0.1",
  "memfs": "3.5.3",
- "mocha": "11.7.2",
+ "mocha": "11.7.4",
  "nyc": "17.1.0",
  "sinon": "18.0.1",
  "ts-loader": "9.5.4",

doc/semconv-stable-http-and-database.md

@@ -0,0 +1,49 @@
+<!-- markdownlint-disable MD029 -->
+
+# Migrating to stable HTTP and database semantic conventions
+
+This document describes how users of **OTel JS** instrumentations can migrate to stable **HTTP** and **database**-related semantic conventions (semconv).
+
+For example, consider an HTTP client making a `GET /users/42` request that receives an HTTP 200 response status. HTTP instrumentation will generate a [Span](https://opentelemetry.io/docs/concepts/signals/traces/#spans) representing that request/response. Should the HTTP request method be captured with an attribute named `http.method` or `http.request.method`? The response status with `http.status_code` or `http.response.status_code`? This is what semantic conventions define. Which attribute names are used might matter when they are ingested into your Observability system: queries, dashboards, alerts, etc. might be relying on specific attribute names.
+
+To allow users to **migrate** from old names to the stabilized names over a period of time, OpenTelemetry defined a recommended migration process based on setting the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable to indicate whether old, stable, or both sets of field names should be used. See [the HTTP migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/) and the [database migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/).
+
+For **OTel JS users**, as of 2025-10, **not all instrumentations support stable semconv and `OTEL_SEMCONV_STABILITY_OPT_IN` yet**. Support for `http.*` attributes is complete, but not yet for `net.*` and `db.*` attributes.
+
+## What's the easiest thing I can do?
+
+1. Set the `OTEL_SEMCONV_STABILITY_OPT_IN=http/dup,database/dup` environment variable when you configure an OTel JS SDK. This tells instrumentations (that support it) to *emit* both old and stable semconv attributes.
+2. Migrate queries/dashboards/alerts in your Observability system to **use the stable `http.*` semconv** as described in [the HTTP migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/).
+3. For now, continue to **use the old `net.*` and `db.*` attributes** in your Observability system.
+
+Future:
+
+4. When [OTel JS instrumentations support it](https://github.com/open-telemetry/opentelemetry-js/issues/5663): migrate queries/dashboards/alerts in your Observability system to use the stable `net.*` semconv as described in [the HTTP migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/).
+5. When [OTel JS instrumentations support it](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/2953): migrate queries/dashboards/alerts in your Observability system to use the stable `db.*` semconv as described in [the database migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/).
+6. Sometime after a OTel JS SDK 3.0 release (anticipated to be in or after June 2026), you can drop usage of the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable. In JS SDK 3.0, instrumentations will only support the stable HTTP and database semantic conventions.
+
+## Browser instrumentations
+
+Some HTTP-related instrumentations are for use in the browser:
+[`@opentelemetry/instrumentation-fetch`](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-fetch/#semantic-conventions),
+[`@opentelemetry/instrumentation-xml-http-request`](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-xml-http-request/#semantic-conventions), and
+[`@opentelemetry/instrumentation-document-load`](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/packages/instrumentation-document-load/#semantic-conventions). Environment variables don't exist in the browser so, instead of `OTEL_SEMCONV_STABILITY_OPT_IN`, use the `semconvStabilityOptIn` config option to these instrumentations.
+
+## Timeline
+
+- 2023-11:03: In [semconv v1.23.0](https://github.com/open-telemetry/semantic-conventions/blob/main/CHANGELOG.md#v1230-2023-11-03), HTTP semantic conventions were stabilized.
+- 2025-05-02: In [semconv v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/main/CHANGELOG.md#v1330), database semantic conventions were stabilized.
+- 2024-09-10 to 2025-09-19: All OTel JS instrumentations producing `http.*` were updated to support stable semconv and `OTEL_SEMCONV_STABILITY_OPT_IN`.
+- Ongoing: [OTel JS instrumentations producing **`net.*` semconv** are being updated](https://github.com/open-telemetry/opentelemetry-js/issues/5663) to support stable semconv and `OTEL_SEMCONV_STABILITY_OPT_IN`
+- Ongoing: [OTel JS instrumentations producing **`db.*` semconv** are being updated](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/2953) to support stable semconv and `OTEL_SEMCONV_STABILITY_OPT_IN`
+- Projected 2026-06: As part of OTel JS SDK 3.0, instrumentations will emit *stable* HTTP and database semantic conventions by default, and drop support for old names.
+
+## Q&A
+
+### Why are `net.*` attributes controlled by `OTEL_SEMCONV_STABILITY_OPT_IN=http/dup`?
+
+The semantic conventions for a number of networking-related attributes were stabilized as part of the same effort of stabilizing HTTP. Therefore when the [HTTP migration process](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/) was defined, it included migration of `net.*` attributes -- e.g. `net.peer.name → server.address` and `net.protocol.version → network.protocol.version`.
+
+Even though `net.*` attributes are used in non-HTTP instrumentations (e.g. `@opentelemetry/instrumentation-amqplib`, `@opentelemetry/instrumentation-mysql2`) they will still use the `http` (or `http/dup`) value in `OTEL_SEMCONV_STABILITY_OPT_IN`.
+
+(Note: One exception to this is `@opentelemetry/instrumentation-pg`, which added support for stable semconv migration using `OTEL_SEMCONV_STABILITY_OPT_IN=db/dup` for both `net.*` and `db.*` attributes **before** the plan in this document was discussed.)

examples/opentelemetry-web/examples/session/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+ <meta charset="utf-8">
+ <title>Session Example</title>
+ <base href="/">
+
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+</head>
+
+<body>
+ Example of using attaching session attributes to spans and logs.
+ <script type="text/javascript" src="session.js"></script>
+ <button id="button1">generate span</button>
+ <button id="button2">generate log</button>
+</body>
+
+</html>

examples/opentelemetry-web/examples/session/index.js

@@ -0,0 +1,77 @@
+const { ConsoleSpanExporter, SimpleSpanProcessor } = require( '@opentelemetry/sdk-trace-base');
+const { WebTracerProvider } = require( '@opentelemetry/sdk-trace-web');
+const {
+ LoggerProvider,
+ SimpleLogRecordProcessor,
+ ConsoleLogRecordExporter,
+} = require('@opentelemetry/sdk-logs');
+const {
+ createSessionSpanProcessor,
+ createSessionLogRecordProcessor,
+ createSessionManager,
+ createDefaultSessionIdGenerator,
+ LocalStorageSessionStore
+} = require('@opentelemetry/web-common');
+
+// session manager
+const sessionManager = createSessionManager({
+ sessionIdGenerator: createDefaultSessionIdGenerator(),
+ sessionStore: new LocalStorageSessionStore(),
+ maxDuration: 20,
+ inactivityTimeout: 10
+});
+
+sessionManager.addObserver({
+ onSessionStarted: (newSession, previousSession) => {
+ console.log('Session started', newSession, previousSession);
+ },
+ onSessionEnded: (session) => {
+ console.log('Session ended', session);
+ }
+});
+
+// restore or start session
+sessionManager.start();
+
+// configure tracer
+const tracerProvider = new WebTracerProvider({
+ spanProcessors: [
+ createSessionSpanProcessor(sessionManager),
+ new SimpleSpanProcessor(new ConsoleSpanExporter())
+ ]
+});
+
+tracerProvider.register();
+const tracer = tracerProvider.getTracer('example');
+
+// configure logger
+const loggerProvider = new LoggerProvider({
+ processors: [
+ createSessionLogRecordProcessor(sessionManager),
+ new SimpleLogRecordProcessor(new ConsoleLogRecordExporter())
+ ]
+});
+
+const logger = loggerProvider.getLogger('example');
+
+window.addEventListener('load', () => {
+ document.getElementById('button1').addEventListener('click', generateSpan);
+ document.getElementById('button2').addEventListener('click', generateLog);
+});
+
+function generateSpan() {
+ const span = tracer.startSpan('foo');
+ span.setAttribute('key', 'value');
+ span.end();
+}
+
+function generateLog() {
+ logger.emit({
+ attributes: {
+ name: 'my-event',
+ },
+ body: {
+ key1: 'val1'
+ }
+ });
+}

examples/opentelemetry-web/webpack.dev.config.js

@@ -14,6 +14,7 @@ const common = {
  fetchXhrB3: 'examples/fetchXhrB3/index.js',
  'fetch-proto': 'examples/fetch-proto/index.js',
  zipkin: 'examples/zipkin/index.js',
+ session: 'examples/session/index.js'
  },
  output: {
  path: path.resolve(__dirname, 'dist'),

examples/opentelemetry-web/webpack.prod.config.js

@@ -14,6 +14,7 @@ const common = {
  fetchXhrB3: 'examples/fetchXhrB3/index.js',
  "fetch-proto": "examples/fetch-proto/index.js",
  zipkin: 'examples/zipkin/index.js',
+ session: 'examples/session/index.js'
  },
  output: {
  path: path.resolve(__dirname, 'dist'),

experimental/CHANGELOG.md

@@ -14,12 +14,22 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 
 ### :rocket: Features
 
+* feat(sdk-node): always set up propagtion and context manager [#5930](https://github.com/open-telemetry/opentelemetry-js/pull/5930)
+ * using `(new NodeSDK).start()` will now automatically set up a context management and propagation, even if no Trace SDK
+ is initialized.
+* feat(otlp-exporter-base, otlp-grpc-exporter-base): add an option to let an SDK distribution prepend their own user-agent string in HTTP & GRPC exporters [#5928](https://github.com/open-telemetry/opentelemetry-js/pull/5928) @david-luna
+
 ### :bug: Bug Fixes
 
+* fix(sdk-logs): Fix the `batchLogProcessor` exporting only upon `_scheduledDelayMillis` and ignoring `maxExportBatchSize` [#5961](https://github.com/open-telemetry/opentelemetry-js/pull/5961) @jacksonweber
+* fix(otlp-grpc-exporter-base): fix GRPC exporter not sending the user-agent header [#5687](https://github.com/open-telemetry/opentelemetry-js/issues/5867) @david-luna
+
 ### :books: Documentation
 
 ### :house: Internal
 
+* test(opentelemetry-configuration): simplify management of environment variables [#6004](https://github.com/open-telemetry/opentelemetry-js/pull/6004) @cjihrig
+
 ## 0.206.0
 
 ### :rocket: Features
@@ -30,11 +40,14 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 * feat(opentelemetry-configuration): Parse of Configuration File [#5875](https://github.com/open-telemetry/opentelemetry-js/pull/5875) @maryliag
 * feat(opentelemetry-configuration): parse of array objects on configuration file [#5947](https://github.com/open-telemetry/opentelemetry-js/pull/5947) @maryliag
 * feat(opentelemetry-configuration): parse of environment variables on configuration file [#5947](https://github.com/open-telemetry/opentelemetry-js/pull/5947) @maryliag
+* feat(opentelemetry-configuration): parse more parameters from config file [#5955](https://github.com/open-telemetry/opentelemetry-js/pull/5955) @maryliag
+* feat(exporter-prometheus): support withoutTargetInfo option [#5962](https://github.com/open-telemetry/opentelemetry-js/pull/5962) @cjihrig
 
 ### :bug: Bug Fixes
 
 * fix(instrumentation-http): respect requireParent flag when INVALID_SPAN_CONTEXT is used [#4788](https://github.com/open-telemetry/opentelemetry-js/pull/4788) @reberhardt7
 * fix(otlp-transformer): trunc hrTime to int for nanos converting [#5924](https://github.com/open-telemetry/opentelemetry-js/pull/5924) @blumamir
+* fix(instrumentation-http): remove port from ATTR_CLIENT_ADDRESS [#5957](https://github.com/open-telemetry/opentelemetry-js/pull/5957) @cjihrig
 
 ### :house: Internal