@defjs/opentelemetry-server 0.0.1-beta.0 → 0.0.2

package/README.md

@@ -1,290 +1,103 @@
 # @defjs/opentelemetry-server
 
-Server-side outbound OpenTelemetry integration for `@defjs/core` HTTP, SSE, and WebSocket clients.
+Server-side outbound OpenTelemetry for `@defjs/core` HTTP, SSE, and WebSocket clients.
 
-**Core Positioning**:
+It is a middleware plugin — the plugin form of an interceptor chain. Your application keeps its OpenTelemetry SDK, providers, exporters, and shutdown; the imported SDK definitions stay free of telemetry configuration. This package is outbound client instrumentation for server applications, not inbound server instrumentation.
 
-- **Outbound-only client instrumentation** — This package wraps defjs clients that make outbound requests. It is not inbound server instrumentation.
-- **Server environment** — Designed for server-side applications with an OpenTelemetry SDK, not browser-only telemetry setup.
-- **Does not initialize the SDK** — This package does not initialize an OpenTelemetry SDK. Register a `TracerProvider` (`setGlobalTracerProvider`, or your SDK's `start()`) then pass that tracer (and optional meter) into `withOpenTelemetryServer(...)`. `trace.getTracer(...)` with no provider is a silent no-op.
-- **Per-transport separation** — HTTP, SSE, and WebSocket each have independent interceptors, span lifecycles, and metric dimensions.
-
-## Installation
-
-Install `@defjs/opentelemetry-server` with the matching `@defjs/core` release line and its OpenTelemetry peers:
+## Install
 
 ```sh
 bun add @defjs/core @defjs/opentelemetry-server @opentelemetry/api @opentelemetry/core
 ```
 
-The package is ESM and requires `@defjs/core` as a peer in the `^0.4.0` range. Its tarball retains this `README.md` and the repository `LICENSE`; repository-wide guides and examples remain outside the package.
+The package is ESM and requires `@defjs/core` as a peer in the `^0.5.0` range.
 
-Initialize your application's OpenTelemetry SDK separately so a `TracerProvider` is registered. The package provides interceptors and consumes the tracer you pass; it does not emit spans on its own.
+## Quick start
 
-## Basic Usage
-
-This package does not install a `TracerProvider`. `trace.getTracer('my-service')` without `trace.setGlobalTracerProvider(...)` (your SDK's `start()` usually does this) returns a no-op tracer: interceptors still wrap requests, but spans are silently discarded. Pass a recording tracer from your SDK, or register the provider first:
+It never initializes a provider or looks one up implicitly: pass the `tracer`, `meter`, and `logger` you want, and each signal works independently. Without a `tracer` no spans are created — interceptors still wrap requests, but `trace.getTracer()` returns a no-op until your SDK registers a provider.
 
 ```typescript
-import { createClient, withEndpoint } from '@defjs/core'
-import { withOpenTelemetryServer } from '@defjs/opentelemetry-server'
-import { trace } from '@opentelemetry/api'
+import { createClient, withEndpoint } from "@defjs/core";
+import { withOpenTelemetryServer } from "@defjs/opentelemetry-server";
+import { trace } from "@opentelemetry/api";
 
 // After your OpenTelemetry SDK has called setGlobalTracerProvider:
-const tracer = trace.getTracer('my-service')
+const tracer = trace.getTracer("my-service");
 
 const client = createClient(
-  withEndpoint('https://api.example.com'),
-  withOpenTelemetryServer({
-    tracer,
-  }),
-)
+  withEndpoint("https://api.example.com"),
+  withOpenTelemetryServer({ tracer }),
+);
 ```
 
-## Operation Identity
-
-Set the optional `operation` field statically on `defineRequest(...)`, `defineEventStream(...)`, or `defineWebSocket(...)`:
+Omit `tracer` to record metrics only; the plugin then never calls `trace.getTracer(...)` or the span hooks. `logger` accepts the native `Logger` from `@opentelemetry/api-logs`, not a Winston or Pino business logger.
 
 ```typescript
-const readOrder = defineRequest({
-  method: 'GET',
-  operation: 'orders.read',
-  path: '/orders/:id',
-  // input and output omitted
-})
-```
-
-An explicit operation is the low-cardinality transport identity. HTTP spans use names such as `GET orders.read`; SSE and WebSocket spans use `SSE orders.watch` and `WebSocket orders.connect`. Spans and metrics also receive `defjs.operation`.
+import { metrics } from "@opentelemetry/api";
 
-Without `operation`, the previous fallback remains unchanged: HTTP uses the request method as its span name, SSE uses `SSE`, WebSocket uses `WebSocket`, and `defjs.operation` is omitted. Never infer an operation from `req.endpoint`, a resolved URL, or a path containing identifiers. Do not copy resolved URLs into custom attributes or logs.
+const meter = metrics.getMeter("my-service");
 
-## Full Configuration
-
-```typescript
 const client = createClient(
-  withEndpoint('https://api.example.com'),
-  withOpenTelemetryServer({
-    tracer, // Required
-    meter, // Optional, metrics only collected when provided
-    propagator, // Optional, default W3C TraceContext + Baggage
-    requireParentSpan: false,
-    http: {
-      enabled: true,
-      startSpanHook(req) {
-        return { 'app.operation': req.operation ?? 'unclassified' }
-      },
-      responseHook(span, res, req) {
-        span.setAttribute('defjs.response.status_text', res.statusText)
-      },
-    },
-    sse: {
-      enabled: true,
-    },
-    webSocket: {
-      enabled: true,
-      queryPropagation: false, // Safe default; set true only after reviewing URL propagation
-    },
-  }),
-)
+  withEndpoint("https://api.example.com"),
+  withOpenTelemetryServer({ meter }),
+);
 ```
 
-## WebSocket propagation safety
+## Operation identity
 
-`webSocket.queryPropagation` defaults to `false`. Omitting it leaves the WebSocket query string unchanged and does not inject trace context or baggage into the URL.
+Set `operation` statically on the definition. It is the low-cardinality transport identity: spans are named `GET orders.read`, `SSE orders.watch`, `WebSocket orders.connect`, and `defjs.operation` is recorded on spans and metrics.
 
-Browser WebSocket clients usually cannot set arbitrary headers. If you have reviewed URL-based propagation for your environment and accept its exposure boundary, enable it explicitly:
-
-```ts
-withOpenTelemetryServer({
-  tracer,
-  webSocket: {
-    queryPropagation: true,
-  },
-})
+```typescript
+const readOrder = defineRequest({
+  method: "GET",
+  operation: "orders.read",
+  path: "/orders/:id",
+});
 ```
 
-Query strings can be recorded by proxies, browsers, APM tooling, access logs, and network debugging tools. They may also contain tokens or other high-cardinality user input. If your propagator includes `baggage`, baggage values can also be written into the URL and may contain sensitive data.
-
-With the safe default, trace context does not ride on the WebSocket URL. Use another reviewed correlation mechanism at the application layer, such as a protocol-reviewed first frame or a short-lived connection ticket, if your server still needs to link the connection to a trace.
-
-### Configuration Options
-
-| Option              | Type                                  | Default                    | Description                                                  |
-| ------------------- | ------------------------------------- | -------------------------- | ------------------------------------------------------------ |
-| `tracer`            | `Tracer`                              | **Required**               | External OpenTelemetry tracer                                |
-| `meter`             | `Meter`                               | `undefined`                | External OpenTelemetry meter, omitting disables metrics      |
-| `propagator`        | `TextMapPropagator`                   | W3C TraceContext + Baggage | Custom context propagator                                    |
-| `requireParentSpan` | `boolean`                             | `false`                    | Only create outbound spans when an active parent span exists |
-| `http`              | `OpenTelemetryServerHttpOptions`      | `{}`                       | HTTP transport trace/metric options                          |
-| `sse`               | `OpenTelemetryServerSSEOptions`       | `{}`                       | SSE transport trace/metric options                           |
-| `webSocket`         | `OpenTelemetryServerWebSocketOptions` | `{}`                       | WebSocket transport trace/metric options                     |
-
-### HTTP Options
-
-| Option          | Type                                        | Default     | Description                                                                    |
-| --------------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------------ |
-| `enabled`       | `boolean`                                   | `true`      | Enable HTTP tracing                                                            |
-| `startSpanHook` | `(req) => Attributes`                       | `undefined` | Add or override synchronous initial attributes before the HTTP span is created |
-| `requestHook`   | `(span, req) => void \| Promise<void>`      | `undefined` | Customize HTTP span before request, `req` is `HttpRequest`                     |
-| `responseHook`  | `(span, res, req) => void \| Promise<void>` | `undefined` | Customize HTTP span after response; `req` is the original `HttpRequest`        |
-
-### SSE Options
-
-| Option          | Type                                           | Default     | Description                                                                          |
-| --------------- | ---------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
-| `enabled`       | `boolean`                                      | `true`      | Enable SSE tracing                                                                   |
-| `startSpanHook` | `(req) => Attributes`                          | `undefined` | Add or override synchronous initial attributes before the SSE span is created        |
-| `requestHook`   | `(span, req) => void \| Promise<void>`         | `undefined` | Customize SSE span before stream request                                             |
-| `responseHook`  | `(span, stream, req) => void \| Promise<void>` | `undefined` | Customize SSE span after stream handle returned; `req` is the original `HttpRequest` |
-
-### WebSocket Options
-
-| Option             | Type                                            | Default     | Description                                                                                                                         |
-| ------------------ | ----------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`          | `boolean`                                       | `true`      | Enable WebSocket tracing                                                                                                            |
-| `queryPropagation` | `boolean`                                       | `false`     | Inject trace context and baggage into the WebSocket URL query string. Enable only after reviewing URL logging and disclosure risks. |
-| `startSpanHook`    | `(req) => Attributes`                           | `undefined` | Add or override synchronous initial attributes before the WebSocket span is created                                                 |
-| `requestHook`      | `(span, req) => void \| Promise<void>`          | `undefined` | Customize WebSocket span before connection request                                                                                  |
-| `responseHook`     | `(span, session, req) => void \| Promise<void>` | `undefined` | Customize WebSocket span after session returned; `req` is the original `HttpRequest`                                                |
-
-> **Hook timing and failures**: `startSpanHook(request)` is synchronous and runs before span creation. Its attributes are applied after built-in attributes. If it throws, Defjs creates the span with built-in attributes, records `defjs.otel.hook.error`, and the client request/stream/session continues normally. `requestHook` and `responseHook` run after creation and may return `void` or `Promise<void>`; their throws/rejections are recorded without blocking the operation.
->
-> Each `responseHook` receives the original transport `HttpRequest` as its third argument. Read its explicit `operation`; do not reconstruct identity from its endpoint or a resolved URL.
->
-> **Attribute hygiene**: This package has no built-in redactor or sensitive-key policy. Prefer explicit allowlists, application-owned redaction, and stable low-cardinality attributes in hooks. Do not attach resolved URLs, raw query strings, request or response bodies, full headers, baggage values, or message payloads unless your application has already reviewed privacy, cardinality, retention, and redaction requirements.
-
-## HTTP Semantic Conventions and Metrics
-
-HTTP tracing uses stable OpenTelemetry HTTP client attribute and metric names. This is not a claim of complete semantic-convention compliance. With an explicit operation, the interceptor creates a `SpanKind.CLIENT` span named `${method} ${operation}` and records `defjs.operation`. Without one, it preserves the previous method-only span name and omits that attribute. It also records:
-
-- `http.request.method`
-- `url.full`
-- `server.address`
-- `server.port`
-- `http.response.status_code` only when a response status was received
-
-HTTP span status and `error.type` follow these rules:
-
-- status `100` through `399` leaves span status unset and does not set `error.type`;
-- status `400` and above marks the client span `ERROR` and sets `error.type` to the status code string;
-- a Defjs status-0 transport result does not set `http.response.status_code`; caller cancellation leaves status unset, timeout uses `ERROR` / `TIMEOUT`, and other transport failures use `ERROR` / `NETWORK_ERROR`;
-- an error thrown through the interceptor marks the span `ERROR`, records the exception, and uses its `Error.name` or another low-cardinality type fallback as `error.type`.
+Without it, HTTP spans use the method alone and SSE/WebSocket use their transport name. Never derive an operation from a resolved URL or a path containing identifiers.
 
-In the current implementation, `url.full` is resolved from `req.endpoint` and the optional `req.baseEndpoint`; it does not append `req.queryString`. This is an implementation boundary, not sanitization, an identity source, or a guarantee that URLs are safe. Applications that need a complete or redacted URL can override the initial value explicitly:
-
-```ts
-import { createResolvedRequestUrl } from '@defjs/core'
+## Configuration
 
+```typescript
 withOpenTelemetryServer({
-  tracer,
-  http: {
-    startSpanHook(req) {
-      if (!req.baseEndpoint) return {}
-      const url = createResolvedRequestUrl(req.baseEndpoint, req.endpoint)
-      if (req.queryString) url.search = req.queryString
-      url.searchParams.delete('access_token')
-      return { 'url.full': url.href }
-    },
-  },
-})
-```
-
-Resolved paths can contain sensitive or high-cardinality identifiers. Keep operation names static and apply application or SDK/exporter redaction before exporting URL attributes.
-
-When `meter` is provided, the following stable metrics are collected:
-
-| Metric                         | Unit | Attributes                                                                                                                                      |
-| ------------------------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `http.client.request.duration` | `s`  | `http.request.method`, optional `defjs.operation`, `server.address`, `server.port`, optional `http.response.status_code`, optional `error.type` |
-
-The metric applies the same response-status and `error.type` classification as the HTTP span.
-
-### Transport span boundary
-
-The HTTP span ends when the interceptor receives the Defjs `HttpResponse`. Exact output-status dispatch and Struct decoding happen afterward, so a later `RESPONSE_VALIDATION_FAILED` or `UNDECLARED_STATUS` cannot update that transport span.
-
-When telemetry must represent the final command outcome, create an application span around `client.execute(...)` and classify the returned tuple:
-
-```ts
-import { SpanStatusCode } from '@opentelemetry/api'
-
-const outcome = await tracer.startActiveSpan('defjs.command', async (span) => {
-  try {
-    const outcome = await client.execute(command)
-    const [error] = outcome
-    if (error) {
-      span.setAttribute('error.type', error.code)
-      span.setStatus({ code: SpanStatusCode.ERROR })
-    }
-    return outcome
-  } catch (error) {
-    span.setAttribute('error.type', error instanceof Error ? error.name : typeof error)
-    span.setStatus({ code: SpanStatusCode.ERROR })
-    throw error
-  } finally {
-    span.end()
-  }
-})
+  tracer, // optional: local spans and span hooks
+  meter, // optional: metrics
+  logger, // optional: failure diagnostics only
+  propagator, // optional: defaults to W3C TraceContext + Baggage
+  requireParentSpan: false,
+  http: { enabled: true, startSpanHook, requestHook, responseHook },
+  sse: { enabled: true, startSpanHook, requestHook, responseHook },
+  webSocket: { enabled: true, queryPropagation: false },
+});
 ```
 
-This outer span is application-owned command telemetry; the plugin continues to emit only its lower-level transport span.
-
-This package does not add request or response bodies, full headers, baggage values, payload sizes, or message payloads as default custom telemetry fields. It also does not create separate span attributes or metrics for raw query strings.
-
-Do not add raw query strings, request or response bodies, full headers, baggage values, or message payloads to spans or metrics unless the application has reviewed privacy, cardinality, retention, and redaction requirements. Prefer explicit allowlists, redaction, and stable low-cardinality attributes when extending telemetry with hooks.
-
-## SSE Connection-Level Tracing and Custom Metrics
-
-SSE is a long-lived HTTP response. Normal HTTP request duration ends at stream establishment, which does not reflect whether the stream is still running, interrupted, or errored. Therefore, this package treats SSE as **connection-level** telemetry.
-
-### Span Lifecycle
-
-After startup succeeds, the SSE interceptor attaches to `stream.closed` and keeps the span open until the stream reaches its normal, fatal, or aborted terminal state. It records:
-
-- `sse.connected` — Stream successfully established
-- `sse.closed` — Stream normal end (server EOF)
-- `sse.aborted` — Active close via `stream.close()`
-- `sse.error` — Connection error or reconnect exhaustion
-
-### Custom Metrics
-
-When `meter` is provided, the following defjs custom metrics are collected (non-official OpenTelemetry stable semantic conventions):
-
-| Metric                                 | Unit       | Meaning                                                 |
-| -------------------------------------- | ---------- | ------------------------------------------------------- |
-| `defjs.client.sse.connect.duration`    | `s`        | Time to establish stream connection                     |
-| `defjs.client.sse.connection.duration` | `s`        | Total duration from stream establishment to close/error |
-| `defjs.client.sse.active_streams`      | `{stream}` | Current active SSE stream count                         |
-
-By default, **per-event spans are not created**, and **event payloads, event IDs, `Last-Event-ID`, delivery latency, lost events, or reconnect queues are not collected**. These are application-level semantics that may produce high-cardinality or sensitive telemetry. Implement them at the application layer if needed.
-
-## WebSocket Connection-Level Tracing and Custom Metrics
-
-WebSocket starts with an HTTP Upgrade handshake, but production environments care more about the post-handshake connection lifecycle: active connections, connection duration, close/error behavior, and connection failure rate. Since OpenTelemetry WebSocket semantic conventions are not yet stable, this package uses connection-level custom metrics.
-
-### Span Lifecycle
-
-The WebSocket span stays open until `session.closed` resolves, recording the following lifecycle events:
+| Option              | Type                                    | Default                    | Description                                                                 |
+| ------------------- | --------------------------------------- | -------------------------- | --------------------------------------------------------------------------- |
+| `tracer`            | `Tracer`                                | `undefined`                | External tracer; omitting disables local spans and hooks                    |
+| `meter`             | `Meter`                                 | `undefined`                | External meter; omitting disables metrics                                   |
+| `logger`            | `Logger` from `@opentelemetry/api-logs` | `undefined`                | External native Logger; omitting disables diagnostic LogRecords             |
+| `propagator`        | `TextMapPropagator`                     | W3C TraceContext + Baggage | Custom context propagator                                                   |
+| `requireParentSpan` | `boolean`                               | `false`                    | With a tracer, bypass all instrumentation when no active parent span exists |
+| `http`              | `OpenTelemetryServerHttpOptions`        | `{}`                       | HTTP transport options                                                      |
+| `sse`               | `OpenTelemetryServerSSEOptions`         | `{}`                       | SSE transport options                                                       |
+| `webSocket`         | `OpenTelemetryServerWebSocketOptions`   | `{}`                       | WebSocket transport options                                                 |
 
-- `websocket.connected` — Session successfully established
-- `websocket.closed` — Connection normal close
-- `websocket.error` — Connection error
+Span hooks run only with a `tracer`. `startSpanHook(request)` is synchronous and runs before span creation; a throw leaves the built-in attributes and the operation continues. `requestHook` and `responseHook` are not awaited, and their failures never block or fail the operation. Configure `diag.setLogger(...)` to see hook diagnostics.
 
-### Custom Metrics
+## Privacy defaults
 
-When `meter` is provided, the following defjs custom metrics are collected:
+- `webSocket.queryPropagation` defaults to `false`: trace context and baggage do not ride on the WebSocket URL. Enable it only after reviewing how your proxies, browsers, and access logs record query strings.
+- No bodies, full headers, baggage values, or message payloads are added as telemetry fields, and no built-in redactor exists. Prefer allowlists and low-cardinality attributes in hooks.
+- Diagnostics carry a fixed message, phase, operation, server address/port, and exception type — not raw URLs, headers, bodies, or stacks.
+- SSE and WebSocket are traced per connection, not per event or message.
 
-| Metric                                       | Unit           | Meaning                                                  |
-| -------------------------------------------- | -------------- | -------------------------------------------------------- |
-| `defjs.client.websocket.connect.duration`    | `s`            | Time to establish WebSocket session                      |
-| `defjs.client.websocket.connection.duration` | `s`            | Total duration from session establishment to close/error |
-| `defjs.client.websocket.active_connections`  | `{connection}` | Current active WebSocket connection count                |
+## Documentation
 
-By default, **per-message spans are not created**, and **message payloads, message sizes, backpressure, buffered amount, subprotocols, or reconnect queues are not collected**. Keep any application-layer message telemetry opt-in, sampled, redacted, and limited to stable low-cardinality attributes whenever possible.
+- [OpenTelemetry guide](https://defjs.lyz.cloud/docs/integrations/opentelemetry-server) — full option tables, log events, span lifecycles, metrics, and third-party logging
+- [OpenTelemetry API](https://defjs.lyz.cloud/api/opentelemetry-server)
+- [Client](https://defjs.lyz.cloud/docs/client) · [SSE](https://defjs.lyz.cloud/docs/sse) · [WebSocket](https://defjs.lyz.cloud/docs/web-socket)
 
-## What's Next
+## License
 
-- [OpenTelemetry guide](https://defjs.org/plugins/opentelemetry-server) — complete plugin boundaries and examples
-- [Client](https://defjs.org/core/client) — `createClient` and full transport configuration
-- [SSE](https://defjs.org/core/sse) — `defineEventStream` and streaming event consumption
-- [WebSocket](https://defjs.org/core/web-socket) — `defineWebSocket` and real-time communication
+MIT.

package/index.d.ts

@@ -1,7 +1,25 @@
 import { ClientOption, EventStreamHandle, HttpRequest, HttpResponse, WebSocketSessionLike } from "@defjs/core";
 import { Attributes, Meter, Span, TextMapPropagator, Tracer } from "@opentelemetry/api";
-//#region src/option.d.ts
-/** Shared per-transport OpenTelemetry client options. */
+import { Logger } from "@opentelemetry/api-logs";
+/**
+ * Shared per-transport OpenTelemetry client options: whether the transport is enabled and its span hooks, generic over the response type.
+ *
+ * `TResponse` is what `responseHook` receives: `HttpResponse<unknown>` for HTTP, `EventStreamHandle<unknown>` for SSE, `WebSocketSessionLike` for WebSocket. See {@link OpenTelemetryServerHttpOptions}, {@link OpenTelemetryServerSSEOptions} and {@link OpenTelemetryServerWebSocketOptions}.
+ *
+ * `enabled` defaults to `true`; only `enabled: false` turns the transport off. The old boolean switch (`http: false`) and top-level hooks are rejected by the TypeScript types only. There is no runtime check, so at runtime `http: false` leaves the transport enabled and a top-level hook is silently ignored.
+ *
+ * Span hooks run only when a `tracer` is supplied. `startSpanHook` runs synchronously before span creation for its own transport. Its attributes are applied after built-in attributes, so the application may override `url.full` or another initial value. If it throws, Defjs creates the span with built-in attributes and continues the request. `requestHook` runs after span creation and before the request is sent; `responseHook` runs after the transport result is returned. Both may return a promise, but neither is awaited: a throw or rejection never blocks or fails the operation. `responseHook` receives the original request as its third argument.
+ *
+ * While `span.isRecording()` is true, hook failures record `defjs.otel.hook.error` and `exception` events. For non-recording spans (ended or unsampled), failures go to the OpenTelemetry diagnostic logger through `diag.error`. Applications must configure `diag.setLogger(...)` from `@opentelemetry/api` to receive them; there is no automatic output by default. The package does not initialize the SDK, and this diagnostic is not a separate SDK `LogRecord`.
+ *
+ * By default, `url.full` resolves only `request.endpoint` against optional `request.baseEndpoint`; an independent `request.queryString` is not appended. That boundary is not redaction, and the package has no built-in redactor or sensitive-key policy. Construct and, if needed, redact an application-owned URL explicitly.
+ *
+ * @group opentelemetry-server
+ * @see {@link OpenTelemetryServerHttpOptions}
+ * @see {@link OpenTelemetryServerSSEOptions}
+ * @see {@link OpenTelemetryServerWebSocketOptions}
+ * @exampleFile examples/api/opentelemetry-server-transport-options.ts#example
+ */
 interface OpenTelemetryServerTransportOptions<TResponse> {
   /** Whether this transport's instrumentation is enabled. Defaults to `true`. */
   enabled?: boolean;
@@ -12,8 +30,54 @@ interface OpenTelemetryServerTransportOptions<TResponse> {
   /** Customize the client span after the transport result is returned. */
   responseHook?: (span: Span, res: TResponse, req: HttpRequest) => Promise<void> | void;
 }
+/**
+ * Options for the HTTP transport — the shared options with an HttpResponse in responseHook.
+ *
+ * Set on `http` in `OpenTelemetryServerOptions`. It has no fields of its own: `enabled`, `startSpanHook`, `requestHook` and `responseHook` come from `OpenTelemetryServerTransportOptions`.
+ *
+ * - `responseHook(span, res, req)` receives the `HttpResponse` that came back through the interceptor, before the client decodes a declared body, together with the original `HttpRequest`. Read `req.operation` for the request identity; do not rebuild it from the endpoint or a resolved URL.
+ *
+ * - The HTTP span ends as soon as `responseHook` returns; the hook is not awaited, so only its synchronous part can still change the span. A status of 400 or above ends it `ERROR` with `error.type` set to the status string; 100–399 leaves its status unset. An asynchronous hook rejection after end is reported through `diag.error`; configure `diag.setLogger(...)` from `@opentelemetry/api` to receive it. It cannot append events to an ended span.
+ *
+ * - A rejection through the interceptor has no response status and does not call `responseHook`. That includes a network failure, caller cancellation, an abort whose reason is `TimeoutError`, any declared-body read failure (`BodyFailure`, including text, blob, and bytes, not only JSON), and a progress observer failure (`EXT_OBSERVER_FAILED`). The span ends `ERROR` with `error.type` set to the thrown class name, such as `TypeError`, `Error` or `BodyFailure`. Caller cancellation is `Error` whatever the abort reason. There is no `timeout` option; a deadline is `abort`.
+ *
+ * Pass `{ enabled: false }` to skip HTTP instrumentation. Span hooks run only when a `tracer` is supplied.
+ *
+ * @group opentelemetry-server
+ * @see {@link OpenTelemetryServerTransportOptions}
+ */
 type OpenTelemetryServerHttpOptions = OpenTelemetryServerTransportOptions<HttpResponse<unknown>>;
+/**
+ * Options for the SSE transport — the shared options with the stream handle in responseHook.
+ *
+ * Set on `sse` in `OpenTelemetryServerOptions`. It has no fields of its own: `enabled`, `startSpanHook`, `requestHook` and `responseHook` come from `OpenTelemetryServerTransportOptions`.
+ *
+ * - `responseHook(span, stream, req)` runs once the stream has opened, before the span records `sse.connected`. `stream` is the `EventStreamHandle` the transport returned; `req` is the original `HttpRequest`.
+ *
+ * - SSE is traced at connection level. After startup the span stays open until `stream.closed` settles, and records `sse.connected`, then one of `sse.closed` (server EOF), `sse.aborted` (`stream.close()` or a caller abort of the open stream whose reason is not `TimeoutError`; the span still ends without error), or `sse.error` (including an abort whose reason is `TimeoutError`, which ends the span `ERROR`). No per-event spans are created.
+ *
+ * - A non-2xx handshake is observed as a connection failure: the span ends `ERROR` and, with a `logger`, one `WARN` is emitted whatever the response body.
+ *
+ * Pass `{ enabled: false }` to skip SSE instrumentation. Span hooks run only when a `tracer` is supplied.
+ *
+ * @group opentelemetry-server
+ * @see {@link OpenTelemetryServerTransportOptions}
+ */
 type OpenTelemetryServerSSEOptions = OpenTelemetryServerTransportOptions<EventStreamHandle<unknown>>;
+/**
+ * Options for the WebSocket transport — the shared options plus queryPropagation.
+ *
+ * Set on `webSocket` in `OpenTelemetryServerOptions`. `enabled`, `startSpanHook`, `requestHook` and `responseHook` come from `OpenTelemetryServerTransportOptions`; `responseHook(span, session, req)` receives the opened `WebSocketSessionLike` and the original `HttpRequest`.
+ *
+ * `queryPropagation` defaults to `false`: the WebSocket query string is left unchanged and no trace context or baggage is written into the URL. Browser WebSocket clients usually cannot set headers, so enabling it writes the propagated context to the end of the query string, replacing any parameter of the same name. Query strings can be recorded by proxies, access logs and APM tools, and baggage values can be sensitive. Turn it on only after you accept that exposure.
+ *
+ * WebSocket is traced at connection level. The span stays open until `session.closed` settles. It records `websocket.connected`, then `websocket.closed` for a normal close or `websocket.error`. A close frame from the server counts as normal with any code, including 1011. An abrupt drop without a close frame (1006) is normal only where the runtime reports no socket `error` before `close` (Bun); where it does (Node.js), the session ends in error and logs once. A caller abort of an open session is also `websocket.error`: the span ends `ERROR` and no log is emitted. `error.type` follows the abort reason: `AbortError` for a default `abort()`, the `Error.name` of an `Error` reason, `string` for a string reason. An abort while the WebSocket is still connecting ends the span `ERROR` with `error.type` `DefjsFault`. No per-message spans are created.
+ *
+ * Pass `{ enabled: false }` to skip WebSocket instrumentation. Span hooks run only when a `tracer` is supplied.
+ *
+ * @group opentelemetry-server
+ * @see {@link OpenTelemetryServerTransportOptions}
+ */
 interface OpenTelemetryServerWebSocketOptions extends OpenTelemetryServerTransportOptions<WebSocketSessionLike> {
   /**
    * Inject trace context into the WebSocket URL query string.
@@ -22,19 +86,39 @@ interface OpenTelemetryServerWebSocketOptions extends OpenTelemetryServerTranspo
   queryPropagation?: boolean;
 }
 /**
- * Options for {@link withOpenTelemetryServer}.
+ * Options for {@link withOpenTelemetryServer}: tracer, meter, logger, propagator, and per-transport settings.
  *
- * Pass an application-owned OpenTelemetry `Tracer` (and optional `Meter`).
+ * Pass application-owned OpenTelemetry `Tracer`, `Meter`, and/or `Logger` handles.
  * This package does not initialize the OpenTelemetry SDK.
+ *
+ * - `tracer` — Optional. Without it there are no local spans and no span hooks.
+ *
+ * - `meter` — Optional. Without it no package metrics are recorded.
+ *
+ * - `logger` — Optional. A `Logger` from `@opentelemetry/api-logs`, not a Winston/Pino Logger. Without it no diagnostic LogRecords are emitted. Defjs never obtains a global logger or owns its provider.
+ *
+ * - `propagator` — Defaults to W3C Trace Context + Baggage.
+ *
+ * - `requireParentSpan` — Defaults to `false`. With a `tracer`, `true` bypasses all instrumentation, including logs, when no active parent span exists. Without a `tracer` it blocks neither metrics nor logs.
+ *
+ * - `http`, `sse`, `webSocket` — Per-transport options. Each defaults to `{}`; a transport is disabled only by `{ enabled: false }`.
+ *
+ * @group opentelemetry-server
+ * @see {@link OpenTelemetryServerHttpOptions}
+ * @see {@link OpenTelemetryServerSSEOptions}
+ * @see {@link OpenTelemetryServerWebSocketOptions}
+ * @see {@link OpenTelemetryServerTransportOptions}
  */
 interface OpenTelemetryServerOptions {
-  /** OpenTelemetry tracer used for outbound client spans. */
-  tracer: Tracer;
+  /** Optional tracer; omitting it disables outbound spans and span hooks. */
+  tracer?: Tracer;
   /** Optional meter; when set, per-transport client metrics are recorded. */
   meter?: Meter;
+  /** Optional logger; emits WARN diagnostics for failed outbound requests and connections. */
+  logger?: Logger;
   /** Context propagator. Defaults to W3C Trace Context + Baggage. */
   propagator?: TextMapPropagator;
-  /** When `true`, only create an outgoing span if an active parent span exists. */
+  /** With a tracer, bypass instrumentation when no active parent span exists. Ignored without a tracer. */
   requireParentSpan?: boolean;
   /** HTTP transport instrumentation options. */
   http?: OpenTelemetryServerHttpOptions;
@@ -46,20 +130,21 @@ interface OpenTelemetryServerOptions {
 /**
  * Client option that installs outbound OpenTelemetry interceptors for HTTP, SSE, and WebSocket.
  *
- * Does not initialize the OpenTelemetry SDK — supply a `tracer` (and optional `meter`) from your app.
- * Each transport can be toggled or customized via `http`, `sse`, and `webSocket`.
+ * Appends one interceptor per enabled transport, in the order HTTP, SSE, WebSocket. Apply it at `createClient` time. It does not initialize the OpenTelemetry SDK or acquire global tracer, meter, or logger handles: pass the ones your application owns. Each transport can be toggled or customized via `http`, `sse`, and `webSocket`.
+ *
+ * `options` is required. It carries `tracer`, `meter`, `logger`, `propagator`, `requireParentSpan`, and the `http` / `sse` / `webSocket` transport options. Pass `{}` to install the interceptors with propagation only.
+ *
+ * Each of `tracer`, `meter` and `logger` is optional and works without the others. Without `tracer`, the plugin creates no local spans, never calls `trace.getTracer(...)`, and skips `startSpanHook`, `requestHook` and `responseHook`. Propagation still forwards the extracted parent context.
+ *
+ * HTTP, SSE, and WebSocket are on by default. Pass `{ enabled: false }` on a transport to skip it.
  *
- * @param options - Tracer, optional meter/propagator, and per-transport settings.
+ * @param options - Required settings object. Each of `tracer`, `meter`, `logger`, and `propagator` may be omitted; pass `{}` for propagation only.
  * @returns A `ClientOption` for `createClient(...)`.
  *
- * @example
- * ```ts
- * const client = createClient(
- *   withEndpoint('https://api.example.com'),
- *   withOpenTelemetryServer({ tracer }),
- * )
- * ```
+ * @group opentelemetry-server
+ * @see {@link ClientOption}
+ * @see {@link OpenTelemetryServerOptions}
+ * @exampleFile examples/api/with-opentelemetry-server.ts#example
  */
 export declare function withOpenTelemetryServer(options: OpenTelemetryServerOptions): ClientOption;
-//#endregion
 export type { OpenTelemetryServerHttpOptions, OpenTelemetryServerOptions, OpenTelemetryServerSSEOptions, OpenTelemetryServerTransportOptions, OpenTelemetryServerWebSocketOptions };

package/index.js

@@ -1,7 +1,8 @@
 import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } from "@opentelemetry/core";
-import { ERR_ABORTED, createHttpInterceptor, createResolvedRequestUrl, createSSEInterceptor, createTransportError, createWebSocketInterceptor } from "@defjs/core";
-import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
-//#region src/propagation/carrier.ts
+import { ERR_ABORTED, createHttpInterceptor, createResolvedRequestUrl, createSSEInterceptor, createWebSocketInterceptor, isAbortCause, isTimeoutCause } from "@defjs/core";
+import { SpanKind, SpanStatusCode, context, diag, trace } from "@opentelemetry/api";
+import { SeverityNumber } from "@opentelemetry/api-logs";
+// src/propagation/carrier.ts
 const headersSetter = { set(carrier, key, value) {
 	if (carrier && key && value !== void 0) carrier.set(key, String(value));
 } };
@@ -16,10 +17,9 @@ const headersGetter = {
 	}
 };
 const queryStringSetter = { set(carrier, key, value) {
-	if (carrier && key && value !== void 0) carrier.params.append(key, String(value));
+	if (carrier && key && value !== void 0) carrier.params.set(key, String(value));
 } };
-//#endregion
-//#region src/telemetry/trace.ts
+// src/telemetry/trace.ts
 const spanStatusSet = /* @__PURE__ */ new WeakMap();
 function markSpanStatusSet(span) {
 	spanStatusSet.set(span, true);
@@ -69,9 +69,9 @@ function createWebSocketSpan(tracer, url, parentCtx, operation, startAttributes)
 		}
 	}, parentCtx);
 }
-function setSpanHttpResponse(span, status, error) {
+function setSpanHttpResponse(span, status) {
 	if (status !== 0) span.setAttribute("http.response.status_code", status);
-	const errorType = getHttpResponseErrorType(status, error);
+	const errorType = getHttpResponseErrorType(status);
 	if (errorType) {
 		span.setAttribute("error.type", errorType);
 		span.setStatus({ code: SpanStatusCode.ERROR });
@@ -100,6 +100,18 @@ function runSpanHook(span, hookName, hook) {
 	}
 }
 function recordSpanHookError(span, hookName, error) {
+	if (!span.isRecording()) {
+		try {
+			const { traceId, spanId } = span.spanContext();
+			diag.error("@defjs/opentelemetry-server: span hook failed on a non-recording span", {
+				"hook.name": hookName,
+				"error.type": getErrorType(error),
+				traceId,
+				spanId
+			});
+		} catch {}
+		return;
+	}
 	try {
 		span.addEvent("defjs.otel.hook.error", {
 			"hook.name": hookName,
@@ -120,11 +132,7 @@ function addSpanEvent(span, eventName, attributes) {
 function toError(error) {
 	return error instanceof Error ? error : new Error(String(error));
 }
-function getHttpResponseErrorType(status, error) {
-	if (status === 0) {
-		const errorCode = createTransportError(error).code;
-		return errorCode === "ABORTED" ? void 0 : errorCode;
-	}
+function getHttpResponseErrorType(status) {
 	if (status >= 400) return String(status);
 }
 function getErrorType(error) {
@@ -132,8 +140,7 @@ function getErrorType(error) {
 	if (error === void 0 || error === null) return "_OTHER";
 	return typeof error;
 }
-//#endregion
-//#region src/telemetry/url.ts
+// src/telemetry/url.ts
 function resolveUrl(endpoint, baseEndpoint) {
 	if (!baseEndpoint) return endpoint;
 	try {
@@ -155,8 +162,7 @@ function resolveHttpUrl(endpoint, baseEndpoint) {
 		return { url: endpoint };
 	}
 }
-//#endregion
-//#region src/telemetry/metrics.ts
+// src/telemetry/metrics.ts
 const DURATION_BUCKETS = [
 	.005,
 	.01,
@@ -224,7 +230,7 @@ function createHttpMetricAttributes(req, response, error) {
 		...createServerMetricAttributes(req),
 		"http.request.method": req.method
 	};
-	const errorType = response ? getHttpResponseErrorType(response.status, response.error) : createErrorMetricAttributes(error)["error.type"];
+	const errorType = response ? getHttpResponseErrorType(response.status) : createErrorMetricAttributes(error)["error.type"];
 	if (errorType) attributes["error.type"] = errorType;
 	if (response && response.status !== 0) attributes["http.response.status_code"] = response.status;
 	return attributes;
@@ -248,26 +254,85 @@ function createErrorMetricAttributes(error) {
 	if (error === void 0 || error === null) return {};
 	return { "error.type": getErrorType(error) };
 }
-//#endregion
-//#region src/interceptor/http.ts
+// src/telemetry/logs.ts
+const CLIENT_EXCEPTIONS = {
+	http: {
+		eventName: "http.client.request.exception",
+		body: "HTTP client request failed"
+	},
+	sse: {
+		eventName: "defjs.client.sse.exception",
+		body: "SSE client connection failed"
+	},
+	websocket: {
+		eventName: "defjs.client.websocket.exception",
+		body: "WebSocket client connection failed"
+	}
+};
+/**
+* Caller cancellation produces no log. An abort whose reason is `TimeoutError` or `ERR_TIMEOUT` still logs.
+*
+* `request.abort` alone is not cancellation: WebSocket `finish()` aborts that same signal
+* when a connect fails. Cancellation is an abort sentinel from any `@defjs/core` copy, or an
+* `AbortError`, on the rejection or on `request.abort.reason`. There is no `timeout` option.
+*/
+function isCallerCancellation(request, error) {
+	const reason = request.abort?.reason;
+	if (isTimeoutCause(error) || isTimeoutCause(reason)) return false;
+	return isAbortCause(error) || isAbortCause(reason);
+}
+function emitClientException(logger, details) {
+	if (!logger) return;
+	try {
+		const { error, transport, request } = details;
+		if (isCallerCancellation(request, error)) return;
+		if (error instanceof Error && "code" in error) {
+			if (error.code === "NET_ABORTED" || transport === "http" && error.code === "HTTP_STATUS") return;
+		}
+		const attributes = {
+			...createServerMetricAttributes(request),
+			"defjs.phase": details.phase,
+			"exception.type": getErrorType(error)
+		};
+		if (transport === "http") attributes["http.request.method"] = request.method;
+		const closeCode = details.closeInfo?.code;
+		if (transport === "sse" && typeof closeCode === "string") attributes["defjs.sse.fault.code"] = closeCode;
+		if (transport === "websocket" && typeof closeCode === "number") attributes["websocket.close.code"] = closeCode;
+		logger.emit({
+			...CLIENT_EXCEPTIONS[transport],
+			context: details.context,
+			severityNumber: SeverityNumber.WARN,
+			severityText: "WARN",
+			attributes
+		});
+	} catch {
+		try {
+			diag.error("@defjs/opentelemetry-server: failed to emit client diagnostic log");
+		} catch {}
+	}
+}
+// src/interceptor/http.ts
 function createOpenTelemetryHttpInterceptor(options) {
 	return createHttpInterceptor(async (req, next) => {
-		const { tracer, propagator, metrics, requireParentSpan, startSpanHook, requestHook, responseHook } = options;
-		if (requireParentSpan && !trace.getActiveSpan()) return next(req);
+		const { tracer, logger, propagator, metrics, requireParentSpan, startSpanHook, requestHook, responseHook } = options;
+		if (tracer && requireParentSpan && !trace.getActiveSpan()) return next(req);
 		const parentCtx = propagator.extract(context.active(), req.headers ?? new Headers(), headersGetter);
 		const { url, serverAddress, serverPort } = resolveHttpUrl(req.endpoint, req.baseEndpoint);
-		const startSpanHookResult = resolveStartSpanHook(startSpanHook, req);
-		const span = createHttpSpan(tracer, req.method, url, parentCtx, req.operation, {
-			...serverAddress ? { "server.address": serverAddress } : {},
-			...serverPort ? { "server.port": serverPort } : {},
-			...startSpanHookResult.ok ? startSpanHookResult.attributes : {}
-		});
-		if (!startSpanHookResult.ok) runSpanHook(span, "startSpanHook", () => {
-			throw startSpanHookResult.error;
-		});
-		runSpanHook(span, "requestHook", () => requestHook?.(span, req));
-		const spanCtx = trace.setSpan(parentCtx, span);
-		const headers = req.headers instanceof Headers ? req.headers : new Headers(req.headers);
+		let span;
+		if (tracer) {
+			const startSpanHookResult = resolveStartSpanHook(startSpanHook, req);
+			span = createHttpSpan(tracer, req.method, url, parentCtx, req.operation, {
+				...serverAddress ? { "server.address": serverAddress } : {},
+				...serverPort ? { "server.port": serverPort } : {},
+				...startSpanHookResult.ok ? startSpanHookResult.attributes : {}
+			});
+			if (!startSpanHookResult.ok) runSpanHook(span, "startSpanHook", () => {
+				throw startSpanHookResult.error;
+			});
+		}
+		if (span) runSpanHook(span, "requestHook", () => requestHook?.(span, req));
+		const spanCtx = span ? trace.setSpan(parentCtx, span) : parentCtx;
+		const headers = new Headers(req.headers);
 		propagator.inject(spanCtx, headers, headersSetter);
 		const startTime = performance.now();
 		try {
@@ -276,35 +341,46 @@ function createOpenTelemetryHttpInterceptor(options) {
 				headers
 			});
 			const durationS = durationSeconds(startTime);
-			runSpanHook(span, "responseHook", () => responseHook?.(span, response, req));
-			setSpanHttpResponse(span, response.status, response.error);
+			if (span) {
+				runSpanHook(span, "responseHook", () => responseHook?.(span, response, req));
+				setSpanHttpResponse(span, response.status);
+			}
 			metrics?.requestDuration.record(durationS, createHttpMetricAttributes(req, response));
 			return response;
 		} catch (error) {
 			const durationS = durationSeconds(startTime);
-			setSpanError(span, error);
+			emitClientException(logger, {
+				request: req,
+				context: spanCtx,
+				error,
+				transport: "http",
+				phase: "request"
+			});
+			if (span) setSpanError(span, error);
 			metrics?.requestDuration.record(durationS, createHttpMetricAttributes(req, void 0, error));
 			throw error;
 		}
 	});
 }
-//#endregion
-//#region src/interceptor/sse.ts
+// src/interceptor/sse.ts
 function createOpenTelemetrySSEInterceptor(options) {
 	return createSSEInterceptor(async (req, next) => {
-		const { tracer, propagator, metrics, requireParentSpan, startSpanHook, requestHook, responseHook } = options;
-		if (requireParentSpan && !trace.getActiveSpan()) return next(req);
+		const { tracer, logger, propagator, metrics, requireParentSpan, startSpanHook, requestHook, responseHook } = options;
+		if (tracer && requireParentSpan && !trace.getActiveSpan()) return next(req);
 		const parentCtx = propagator.extract(context.active(), req.headers ?? new Headers(), headersGetter);
 		const url = resolveUrl(req.endpoint, req.baseEndpoint);
-		const startSpanHookResult = resolveStartSpanHook(startSpanHook, req);
-		const span = createSSESpan(tracer, url, parentCtx, req.operation, startSpanHookResult.ok ? startSpanHookResult.attributes : void 0);
-		if (!startSpanHookResult.ok) runSpanHook(span, "startSpanHook", () => {
-			throw startSpanHookResult.error;
-		});
-		const spanCtx = trace.setSpan(parentCtx, span);
-		const headers = req.headers instanceof Headers ? req.headers : new Headers(req.headers);
+		let span;
+		if (tracer) {
+			const startSpanHookResult = resolveStartSpanHook(startSpanHook, req);
+			span = createSSESpan(tracer, url, parentCtx, req.operation, startSpanHookResult.ok ? startSpanHookResult.attributes : void 0);
+			if (!startSpanHookResult.ok) runSpanHook(span, "startSpanHook", () => {
+				throw startSpanHookResult.error;
+			});
+		}
+		const spanCtx = span ? trace.setSpan(parentCtx, span) : parentCtx;
+		if (span) runSpanHook(span, "requestHook", () => requestHook?.(span, req));
+		const headers = new Headers(req.headers);
 		propagator.inject(spanCtx, headers, headersSetter);
-		runSpanHook(span, "requestHook", () => requestHook?.(span, req));
 		const connectStartMs = performance.now();
 		try {
 			const stream = await next({
@@ -313,8 +389,10 @@ function createOpenTelemetrySSEInterceptor(options) {
 			});
 			const connectedAtMs = performance.now();
 			const activeAttributes = createServerMetricAttributes(req);
-			runSpanHook(span, "responseHook", () => responseHook?.(span, stream, req));
-			addSpanEvent(span, "sse.connected");
+			if (span) {
+				runSpanHook(span, "responseHook", () => responseHook?.(span, stream, req));
+				addSpanEvent(span, "sse.connected");
+			}
 			metrics?.connectDuration.record(durationSeconds(connectStartMs, connectedAtMs), createConnectionMetricAttributes(req, "success"));
 			metrics?.activeStreams.add(1, activeAttributes);
 			const closeActiveStream = () => {
@@ -323,59 +401,82 @@ function createOpenTelemetrySSEInterceptor(options) {
 			stream.closed.then((closeInfo) => {
 				closeActiveStream();
 				const closeAttributes = {
-					"sse.close.code": closeInfo.code,
-					...closeInfo.code === "error" ? { "defjs.sse.error.code": closeInfo.errorCode } : {}
+					"sse.close.kind": closeInfo.kind,
+					...closeInfo.kind === "error" ? { "defjs.sse.fault.code": closeInfo.code } : {}
 				};
-				if (closeInfo.code === "error") {
-					addSpanEvent(span, "sse.error", closeAttributes);
+				if (closeInfo.kind === "error") {
+					emitClientException(logger, {
+						request: req,
+						context: spanCtx,
+						error: closeInfo.cause,
+						transport: "sse",
+						phase: "connection",
+						closeInfo
+					});
+					if (span) addSpanEvent(span, "sse.error", closeAttributes);
 					metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "error", {
 						...closeAttributes,
 						...createErrorMetricAttributes(closeInfo.cause)
 					}));
-					setSpanError(span, closeInfo.cause);
+					if (span) setSpanError(span, closeInfo.cause);
 					return;
 				}
-				addSpanEvent(span, closeInfo.code === "aborted" ? "sse.aborted" : "sse.closed", closeAttributes);
+				if (span) addSpanEvent(span, closeInfo.kind === "aborted" ? "sse.aborted" : "sse.closed", closeAttributes);
 				metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "success", closeAttributes));
-				endSpan(span);
+				if (span) endSpan(span);
 			}, (error) => {
 				closeActiveStream();
-				addSpanEvent(span, "sse.error", createErrorMetricAttributes(error));
+				emitClientException(logger, {
+					request: req,
+					context: spanCtx,
+					error,
+					transport: "sse",
+					phase: "connection"
+				});
+				if (span) addSpanEvent(span, "sse.error", createErrorMetricAttributes(error));
 				metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
-				setSpanError(span, error);
+				if (span) setSpanError(span, error);
 			});
 			return stream;
 		} catch (error) {
+			emitClientException(logger, {
+				request: req,
+				context: spanCtx,
+				error,
+				transport: "sse",
+				phase: "connect"
+			});
 			metrics?.connectDuration.record(durationSeconds(connectStartMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
-			setSpanError(span, error);
+			if (span) setSpanError(span, error);
 			throw error;
 		}
 	});
 }
-//#endregion
-//#region src/interceptor/web_socket.ts
+// src/interceptor/web_socket.ts
 function createOpenTelemetryWebSocketInterceptor(options) {
 	return createWebSocketInterceptor(async (req, next) => {
-		const { tracer, propagator, metrics, requireParentSpan, queryPropagation = false, startSpanHook, requestHook, responseHook } = options;
-		if (requireParentSpan && !trace.getActiveSpan()) return next(req);
+		const { tracer, logger, propagator, metrics, requireParentSpan, queryPropagation = false, startSpanHook, requestHook, responseHook } = options;
+		if (tracer && requireParentSpan && !trace.getActiveSpan()) return next(req);
 		const url = resolveUrl(req.endpoint, req.baseEndpoint);
 		const parentCtx = propagator.extract(context.active(), req.headers ?? new Headers(), headersGetter);
-		const startSpanHookResult = resolveStartSpanHook(startSpanHook, req);
-		const span = createWebSocketSpan(tracer, url, parentCtx, req.operation, startSpanHookResult.ok ? startSpanHookResult.attributes : void 0);
-		if (!startSpanHookResult.ok) runSpanHook(span, "startSpanHook", () => {
-			throw startSpanHookResult.error;
-		});
-		const spanCtx = trace.setSpan(parentCtx, span);
+		let span;
+		if (tracer) {
+			const startSpanHookResult = resolveStartSpanHook(startSpanHook, req);
+			span = createWebSocketSpan(tracer, url, parentCtx, req.operation, startSpanHookResult.ok ? startSpanHookResult.attributes : void 0);
+			if (!startSpanHookResult.ok) runSpanHook(span, "startSpanHook", () => {
+				throw startSpanHookResult.error;
+			});
+		}
+		const spanCtx = span ? trace.setSpan(parentCtx, span) : parentCtx;
 		let queryParams = req.queryParams;
 		let queryString = req.queryString;
 		if (queryPropagation) {
-			const originalParams = new URLSearchParams(queryParams);
-			const carrier = { params: new URLSearchParams(queryParams) };
+			const carrier = { params: new URLSearchParams() };
 			propagator.inject(spanCtx, carrier, queryStringSetter);
-			queryParams = carrier.params;
-			queryString = appendInjectedQueryString(queryString, originalParams, carrier.params);
+			queryString = replaceInjectedPairs(queryString ?? new URLSearchParams(queryParams).toString(), carrier.params);
+			queryParams = new URLSearchParams(queryString);
 		}
-		runSpanHook(span, "requestHook", () => requestHook?.(span, req));
+		if (span) runSpanHook(span, "requestHook", () => requestHook?.(span, req));
 		const connectStartMs = performance.now();
 		try {
 			const session = await next({
@@ -385,8 +486,10 @@ function createOpenTelemetryWebSocketInterceptor(options) {
 			});
 			const connectedAtMs = performance.now();
 			const activeAttributes = createServerMetricAttributes(req);
-			runSpanHook(span, "responseHook", () => responseHook?.(span, session, req));
-			addSpanEvent(span, "websocket.connected");
+			if (span) {
+				runSpanHook(span, "responseHook", () => responseHook?.(span, session, req));
+				addSpanEvent(span, "websocket.connected");
+			}
 			metrics?.connectDuration.record(durationSeconds(connectStartMs, connectedAtMs), createConnectionMetricAttributes(req, "success"));
 			metrics?.activeConnections.add(1, activeAttributes);
 			const closeActiveConnection = () => {
@@ -399,63 +502,88 @@ function createOpenTelemetryWebSocketInterceptor(options) {
 				const closeCause = runtimeCloseInfo.cause;
 				if (typeof closeKind === "string" ? closeKind !== "closed" : typeof closeCause !== "undefined") {
 					const error = typeof closeKind === "string" ? closeKind === "error" ? closeCause : closeCause ?? ERR_ABORTED : closeCause;
-					addSpanEvent(span, "websocket.error", createErrorMetricAttributes(error));
+					if (closeKind !== "aborted") emitClientException(logger, {
+						request: req,
+						context: spanCtx,
+						error,
+						transport: "websocket",
+						phase: "connection",
+						closeInfo: runtimeCloseInfo
+					});
+					if (span) addSpanEvent(span, "websocket.error", createErrorMetricAttributes(error));
 					metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
-					setSpanError(span, error);
+					if (span) setSpanError(span, error);
 					return;
 				}
-				addSpanEvent(span, "websocket.closed");
+				if (span) addSpanEvent(span, "websocket.closed");
 				metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "success"));
-				endSpan(span);
+				if (span) endSpan(span);
 			}, (error) => {
 				closeActiveConnection();
-				addSpanEvent(span, "websocket.error", createErrorMetricAttributes(error));
+				emitClientException(logger, {
+					request: req,
+					context: spanCtx,
+					error,
+					transport: "websocket",
+					phase: "connection"
+				});
+				if (span) addSpanEvent(span, "websocket.error", createErrorMetricAttributes(error));
 				metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
-				setSpanError(span, error);
+				if (span) setSpanError(span, error);
 			});
 			return session;
 		} catch (error) {
+			emitClientException(logger, {
+				request: req,
+				context: spanCtx,
+				error,
+				transport: "websocket",
+				phase: "connect"
+			});
 			metrics?.connectDuration.record(durationSeconds(connectStartMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
-			setSpanError(span, error);
+			if (span) setSpanError(span, error);
 			throw error;
 		}
 	});
 }
-function appendInjectedQueryString(queryString, originalParams, nextParams) {
-	const injectedParams = new URLSearchParams();
-	nextParams.forEach((value, key) => {
-		if (originalParams.getAll(key).includes(value)) return;
-		injectedParams.append(key, value);
-	});
-	const injectedQueryString = injectedParams.toString();
-	if (!injectedQueryString) return queryString ?? "";
-	if (!queryString) return injectedQueryString;
-	return `${queryString}&${injectedQueryString}`;
+/**
+* Put the injected pairs last and drop earlier pairs of the same name, so a receiver reading the first value gets the injected one.
+* Every other pair keeps the bytes it was serialized with.
+*/
+function replaceInjectedPairs(queryString, injected) {
+	const added = injected.toString();
+	if (!added) return queryString;
+	const prefixed = queryString.startsWith("?");
+	const query = prefixed ? queryString.slice(1) : queryString;
+	const combined = [...query ? query.split("&").filter((pair) => !injected.has(new URLSearchParams(`&${pair}`).keys().next().value ?? "")) : [], added].join("&");
+	return prefixed || combined.startsWith("?") ? `?${combined}` : combined;
 }
-//#endregion
-//#region src/option.ts
+// src/option.ts
 /**
 * Client option that installs outbound OpenTelemetry interceptors for HTTP, SSE, and WebSocket.
 *
-* Does not initialize the OpenTelemetry SDK — supply a `tracer` (and optional `meter`) from your app.
-* Each transport can be toggled or customized via `http`, `sse`, and `webSocket`.
+* Appends one interceptor per enabled transport, in the order HTTP, SSE, WebSocket. Apply it at `createClient` time. It does not initialize the OpenTelemetry SDK or acquire global tracer, meter, or logger handles: pass the ones your application owns. Each transport can be toggled or customized via `http`, `sse`, and `webSocket`.
+*
+* `options` is required. It carries `tracer`, `meter`, `logger`, `propagator`, `requireParentSpan`, and the `http` / `sse` / `webSocket` transport options. Pass `{}` to install the interceptors with propagation only.
+*
+* Each of `tracer`, `meter` and `logger` is optional and works without the others. Without `tracer`, the plugin creates no local spans, never calls `trace.getTracer(...)`, and skips `startSpanHook`, `requestHook` and `responseHook`. Propagation still forwards the extracted parent context.
+*
+* HTTP, SSE, and WebSocket are on by default. Pass `{ enabled: false }` on a transport to skip it.
 *
-* @param options - Tracer, optional meter/propagator, and per-transport settings.
+* @param options - Required settings object. Each of `tracer`, `meter`, `logger`, and `propagator` may be omitted; pass `{}` for propagation only.
 * @returns A `ClientOption` for `createClient(...)`.
 *
-* @example
-* ```ts
-* const client = createClient(
-*   withEndpoint('https://api.example.com'),
-*   withOpenTelemetryServer({ tracer }),
-* )
-* ```
+* @group opentelemetry-server
+* @see {@link ClientOption}
+* @see {@link OpenTelemetryServerOptions}
+* @exampleFile examples/api/with-opentelemetry-server.ts#example
 */
 function withOpenTelemetryServer(options) {
-	const { tracer, meter, propagator = new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()] }), requireParentSpan = false } = options;
+	const { tracer, meter, logger, propagator = new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()] }), requireParentSpan = false } = options;
 	return (config) => {
 		if (isTransportEnabled(options.http)) config.interceptors.push(createOpenTelemetryHttpInterceptor({
 			tracer,
+			logger,
 			propagator,
 			metrics: meter ? createHttpClientMetrics(meter) : void 0,
 			requireParentSpan,
@@ -465,6 +593,7 @@ function withOpenTelemetryServer(options) {
 		}));
 		if (isTransportEnabled(options.sse)) config.interceptors.push(createOpenTelemetrySSEInterceptor({
 			tracer,
+			logger,
 			propagator,
 			metrics: meter ? createSSEClientMetrics(meter) : void 0,
 			requireParentSpan,
@@ -474,6 +603,7 @@ function withOpenTelemetryServer(options) {
 		}));
 		if (isTransportEnabled(options.webSocket)) config.interceptors.push(createOpenTelemetryWebSocketInterceptor({
 			tracer,
+			logger,
 			propagator,
 			metrics: meter ? createWebSocketClientMetrics(meter) : void 0,
 			requireParentSpan,
@@ -487,5 +617,4 @@ function withOpenTelemetryServer(options) {
 function isTransportEnabled(option) {
 	return option?.enabled !== false;
 }
-//#endregion
 export { withOpenTelemetryServer };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@defjs/opentelemetry-server",
-  "version": "0.0.1-beta.0",
+  "version": "0.0.2",
+  "description": "Append OpenTelemetry interceptors to an application-owned Defjs client.",
   "bugs": {
     "url": "https://github.com/defjs/defjs/issues"
   },
@@ -12,10 +13,13 @@
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
+  "dependencies": {
+    "@opentelemetry/api-logs": "^0.223.0"
+  },
   "peerDependencies": {
-    "@defjs/core": "0.4.0-beta.0",
+    "@defjs/core": "^0.5.0",
     "@opentelemetry/api": "^1.0.0",
-    "@opentelemetry/core": "^2.0.0"
+    "@opentelemetry/core": "^2.0.0 || ^3.0.0"
   },
   "module": "./index.js",
   "typings": "./index.d.ts",