Add Java-WebSocket instrumentation

[lrwh]

What Does This Do

Adds tracing instrumentation for the org.java-websocket:Java-WebSocket library.

The instrumentation creates WebSocket spans for:

• client and server connection open events
• text and binary message receive events
• message send events
• connection close events

It also injects Datadog propagation headers into the client handshake and extracts them on the server side so client and server WebSocket spans can be connected in the same trace. The new module is registered under dd-java-agent/instrumentation/websocket/java-websocket and can be controlled with DD_TRACE_JAVA_WEBSOCKET_ENABLED.

Motivation

The Java tracer already supports several WebSocket implementations, but applications using the standalone Java-WebSocket library currently do not get automatic WebSocket lifecycle tracing or propagation across the WebSocket handshake.

Additional Notes

Supported Java-WebSocket versions start at 1.4.1, which is the first version in Maven Central that provides the WebSocketClient.addHeader(String, String) API used for handshake propagation.

Validated locally with:

./gradlew :dd-java-agent:instrumentation:websocket:java-websocket:test
./gradlew :dd-java-agent:instrumentation:websocket:java-websocket:spotlessCheck
./gradlew :dd-java-agent:instrumentation:websocket:java-websocket:muzzle
./gradlew checkInstrumenterModuleConfigurations
git diff --check

Suggested labels: type: enhancement, inst: websocket, tag: ai generated.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c7cd7f70cf

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Close the handshake scope on normal connect returns

When WebSocketClient.connect() returns normally (the common asynchronous path), startHandshakeSpan has already activated a scope on the caller thread, but this exit advice only closes it when connect() throws. The later onWebsocketOpen advice activates and closes a different scope on the websocket thread, so the original scope remains active on the application thread and can parent unrelated spans to the handshake/open span after connect() returns. Close the enter scope on the normal path after preserving the span context, or avoid activating it in startHandshakeSpan.

Useful? React with 👍 / 👎.

[lrwh]

Addressed in c9b86e0. The connect exit advice now always closes the enter scope on normal returns without finishing the handshake span, so the span can still be completed by onWebsocketOpen. On the throwable path it also removes the stored client span before finishing it. Added a test assertion that activeSpan() is null immediately after connect() returns.