Registry / devops / opentelemetry-instrumentation-ws

opentelemetry-instrumentation-ws

library0.5.0jsnpmunverified

OpenTelemetry instrumentation for the `ws` WebSocket library, providing automatic tracing of socket lifecycle events: opens, closes, sends, and optionally messages. Current version 0.5.0 is stable, released monthly. Differentiates from manual instrumentation by patching the `ws` module transparently, supporting both client (`WebSocket`) and server (`ws.Server`) sides, and offering hooks for custom attributes. Requires `ws@^8.5.0` as a peer dependency and the OpenTelemetry Node SDK.

devops messaging

npm install opentelemetry-instrumentation-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENTELEMETRY-INST

opentelemetry-instrumentation-ws

devopsjavascriptv0.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WSInstrumentation

✓ import { WSInstrumentation } from 'opentelemetry-instrumentation-ws'

✗ const WSInstrumentation = require('opentelemetry-instrumentation-ws')

ESM-only since v0.5.0. CommonJS require is not supported.

registerInstrumentations

✓ import { registerInstrumentations } from '@opentelemetry/instrumentation'

✗ import { registerInstrumentations } from 'opentelemetry-instrumentation-ws'

registerInstrumentations is from the base instrumentation package, not this plugin.

WSInstrumentationConfig

✓ import type { WSInstrumentationConfig } from 'opentelemetry-instrumentation-ws'

Type import for TypeScript users to type the config object.

Setup auto-tracing for ws WebSocket client with send spans and message events enabled.

import { WSInstrumentation } from 'opentelemetry-instrumentation-ws'; import { registerInstrumentations } from '@opentelemetry/instrumentation'; import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'; const tracerProvider = new NodeTracerProvider(); tracerProvider.register(); registerInstrumentations({ tracerProvider, instrumentations: [ new WSInstrumentation({ sendSpans: true, messageEvents: true, }), ], }); // Now use 'ws' as usual – spans will be created automatically. import WebSocket from 'ws'; const ws = new WebSocket('wss://echo.websocket.org'); ws.on('open', () => { ws.send('hello'); });

Debug

Known issues

gotchaInstrumentation must be registered before requiring 'ws' to ensure the monkey-patch is applied.

fix

Move registerInstrumentations call to the very top of your entry file, before any imports that pull in 'ws'.

affects: >=0.0.0

gotchasendSpans and messageEvents default to false; spans for send and message events are not created without explicit opt-in.

fix

Set sendSpans: true and/or messageEvents: true in WSInstrumentation config if you need those spans.

affects: >=0.0.0

gotchaThe package is ESM-only and cannot be used with CommonJS require. Node.js must be configured for ESM (e.g., type: 'module' in package.json or .mjs extension).

fix

Switch to ESM imports. For CommonJS projects, use dynamic import: const { WSInstrumentation } = await import('opentelemetry-instrumentation-ws');

affects: >=0.5.0

gotchaIf you use ws.Server, the handleUpgrade span is created only if you use the ws.Server's handleUpgrade method. Directly calling upgrade on http.Server is not traced.

fix

Ensure you use ws.Server and its handleUpgrade method for automatic tracing of upgrades.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: ws.send is not a function

Instrumentation patches the WebSocket constructor, but if you use a different WebSocket implementation (e.g., browser WebSocket), the package won't apply and send may fail if the object is not a true ws instance.

fix

Ensure you are using the 'ws' library version ^8.5.0 and not the browser-native WebSocket.

ERR_REQUIRE_ESM: require() of ES Module not supported

The package is ESM-only, but you are using CommonJS require() to import it.

fix

Use import syntax (ESM) or import dynamically: const { WSInstrumentation } = await import('opentelemetry-instrumentation-ws');

Module not found: Can't resolve 'opentelemetry-instrumentation-ws'

Package not installed or version mismatch.

fix

Run 'npm install opentelemetry-instrumentation-ws' and ensure it's in your package.json dependencies.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

wsrequiredpeer dependency – the library instruments the ws WebSocket implementation

@opentelemetry/instrumentationrequiredrequired to register instrumentation via registerInstrumentations

@opentelemetry/apioptionalrequired for TracerProvider and Span in hooks

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/gadget-inc/opentelemetry-instrumentations ↗

packageopentelemetry-instrumentation-ws ↗

homepagehttps://github.com/gadget-inc/opentelemetry-instrumentations#readme ↗