@unireq/otel 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Olivier Orabona
+
+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/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { Tracer } from '@opentelemetry/api';
+import { RequestContext, Policy } from '@unireq/core';
+
+/**
+ * OpenTelemetry tracing policy for unireq
+ *
+ * Creates spans for HTTP requests following OpenTelemetry semantic conventions.
+ * Propagates trace context via W3C Trace Context headers.
+ */
+
+/**
+ * Function to format span names
+ */
+type SpanNameFormatter = (ctx: RequestContext) => string;
+/**
+ * Configuration options for OpenTelemetry tracing
+ */
+interface OtelOptions {
+    /**
+     * OpenTelemetry tracer instance
+     */
+    readonly tracer: Tracer;
+    /**
+     * Custom span name formatter
+     * @default (ctx) => `HTTP ${ctx.method}`
+     */
+    readonly spanNameFormatter?: SpanNameFormatter;
+    /**
+     * Record request body size in span attributes
+     * @default false
+     */
+    readonly recordRequestBodySize?: boolean;
+    /**
+     * Record response body size in span attributes
+     * @default false
+     */
+    readonly recordResponseBodySize?: boolean;
+    /**
+     * Custom attributes to add to every span
+     */
+    readonly customAttributes?: Record<string, string | number | boolean>;
+    /**
+     * Propagate trace context to downstream services
+     * @default true
+     */
+    readonly propagateContext?: boolean;
+}
+/**
+ * Create an OpenTelemetry tracing policy
+ *
+ * @example
+ * ```typescript
+ * import { client } from '@unireq/core';
+ * import { http } from '@unireq/http';
+ * import { otel } from '@unireq/otel';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * const tracer = trace.getTracer('my-service', '1.0.0');
+ *
+ * const api = client(
+ *   http('https://api.example.com'),
+ *   otel({
+ *     tracer,
+ *     spanNameFormatter: (ctx) => `${ctx.method} ${new URL(ctx.url).pathname}`,
+ *     customAttributes: { 'service.version': '1.0.0' },
+ *   }),
+ *   parse.json()
+ * );
+ * ```
+ */
+declare function otel(options: OtelOptions): Policy;
+
+export { type OtelOptions, type SpanNameFormatter, otel };

package/dist/index.js

@@ -0,0 +1,2 @@
+var g="http.request.method",A="url.full",O="http.response.status_code",C="server.address",b="server.port",R="error.type",x="http.request.body.size",P="http.response.body.size",N=e=>`HTTP ${e.method}`;function q(e){try{let s=new URL(e),a=s.protocol==="https:"?443:80,i=s.port?Number.parseInt(s.port,10):a;return {host:s.hostname,port:i,protocol:s.protocol.replace(":","")}}catch{return {host:"unknown",port:void 0,protocol:"http"}}}function T(e){if(e){if(typeof e=="string")return new TextEncoder().encode(e).length;if(e instanceof ArrayBuffer)return e.byteLength;if(e instanceof Uint8Array)return e.length;if(typeof e=="object")try{return new TextEncoder().encode(JSON.stringify(e)).length}catch{return}}}function w(e){let{tracer:s,spanNameFormatter:a=N,recordRequestBodySize:i=false,recordResponseBodySize:m=false,customAttributes:S={},propagateContext:y=true}=e,n,p,c;return async(o,u)=>{if(!n)try{n=await import('@opentelemetry/api'),p=n.context,c=n.propagation;}catch{return u(o)}let{host:E,port:d}=q(o.url),h=a(o),r=s.startSpan(h,{kind:n.SpanKind.CLIENT,attributes:{[g]:o.method,[A]:o.url,[C]:E,...d!==void 0&&{[b]:d},...S}});if(i&&o.body){let t=T(o.body);t!==void 0&&r.setAttribute(x,t);}let f={...o.headers};if(y&&c&&p){let t=p.active();c.inject(n.trace.setSpan(t,r),f);}let _={...o,headers:f};try{let t=await u(_);if(r.setAttribute(O,t.status),m&&t.data){let l=T(t.data);l!==void 0&&r.setAttribute(P,l);}return t.status>=400?(r.setStatus({code:n.SpanStatusCode.ERROR,message:`HTTP ${t.status} ${t.statusText}`}),r.setAttribute(R,`${t.status}`)):r.setStatus({code:n.SpanStatusCode.OK}),t}catch(t){throw r.setStatus({code:n.SpanStatusCode.ERROR,message:t instanceof Error?t.message:"Unknown error"}),t instanceof Error&&(r.recordException(t),r.setAttribute(R,t.name)),t}finally{r.end();}}}export{w as otel};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tracing.ts"],"names":["ATTR_HTTP_REQUEST_METHOD","ATTR_URL_FULL","ATTR_HTTP_RESPONSE_STATUS_CODE","ATTR_SERVER_ADDRESS","ATTR_SERVER_PORT","ATTR_ERROR_TYPE","ATTR_HTTP_REQUEST_BODY_SIZE","ATTR_HTTP_RESPONSE_BODY_SIZE","defaultSpanNameFormatter","ctx","parseUrl","url","parsed","defaultPort","port","calculateBodySize","body","otel","options","tracer","spanNameFormatter","recordRequestBodySize","recordResponseBodySize","customAttributes","propagateContext","api","contextApi","propagation","next","host","spanName","span","size","headers","activeContext","enrichedCtx","response","error"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * OpenTelemetry tracing policy for unireq\n *\n * Creates spans for HTTP requests following OpenTelemetry semantic conventions.\n * Propagates trace context via W3C Trace Context headers.\n */\n\nimport type { Context, Tracer } from '@opentelemetry/api';\nimport type { Policy, RequestContext, Response } from '@unireq/core';\n\n// Use stable semantic convention attribute names (as of 1.28.0)\n// These are the stable HTTP client span attribute names per OpenTelemetry spec\nconst ATTR_HTTP_REQUEST_METHOD = 'http.request.method';\nconst ATTR_URL_FULL = 'url.full';\nconst ATTR_HTTP_RESPONSE_STATUS_CODE = 'http.response.status_code';\nconst ATTR_SERVER_ADDRESS = 'server.address';\nconst ATTR_SERVER_PORT = 'server.port';\nconst ATTR_ERROR_TYPE = 'error.type';\nconst ATTR_HTTP_REQUEST_BODY_SIZE = 'http.request.body.size';\nconst ATTR_HTTP_RESPONSE_BODY_SIZE = 'http.response.body.size';\n\n/**\n * Function to format span names\n */\nexport type SpanNameFormatter = (ctx: RequestContext) => string;\n\n/**\n * Configuration options for OpenTelemetry tracing\n */\nexport interface OtelOptions {\n  /**\n   * OpenTelemetry tracer instance\n   */\n  readonly tracer: Tracer;\n\n  /**\n   * Custom span name formatter\n   * @default (ctx) => `HTTP ${ctx.method}`\n   */\n  readonly spanNameFormatter?: SpanNameFormatter;\n\n  /**\n   * Record request body size in span attributes\n   * @default false\n   */\n  readonly recordRequestBodySize?: boolean;\n\n  /**\n   * Record response body size in span attributes\n   * @default false\n   */\n  readonly recordResponseBodySize?: boolean;\n\n  /**\n   * Custom attributes to add to every span\n   */\n  readonly customAttributes?: Record<string, string | number | boolean>;\n\n  /**\n   * Propagate trace context to downstream services\n   * @default true\n   */\n  readonly propagateContext?: boolean;\n}\n\n/**\n * Default span name formatter\n */\nconst defaultSpanNameFormatter: SpanNameFormatter = (ctx) => `HTTP ${ctx.method}`;\n\n/**\n * Parse URL to extract host and port\n */\nfunction parseUrl(url: string): { host: string; port: number | undefined; protocol: string } {\n  try {\n    const parsed = new URL(url);\n    const defaultPort = parsed.protocol === 'https:' ? 443 : 80;\n    const port = parsed.port ? Number.parseInt(parsed.port, 10) : defaultPort;\n    return {\n      host: parsed.hostname,\n      port,\n      protocol: parsed.protocol.replace(':', ''),\n    };\n  } catch {\n    return { host: 'unknown', port: undefined, protocol: 'http' };\n  }\n}\n\n/**\n * Calculate body size for various body types\n */\nfunction calculateBodySize(body: unknown): number | undefined {\n  if (!body) return undefined;\n\n  if (typeof body === 'string') {\n    return new TextEncoder().encode(body).length;\n  }\n\n  if (body instanceof ArrayBuffer) {\n    return body.byteLength;\n  }\n\n  if (body instanceof Uint8Array) {\n    return body.length;\n  }\n\n  if (typeof body === 'object') {\n    try {\n      return new TextEncoder().encode(JSON.stringify(body)).length;\n    } catch {\n      return undefined;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Create an OpenTelemetry tracing policy\n *\n * @example\n * ```typescript\n * import { client } from '@unireq/core';\n * import { http } from '@unireq/http';\n * import { otel } from '@unireq/otel';\n * import { trace } from '@opentelemetry/api';\n *\n * const tracer = trace.getTracer('my-service', '1.0.0');\n *\n * const api = client(\n *   http('https://api.example.com'),\n *   otel({\n *     tracer,\n *     spanNameFormatter: (ctx) => `${ctx.method} ${new URL(ctx.url).pathname}`,\n *     customAttributes: { 'service.version': '1.0.0' },\n *   }),\n *   parse.json()\n * );\n * ```\n */\nexport function otel(options: OtelOptions): Policy {\n  const {\n    tracer,\n    spanNameFormatter = defaultSpanNameFormatter,\n    recordRequestBodySize = false,\n    recordResponseBodySize = false,\n    customAttributes = {},\n    propagateContext = true,\n  } = options;\n\n  // Lazy import to avoid issues when OpenTelemetry is not available\n  let api: typeof import('@opentelemetry/api') | undefined;\n  let contextApi: { active: () => Context } | undefined;\n  let propagation: { inject: (context: Context, carrier: Record<string, string>) => void } | undefined;\n\n  return async (ctx: RequestContext, next): Promise<Response> => {\n    // Lazy load OpenTelemetry API\n    if (!api) {\n      try {\n        api = await import('@opentelemetry/api');\n        contextApi = api.context;\n        propagation = api.propagation;\n      } catch {\n        /* c8 ignore next 2 */ // Fallback when @opentelemetry/api is not installed\n        return next(ctx);\n      }\n    }\n\n    const { host, port } = parseUrl(ctx.url);\n    const spanName = spanNameFormatter(ctx);\n\n    // Create span with HTTP client kind\n    const span = tracer.startSpan(spanName, {\n      kind: api.SpanKind.CLIENT,\n      attributes: {\n        [ATTR_HTTP_REQUEST_METHOD]: ctx.method,\n        [ATTR_URL_FULL]: ctx.url,\n        [ATTR_SERVER_ADDRESS]: host,\n        ...(port !== undefined && { [ATTR_SERVER_PORT]: port }),\n        ...customAttributes,\n      },\n    });\n\n    // Record request body size if enabled\n    if (recordRequestBodySize && ctx.body) {\n      const size = calculateBodySize(ctx.body);\n      if (size !== undefined) {\n        span.setAttribute(ATTR_HTTP_REQUEST_BODY_SIZE, size);\n      }\n    }\n\n    // Inject trace context into request headers\n    const headers = { ...ctx.headers };\n    if (propagateContext && propagation && contextApi) {\n      const activeContext = contextApi.active();\n      propagation.inject(api.trace.setSpan(activeContext, span), headers);\n    }\n\n    const enrichedCtx: RequestContext = {\n      ...ctx,\n      headers,\n    };\n\n    try {\n      const response = await next(enrichedCtx);\n\n      // Record response attributes\n      span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.status);\n\n      // Record response body size if enabled\n      if (recordResponseBodySize && response.data) {\n        const size = calculateBodySize(response.data);\n        if (size !== undefined) {\n          span.setAttribute(ATTR_HTTP_RESPONSE_BODY_SIZE, size);\n        }\n      }\n\n      // Set span status based on response\n      if (response.status >= 400) {\n        span.setStatus({\n          code: api.SpanStatusCode.ERROR,\n          message: `HTTP ${response.status} ${response.statusText}`,\n        });\n        span.setAttribute(ATTR_ERROR_TYPE, `${response.status}`);\n      } else {\n        span.setStatus({ code: api.SpanStatusCode.OK });\n      }\n\n      return response;\n    } catch (error) {\n      // Record error\n      span.setStatus({\n        code: api.SpanStatusCode.ERROR,\n        message: error instanceof Error ? error.message : 'Unknown error',\n      });\n\n      if (error instanceof Error) {\n        span.recordException(error);\n        span.setAttribute(ATTR_ERROR_TYPE, error.name);\n      }\n\n      throw error;\n    } finally {\n      span.end();\n    }\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@unireq/otel",
+  "version": "0.0.1",
+  "description": "OpenTelemetry instrumentation for unireq HTTP clients",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "observability",
+    "instrumentation"
+  ],
+  "author": "Olivier Orabona",
+  "license": "MIT",
+  "dependencies": {
+    "@unireq/core": "0.0.1"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "typescript": "^5.9.3",
+    "tsup": "^8.5.1",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oorabona/unireq",
+    "directory": "packages/otel"
+  },
+  "bugs": {
+    "url": "https://github.com/oorabona/unireq/issues"
+  },
+  "homepage": "https://github.com/oorabona/unireq/tree/main/packages/otel",
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}