@defjs/opentelemetry-server 0.0.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MunMunMiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# @defjs/opentelemetry-server
+
+Server-side outbound OpenTelemetry integration for `@defjs/core` HTTP, SSE, and WebSocket clients.
+
+**Core Positioning**:
+
+- **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:
+
+```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.
+
+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.
+
+## 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:
+
+```typescript
+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 client = createClient(
+  withEndpoint('https://api.example.com'),
+  withOpenTelemetryServer({
+    tracer,
+  }),
+)
+```
+
+## Operation Identity
+
+Set the optional `operation` field statically on `defineRequest(...)`, `defineEventStream(...)`, or `defineWebSocket(...)`:
+
+```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`.
+
+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.
+
+## 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
+    },
+  }),
+)
+```
+
+## WebSocket propagation safety
+
+`webSocket.queryPropagation` defaults to `false`. Omitting it leaves the WebSocket query string unchanged and does not inject trace context or baggage into the URL.
+
+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,
+  },
+})
+```
+
+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`.
+
+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'
+
+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()
+  }
+})
+```
+
+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:
+
+- `websocket.connected` — Session successfully established
+- `websocket.closed` — Connection normal close
+- `websocket.error` — Connection error
+
+### Custom Metrics
+
+When `meter` is provided, the following defjs custom metrics are collected:
+
+| 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                |
+
+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.
+
+## What's Next
+
+- [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

package/index.d.ts

@@ -0,0 +1,65 @@
+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. */
+interface OpenTelemetryServerTransportOptions<TResponse> {
+  /** Whether this transport's instrumentation is enabled. Defaults to `true`. */
+  enabled?: boolean;
+  /** Add application attributes when the client span is created. */
+  startSpanHook?: (request: HttpRequest) => Attributes;
+  /** Customize the client span before the request is sent. */
+  requestHook?: (span: Span, req: HttpRequest) => Promise<void> | void;
+  /** Customize the client span after the transport result is returned. */
+  responseHook?: (span: Span, res: TResponse, req: HttpRequest) => Promise<void> | void;
+}
+type OpenTelemetryServerHttpOptions = OpenTelemetryServerTransportOptions<HttpResponse<unknown>>;
+type OpenTelemetryServerSSEOptions = OpenTelemetryServerTransportOptions<EventStreamHandle<unknown>>;
+interface OpenTelemetryServerWebSocketOptions extends OpenTelemetryServerTransportOptions<WebSocketSessionLike> {
+  /**
+   * Inject trace context into the WebSocket URL query string.
+   * Defaults to `false`; enable only after reviewing URL propagation exposure.
+   */
+  queryPropagation?: boolean;
+}
+/**
+ * Options for {@link withOpenTelemetryServer}.
+ *
+ * Pass an application-owned OpenTelemetry `Tracer` (and optional `Meter`).
+ * This package does not initialize the OpenTelemetry SDK.
+ */
+interface OpenTelemetryServerOptions {
+  /** OpenTelemetry tracer used for outbound client spans. */
+  tracer: Tracer;
+  /** Optional meter; when set, per-transport client metrics are recorded. */
+  meter?: Meter;
+  /** Context propagator. Defaults to W3C Trace Context + Baggage. */
+  propagator?: TextMapPropagator;
+  /** When `true`, only create an outgoing span if an active parent span exists. */
+  requireParentSpan?: boolean;
+  /** HTTP transport instrumentation options. */
+  http?: OpenTelemetryServerHttpOptions;
+  /** SSE transport instrumentation options. */
+  sse?: OpenTelemetryServerSSEOptions;
+  /** WebSocket transport instrumentation options. */
+  webSocket?: OpenTelemetryServerWebSocketOptions;
+}
+/**
+ * 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`.
+ *
+ * @param options - Tracer, optional meter/propagator, and per-transport settings.
+ * @returns A `ClientOption` for `createClient(...)`.
+ *
+ * @example
+ * ```ts
+ * const client = createClient(
+ *   withEndpoint('https://api.example.com'),
+ *   withOpenTelemetryServer({ tracer }),
+ * )
+ * ```
+ */
+export declare function withOpenTelemetryServer(options: OpenTelemetryServerOptions): ClientOption;
+//#endregion
+export type { OpenTelemetryServerHttpOptions, OpenTelemetryServerOptions, OpenTelemetryServerSSEOptions, OpenTelemetryServerTransportOptions, OpenTelemetryServerWebSocketOptions };

package/index.js

@@ -0,0 +1,491 @@
+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
+const headersSetter = { set(carrier, key, value) {
+	if (carrier && key && value !== void 0) carrier.set(key, String(value));
+} };
+const headersGetter = {
+	keys(carrier) {
+		if (!carrier) return [];
+		return Array.from(carrier.keys());
+	},
+	get(carrier, key) {
+		if (!carrier || !key) return;
+		return carrier.get(key) ?? void 0;
+	}
+};
+const queryStringSetter = { set(carrier, key, value) {
+	if (carrier && key && value !== void 0) carrier.params.append(key, String(value));
+} };
+//#endregion
+//#region src/telemetry/trace.ts
+const spanStatusSet = /* @__PURE__ */ new WeakMap();
+function markSpanStatusSet(span) {
+	spanStatusSet.set(span, true);
+}
+function resolveStartSpanHook(hook, request) {
+	if (!hook) return { ok: true };
+	try {
+		return {
+			ok: true,
+			attributes: hook(request)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+function createHttpSpan(tracer, method, url, parentCtx, operation, startAttributes) {
+	return tracer.startSpan(operation ? `${method} ${operation}` : method, {
+		kind: SpanKind.CLIENT,
+		attributes: {
+			...operation ? { "defjs.operation": operation } : {},
+			"http.request.method": method,
+			"url.full": url,
+			...startAttributes
+		}
+	}, parentCtx);
+}
+function createSSESpan(tracer, url, parentCtx, operation, startAttributes) {
+	return tracer.startSpan(operation ? `SSE ${operation}` : "SSE", {
+		kind: SpanKind.CLIENT,
+		attributes: {
+			...operation ? { "defjs.operation": operation } : {},
+			"url.full": url,
+			...startAttributes
+		}
+	}, parentCtx);
+}
+function createWebSocketSpan(tracer, url, parentCtx, operation, startAttributes) {
+	return tracer.startSpan(operation ? `WebSocket ${operation}` : "WebSocket", {
+		kind: SpanKind.CLIENT,
+		attributes: {
+			...operation ? { "defjs.operation": operation } : {},
+			"url.full": url,
+			...startAttributes
+		}
+	}, parentCtx);
+}
+function setSpanHttpResponse(span, status, error) {
+	if (status !== 0) span.setAttribute("http.response.status_code", status);
+	const errorType = getHttpResponseErrorType(status, error);
+	if (errorType) {
+		span.setAttribute("error.type", errorType);
+		span.setStatus({ code: SpanStatusCode.ERROR });
+	}
+	markSpanStatusSet(span);
+	span.end();
+}
+function setSpanError(span, error) {
+	span.recordException(toError(error));
+	span.setAttribute("error.type", getErrorType(error));
+	span.setStatus({ code: SpanStatusCode.ERROR });
+	markSpanStatusSet(span);
+	span.end();
+}
+function endSpan(span) {
+	if (!spanStatusSet.has(span)) span.setStatus({ code: SpanStatusCode.OK });
+	span.end();
+}
+function runSpanHook(span, hookName, hook) {
+	if (!hook) return;
+	try {
+		const result = hook();
+		Promise.resolve(result).catch((error) => recordSpanHookError(span, hookName, error));
+	} catch (error) {
+		recordSpanHookError(span, hookName, error);
+	}
+}
+function recordSpanHookError(span, hookName, error) {
+	try {
+		span.addEvent("defjs.otel.hook.error", {
+			"hook.name": hookName,
+			"error.type": getErrorType(error)
+		});
+	} catch {}
+	try {
+		span.recordException(toError(error));
+	} catch {}
+}
+function addSpanEvent(span, eventName, attributes) {
+	if (attributes) {
+		span.addEvent(eventName, attributes);
+		return;
+	}
+	span.addEvent(eventName);
+}
+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;
+	}
+	if (status >= 400) return String(status);
+}
+function getErrorType(error) {
+	if (error instanceof Error) return error.name || "Error";
+	if (error === void 0 || error === null) return "_OTHER";
+	return typeof error;
+}
+//#endregion
+//#region src/telemetry/url.ts
+function resolveUrl(endpoint, baseEndpoint) {
+	if (!baseEndpoint) return endpoint;
+	try {
+		return createResolvedRequestUrl(baseEndpoint, endpoint).toString();
+	} catch {
+		return endpoint;
+	}
+}
+function resolveHttpUrl(endpoint, baseEndpoint) {
+	if (!baseEndpoint) return { url: endpoint };
+	try {
+		const parsed = createResolvedRequestUrl(baseEndpoint, endpoint);
+		return {
+			url: parsed.toString(),
+			serverAddress: parsed.hostname,
+			serverPort: Number.parseInt(parsed.port) || void 0
+		};
+	} catch {
+		return { url: endpoint };
+	}
+}
+//#endregion
+//#region src/telemetry/metrics.ts
+const DURATION_BUCKETS = [
+	.005,
+	.01,
+	.025,
+	.05,
+	.075,
+	.1,
+	.25,
+	.5,
+	.75,
+	1,
+	2.5,
+	5,
+	7.5,
+	10
+];
+function createHttpClientMetrics(meter) {
+	return { requestDuration: meter.createHistogram("http.client.request.duration", {
+		description: "Duration of HTTP client requests",
+		unit: "s",
+		advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+	}) };
+}
+function createSSEClientMetrics(meter) {
+	return {
+		connectDuration: meter.createHistogram("defjs.client.sse.connect.duration", {
+			description: "Duration of SSE connection attempts",
+			unit: "s",
+			advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+		}),
+		connectionDuration: meter.createHistogram("defjs.client.sse.connection.duration", {
+			description: "Duration of SSE stream connections",
+			unit: "s",
+			advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+		}),
+		activeStreams: meter.createUpDownCounter("defjs.client.sse.active_streams", {
+			description: "Number of active SSE streams",
+			unit: "{stream}"
+		})
+	};
+}
+function createWebSocketClientMetrics(meter) {
+	return {
+		connectDuration: meter.createHistogram("defjs.client.websocket.connect.duration", {
+			description: "Duration of WebSocket connection attempts",
+			unit: "s",
+			advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+		}),
+		connectionDuration: meter.createHistogram("defjs.client.websocket.connection.duration", {
+			description: "Duration of WebSocket connections",
+			unit: "s",
+			advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+		}),
+		activeConnections: meter.createUpDownCounter("defjs.client.websocket.active_connections", {
+			description: "Number of active WebSocket connections",
+			unit: "{connection}"
+		})
+	};
+}
+function durationSeconds(startMs, endMs = performance.now()) {
+	return (endMs - startMs) / 1e3;
+}
+function createHttpMetricAttributes(req, response, error) {
+	const attributes = {
+		...createServerMetricAttributes(req),
+		"http.request.method": req.method
+	};
+	const errorType = response ? getHttpResponseErrorType(response.status, response.error) : createErrorMetricAttributes(error)["error.type"];
+	if (errorType) attributes["error.type"] = errorType;
+	if (response && response.status !== 0) attributes["http.response.status_code"] = response.status;
+	return attributes;
+}
+function createConnectionMetricAttributes(req, result, extras) {
+	return {
+		...createServerMetricAttributes(req),
+		"defjs.result": result,
+		...extras
+	};
+}
+function createServerMetricAttributes(req) {
+	const { serverAddress, serverPort } = resolveHttpUrl(req.endpoint, req.baseEndpoint);
+	const attributes = {};
+	if (req.operation) attributes["defjs.operation"] = req.operation;
+	if (serverAddress) attributes["server.address"] = serverAddress;
+	if (serverPort) attributes["server.port"] = serverPort;
+	return attributes;
+}
+function createErrorMetricAttributes(error) {
+	if (error === void 0 || error === null) return {};
+	return { "error.type": getErrorType(error) };
+}
+//#endregion
+//#region 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 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);
+		propagator.inject(spanCtx, headers, headersSetter);
+		const startTime = performance.now();
+		try {
+			const response = await next({
+				...req,
+				headers
+			});
+			const durationS = durationSeconds(startTime);
+			runSpanHook(span, "responseHook", () => responseHook?.(span, response, req));
+			setSpanHttpResponse(span, response.status, response.error);
+			metrics?.requestDuration.record(durationS, createHttpMetricAttributes(req, response));
+			return response;
+		} catch (error) {
+			const durationS = durationSeconds(startTime);
+			setSpanError(span, error);
+			metrics?.requestDuration.record(durationS, createHttpMetricAttributes(req, void 0, error));
+			throw error;
+		}
+	});
+}
+//#endregion
+//#region 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 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);
+		propagator.inject(spanCtx, headers, headersSetter);
+		runSpanHook(span, "requestHook", () => requestHook?.(span, req));
+		const connectStartMs = performance.now();
+		try {
+			const stream = await next({
+				...req,
+				headers
+			});
+			const connectedAtMs = performance.now();
+			const activeAttributes = createServerMetricAttributes(req);
+			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 = () => {
+				metrics?.activeStreams.add(-1, activeAttributes);
+			};
+			stream.closed.then((closeInfo) => {
+				closeActiveStream();
+				const closeAttributes = {
+					"sse.close.code": closeInfo.code,
+					...closeInfo.code === "error" ? { "defjs.sse.error.code": closeInfo.errorCode } : {}
+				};
+				if (closeInfo.code === "error") {
+					addSpanEvent(span, "sse.error", closeAttributes);
+					metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "error", {
+						...closeAttributes,
+						...createErrorMetricAttributes(closeInfo.cause)
+					}));
+					setSpanError(span, closeInfo.cause);
+					return;
+				}
+				addSpanEvent(span, closeInfo.code === "aborted" ? "sse.aborted" : "sse.closed", closeAttributes);
+				metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "success", closeAttributes));
+				endSpan(span);
+			}, (error) => {
+				closeActiveStream();
+				addSpanEvent(span, "sse.error", createErrorMetricAttributes(error));
+				metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
+				setSpanError(span, error);
+			});
+			return stream;
+		} catch (error) {
+			metrics?.connectDuration.record(durationSeconds(connectStartMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
+			setSpanError(span, error);
+			throw error;
+		}
+	});
+}
+//#endregion
+//#region 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 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 queryParams = req.queryParams;
+		let queryString = req.queryString;
+		if (queryPropagation) {
+			const originalParams = new URLSearchParams(queryParams);
+			const carrier = { params: new URLSearchParams(queryParams) };
+			propagator.inject(spanCtx, carrier, queryStringSetter);
+			queryParams = carrier.params;
+			queryString = appendInjectedQueryString(queryString, originalParams, carrier.params);
+		}
+		runSpanHook(span, "requestHook", () => requestHook?.(span, req));
+		const connectStartMs = performance.now();
+		try {
+			const session = await next({
+				...req,
+				queryParams,
+				queryString
+			});
+			const connectedAtMs = performance.now();
+			const activeAttributes = createServerMetricAttributes(req);
+			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 = () => {
+				metrics?.activeConnections.add(-1, activeAttributes);
+			};
+			session.closed.then((closeInfo) => {
+				closeActiveConnection();
+				const runtimeCloseInfo = typeof closeInfo === "object" && closeInfo !== null ? closeInfo : {};
+				const closeKind = runtimeCloseInfo.kind;
+				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));
+					metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
+					setSpanError(span, error);
+					return;
+				}
+				addSpanEvent(span, "websocket.closed");
+				metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "success"));
+				endSpan(span);
+			}, (error) => {
+				closeActiveConnection();
+				addSpanEvent(span, "websocket.error", createErrorMetricAttributes(error));
+				metrics?.connectionDuration.record(durationSeconds(connectedAtMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
+				setSpanError(span, error);
+			});
+			return session;
+		} catch (error) {
+			metrics?.connectDuration.record(durationSeconds(connectStartMs), createConnectionMetricAttributes(req, "error", createErrorMetricAttributes(error)));
+			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}`;
+}
+//#endregion
+//#region 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`.
+*
+* @param options - Tracer, optional meter/propagator, and per-transport settings.
+* @returns A `ClientOption` for `createClient(...)`.
+*
+* @example
+* ```ts
+* const client = createClient(
+*   withEndpoint('https://api.example.com'),
+*   withOpenTelemetryServer({ tracer }),
+* )
+* ```
+*/
+function withOpenTelemetryServer(options) {
+	const { tracer, meter, propagator = new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()] }), requireParentSpan = false } = options;
+	return (config) => {
+		if (isTransportEnabled(options.http)) config.interceptors.push(createOpenTelemetryHttpInterceptor({
+			tracer,
+			propagator,
+			metrics: meter ? createHttpClientMetrics(meter) : void 0,
+			requireParentSpan,
+			startSpanHook: options.http?.startSpanHook,
+			requestHook: options.http?.requestHook,
+			responseHook: options.http?.responseHook
+		}));
+		if (isTransportEnabled(options.sse)) config.interceptors.push(createOpenTelemetrySSEInterceptor({
+			tracer,
+			propagator,
+			metrics: meter ? createSSEClientMetrics(meter) : void 0,
+			requireParentSpan,
+			startSpanHook: options.sse?.startSpanHook,
+			requestHook: options.sse?.requestHook,
+			responseHook: options.sse?.responseHook
+		}));
+		if (isTransportEnabled(options.webSocket)) config.interceptors.push(createOpenTelemetryWebSocketInterceptor({
+			tracer,
+			propagator,
+			metrics: meter ? createWebSocketClientMetrics(meter) : void 0,
+			requireParentSpan,
+			queryPropagation: options.webSocket?.queryPropagation,
+			startSpanHook: options.webSocket?.startSpanHook,
+			requestHook: options.webSocket?.requestHook,
+			responseHook: options.webSocket?.responseHook
+		}));
+	};
+}
+function isTransportEnabled(option) {
+	return option?.enabled !== false;
+}
+//#endregion
+export { withOpenTelemetryServer };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@defjs/opentelemetry-server",
+  "version": "0.0.1-beta.0",
+  "bugs": {
+    "url": "https://github.com/defjs/defjs/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/defjs/defjs.git"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "peerDependencies": {
+    "@defjs/core": "0.4.0-beta.0",
+    "@opentelemetry/api": "^1.0.0",
+    "@opentelemetry/core": "^2.0.0"
+  },
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  }
+}