hono-webhooks 0.3.0 → 0.4.0

package/README.md

@@ -545,63 +545,47 @@ createWebhooks(webhooks, {
 })
 ```
 
-### OpenTelemetry metrics
+### OpenTelemetry
 
-```ts
-import { metrics } from '@opentelemetry/api'
-
-const duration = metrics.getMeter('webhooks').createHistogram('webhook.duration', { unit: 'ms' })
+`hono-webhooks/otel` puts each request in a server span and records two
+metrics. It needs `@opentelemetry/api` (an optional peer dependency):
 
-createWebhooks(webhooks, {
-	onEvent: (e) =>
-		duration.record(e.durationMs, {
-			'http.route': e.route ?? 'unmatched',
-			'http.request.method': e.method,
-			'http.response.status_code': e.status
-		})
-})
+```bash
+bun add @opentelemetry/api
 ```
 
-### OpenTelemetry traces
-
-One span per request, named by the route pattern (low cardinality), with
-`onEvent` logs attached to it:
-
 ```ts
-import { SpanKind, SpanStatusCode, trace } from '@opentelemetry/api'
-
-const tracer = trace.getTracer('webhooks')
+import { otelWebhooks } from 'hono-webhooks/otel'
 
 createWebhooks(webhooks, {
-	around: ({ c, route, method }, next) =>
-		tracer.startActiveSpan(
-			`webhook ${method} ${route ?? 'unmatched'}`,
-			{
-				kind: SpanKind.SERVER,
-				attributes: {
-					'http.request.method': method,
-					'http.route': route ?? 'unmatched',
-					'url.path': c.req.path
-				}
-			},
-			async (span) => {
-				try {
-					const res = await next()
-					span.setAttribute('http.response.status_code', res.status)
-					if (res.status >= 500) span.setStatus({ code: SpanStatusCode.ERROR })
-					return res
-				} finally {
-					span.end()
-				}
-			}
-		),
-	onEvent: (e) => {
-		// trace.getActiveSpan() is the span above
-		if (e.error instanceof Error) trace.getActiveSpan()?.recordException(e.error)
-	}
+	...otelWebhooks({
+		ignoreRoutes: ['/health'],
+		onWebhookCall(call, event) {
+			// `call` is summarizeEvent(event); the request's span is active here
+			logger.info('webhook.completed', { route: call.route, status: call.status })
+		}
+	}),
+	// onWebhookCall logs errors with the route and span
+	logErrors: false
 })
 ```
 
+- **Span** `webhook: POST /orders/:id` (kind `SERVER`) with `http.method`,
+  `http.route`, `http.status_code`, `webhook.duration_ms`, `webhook.success`
+  and, for validation failures, `webhook.validation_error`. Status is `ERROR`
+  for 4xx and 5xx; 5xx errors are recorded as exceptions. Spans created in
+  handlers nest under it when an OTel context manager is registered.
+- **Metrics** `webhook_request_total` (counter) and
+  `webhook_request_duration_ms` (histogram, ms), both by `route` (the pattern,
+  `__unmatched__` for a 404) and `status` (`success` below 400, else `failed`).
+- `ignoreRoutes` skips metrics only; the span and `onWebhookCall` still run.
+- `tracer` and `meter` default to `trace.getTracer('webhooks')` and
+  `metrics.getMeter('webhooks')`. The meter is resolved on the first request,
+  so registering the SDK after import works.
+
+It returns `{ around, onEvent }`. To add your own, call them from yours, or
+use `onWebhookCall` instead of `onEvent`.
+
 ### Skipping noise
 
 `onEvent` fires for everything, so filter in the hook:
@@ -771,6 +755,11 @@ import {
 	hmac // (options) => a scheme like the ones above
 } from 'hono-webhooks/signatures'
 
+import {
+	otelWebhooks, // (options?) => { around, onEvent } with spans and metrics
+	UNMATCHED_ROUTE // '__unmatched__', the route label for 404s
+} from 'hono-webhooks/otel'
+
 import type {
 	Webhook,
 	WebhookConfig,
@@ -791,6 +780,8 @@ import type {
 	PathParams,
 	StandardSchemaV1
 } from 'hono-webhooks'
+
+import type { OtelWebhooksOptions } from 'hono-webhooks/otel'
 ```
 
 Use `Webhook` to type a list: `const all: Webhook<AppEnv>[] = [a, b]`.

package/dist/otel.d.ts

@@ -0,0 +1,31 @@
+import { type Meter, type Tracer } from '@opentelemetry/api';
+import type { Env } from 'hono';
+import { type WebhookEvent, type WebhookEventSummary, type WebhooksOptions } from 'hono-webhooks';
+/** The `route` label for 404s, which match no webhook. */
+export declare const UNMATCHED_ROUTE = "__unmatched__";
+export interface OtelWebhooksOptions<E extends Env = any> {
+    /** @default trace.getTracer('webhooks') */
+    tracer?: Tracer;
+    /** @default metrics.getMeter('webhooks'), resolved on the first request */
+    meter?: Meter;
+    /** Routes that get a span but no metrics, e.g. `['/health']`. */
+    ignoreRoutes?: readonly string[];
+    /**
+     * Called after every request, ignored routes included, with the span
+     * still active: log it, store it. A returned promise is handled like
+     * `onEvent`'s.
+     */
+    onWebhookCall?: (call: WebhookEventSummary, event: WebhookEvent<E>) => void | Promise<void>;
+}
+/**
+ * `around` and `onEvent` that put each request in a server span and record
+ * `webhook_request_total` and `webhook_request_duration_ms` by route and
+ * outcome.
+ *
+ * With `createWebhookFactory<AppEnv>()`, call `otelWebhooks<AppEnv>(...)`
+ * so `onWebhookCall` gets a typed context.
+ *
+ * @example
+ * createWebhooks(webhooks, { ...otelWebhooks({ ignoreRoutes: ['/health'] }), logErrors: false })
+ */
+export declare function otelWebhooks<E extends Env = any>(options?: OtelWebhooksOptions<E>): Required<Pick<WebhooksOptions<E>, 'around' | 'onEvent'>>;

package/dist/otel.js

@@ -0,0 +1,77 @@
+// src/otel.ts
+import {
+  metrics,
+  SpanKind,
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+import {
+  summarizeEvent
+} from "hono-webhooks";
+var UNMATCHED_ROUTE = "__unmatched__";
+function otelWebhooks(options = {}) {
+  const tracer = options.tracer ?? trace.getTracer("webhooks");
+  const ignored = new Set(options.ignoreRoutes);
+  const spans = new WeakMap;
+  let instruments;
+  return {
+    around: ({ c, route, method }, next) => {
+      const label = route ?? UNMATCHED_ROUTE;
+      return tracer.startActiveSpan(`webhook: ${method} ${label}`, {
+        kind: SpanKind.SERVER,
+        attributes: { "http.method": method, "http.route": label }
+      }, async (span) => {
+        spans.set(c, span);
+        try {
+          return await next();
+        } finally {
+          span.end();
+        }
+      });
+    },
+    onEvent: (event) => {
+      const call = summarizeEvent(event);
+      const success = call.status < 400;
+      const span = spans.get(event.c);
+      span?.setAttributes({
+        "http.status_code": call.status,
+        "webhook.duration_ms": call.durationMs,
+        "webhook.success": success
+      });
+      if (call.validation) {
+        span?.setAttribute("webhook.validation_error", call.validation.message);
+      }
+      if (event.error instanceof Error && call.status >= 500) {
+        span?.recordException(event.error);
+      }
+      span?.setStatus({
+        code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR
+      });
+      if (call.route === null || !ignored.has(call.route)) {
+        instruments ??= createInstruments(options.meter ?? metrics.getMeter("webhooks"));
+        const attributes = {
+          route: call.route ?? UNMATCHED_ROUTE,
+          status: success ? "success" : "failed"
+        };
+        instruments.total.add(1, attributes);
+        instruments.duration.record(event.durationMs, attributes);
+      }
+      return options.onWebhookCall?.(call, event);
+    }
+  };
+}
+function createInstruments(meter) {
+  return {
+    total: meter.createCounter("webhook_request_total", {
+      description: "HTTP webhook requests by route template and status"
+    }),
+    duration: meter.createHistogram("webhook_request_duration_ms", {
+      unit: "ms",
+      description: "HTTP webhook handler duration by route template and status"
+    })
+  };
+}
+export {
+  UNMATCHED_ROUTE,
+  otelWebhooks
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-webhooks",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Type-safe webhook routes for Hono, validated with any Standard Schema library (Zod, Valibot, ArkType)",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,8 @@
     "valibot",
     "arktype",
     "typescript",
-    "type-safe"
+    "type-safe",
+    "opentelemetry"
   ],
   "files": [
     "src/**/*.ts",
@@ -48,11 +49,17 @@
       "bun": "./src/signatures.ts",
       "import": "./dist/signatures.js",
       "default": "./dist/signatures.js"
+    },
+    "./otel": {
+      "types": "./dist/otel.d.ts",
+      "bun": "./src/otel.ts",
+      "import": "./dist/otel.js",
+      "default": "./dist/otel.js"
     }
   },
   "scripts": {
     "build": "rm -rf dist && bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/signatures.ts ./src/cli.ts --outdir ./dist --target node --packages external",
+    "build:js": "bun build ./src/index.ts ./src/signatures.ts ./src/otel.ts ./src/cli.ts --outdir ./dist --target node --packages external",
     "build:types": "tsgo -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "test": "bun test",
@@ -65,10 +72,19 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "peerDependencies": {
-    "hono": "^4.8.0"
+    "hono": "^4.8.0",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-metrics": "^2.12.0",
+    "@opentelemetry/sdk-trace-base": "^2.12.0",
     "@types/bun": "^1.4.2",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
     "hono": "^4.13.10",

package/src/otel.ts

@@ -0,0 +1,127 @@
+import {
+	type Meter,
+	metrics,
+	type Span,
+	SpanKind,
+	SpanStatusCode,
+	type Tracer,
+	trace
+} from '@opentelemetry/api'
+import type { Context, Env } from 'hono'
+import {
+	summarizeEvent,
+	type WebhookEvent,
+	type WebhookEventSummary,
+	type WebhooksOptions
+} from 'hono-webhooks'
+
+/** The `route` label for 404s, which match no webhook. */
+export const UNMATCHED_ROUTE = '__unmatched__'
+
+export interface OtelWebhooksOptions<E extends Env = any> {
+	/** @default trace.getTracer('webhooks') */
+	tracer?: Tracer
+	/** @default metrics.getMeter('webhooks'), resolved on the first request */
+	meter?: Meter
+	/** Routes that get a span but no metrics, e.g. `['/health']`. */
+	ignoreRoutes?: readonly string[]
+	/**
+	 * Called after every request, ignored routes included, with the span
+	 * still active: log it, store it. A returned promise is handled like
+	 * `onEvent`'s.
+	 */
+	onWebhookCall?: (
+		call: WebhookEventSummary,
+		event: WebhookEvent<E>
+	) => void | Promise<void>
+}
+
+/**
+ * `around` and `onEvent` that put each request in a server span and record
+ * `webhook_request_total` and `webhook_request_duration_ms` by route and
+ * outcome.
+ *
+ * With `createWebhookFactory<AppEnv>()`, call `otelWebhooks<AppEnv>(...)`
+ * so `onWebhookCall` gets a typed context.
+ *
+ * @example
+ * createWebhooks(webhooks, { ...otelWebhooks({ ignoreRoutes: ['/health'] }), logErrors: false })
+ */
+export function otelWebhooks<E extends Env = any>(
+	options: OtelWebhooksOptions<E> = {}
+): Required<Pick<WebhooksOptions<E>, 'around' | 'onEvent'>> {
+	const tracer = options.tracer ?? trace.getTracer('webhooks')
+	const ignored = new Set(options.ignoreRoutes)
+	// The span is looked up by context, so it is found even without an OTel
+	// context manager.
+	const spans = new WeakMap<Context, Span>()
+	let instruments: ReturnType<typeof createInstruments> | undefined
+
+	return {
+		around: ({ c, route, method }, next) => {
+			const label = route ?? UNMATCHED_ROUTE
+			return tracer.startActiveSpan(
+				`webhook: ${method} ${label}`,
+				{
+					kind: SpanKind.SERVER,
+					attributes: { 'http.method': method, 'http.route': label }
+				},
+				async (span) => {
+					spans.set(c, span)
+					try {
+						return await next()
+					} finally {
+						span.end()
+					}
+				}
+			)
+		},
+		onEvent: (event) => {
+			const call = summarizeEvent(event)
+			const success = call.status < 400
+
+			const span = spans.get(event.c)
+			span?.setAttributes({
+				'http.status_code': call.status,
+				'webhook.duration_ms': call.durationMs,
+				'webhook.success': success
+			})
+			if (call.validation) {
+				span?.setAttribute('webhook.validation_error', call.validation.message)
+			}
+			if (event.error instanceof Error && call.status >= 500) {
+				span?.recordException(event.error)
+			}
+			span?.setStatus({
+				code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR
+			})
+
+			if (call.route === null || !ignored.has(call.route)) {
+				// Created lazily so a meter provider registered after import still applies.
+				instruments ??= createInstruments(
+					options.meter ?? metrics.getMeter('webhooks')
+				)
+				const attributes = {
+					route: call.route ?? UNMATCHED_ROUTE,
+					status: success ? 'success' : 'failed'
+				}
+				instruments.total.add(1, attributes)
+				instruments.duration.record(event.durationMs, attributes)
+			}
+
+			return options.onWebhookCall?.(call, event)
+		}
+	}
+}
+
+function createInstruments(meter: Meter) {
+	return {
+		total: meter.createCounter('webhook_request_total', {
+			description: 'HTTP webhook requests by route template and status'
+		}),
+		duration: meter.createHistogram('webhook_request_duration_ms', {
+			unit: 'ms',
+			description: 'HTTP webhook handler duration by route template and status'
+		})
+	}
+}