hono-webhooks 0.4.1 → 0.5.0

package/README.md

@@ -560,12 +560,15 @@ import { otelWebhooks } from 'hono-webhooks/otel'
 createWebhooks(webhooks, {
 	...otelWebhooks({
 		ignoreRoutes: ['/health'],
+		// one `webhook.completed` log per request, with the request's span
+		logger: (span) => createLogger({ span }),
 		onWebhookCall(call, event) {
-			// `call` is summarizeEvent(event); the request's span is active here
-			logger.info('webhook.completed', { route: call.route, status: call.status })
+			// `call` is summarizeEvent(event) plus `level` and `outcome`;
+			// the request's span is active here
+			storeCall(call)
 		}
 	}),
-	// onWebhookCall logs errors with the route and span
+	// the completion log carries the error type
 	logErrors: false
 })
 ```
@@ -578,7 +581,23 @@ createWebhooks(webhooks, {
 - **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.
+- **Log** `webhook.completed`, when `logger` is set, at `error` for 5xx,
+  `warn` for 4xx and `info` otherwise, with `route`, `method`, `status_code`,
+  `duration_ms`, `status` (`success`, `failed` or `validation_failed`) and
+  `error_type`. `logger` gets the request's span and returns anything with
+  `info`, `warn` and `error` methods taking `(message, fields)`, so
+  `logger: () => console` works. 404s and `ignoreRoutes` are not logged.
+- `ignoreRoutes` skips metrics and the log; the span and `onWebhookCall` still
+  run.
+- `webhookMetrics` describes both metrics (`name`, `kind`, `unit`,
+  `description` and `attributes`, where each attribute maps to its values or
+  `'string'`), so a metric catalog can list them:
+
+  ```ts
+  import { webhookMetrics } from 'hono-webhooks/otel'
+
+  export const otelMetrics = [...appMetrics, ...webhookMetrics]
+  ```
 - `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.
@@ -757,6 +776,7 @@ import {
 
 import {
 	otelWebhooks, // (options?) => { around, onEvent } with spans and metrics
+	webhookMetrics, // the two metric definitions, as data
 	UNMATCHED_ROUTE // '__unmatched__', the route label for 404s
 } from 'hono-webhooks/otel'
 
@@ -781,7 +801,12 @@ import type {
 	StandardSchemaV1
 } from 'hono-webhooks'
 
-import type { OtelWebhooksOptions } from 'hono-webhooks/otel'
+import type {
+	OtelWebhooksOptions,
+	WebhookCall,
+	WebhookLogger,
+	WebhookMetricDefinition
+} from 'hono-webhooks/otel'
 ```
 
 Use `Webhook` to type a list: `const all: Webhook<AppEnv>[] = [a, b]`.

package/dist/otel.d.ts

@@ -1,8 +1,47 @@
-import { type Meter, type Tracer } from '@opentelemetry/api';
+import { type Meter, type Span, 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__";
+/** A metric `otelWebhooks` records, described for a metric catalog. */
+export interface WebhookMetricDefinition {
+    name: string;
+    kind: 'counter' | 'histogram';
+    unit?: string;
+    description: string;
+    /** Attribute key to its closed set of values, or `'string'` when open. */
+    attributes: Record<string, readonly string[] | 'string'>;
+}
+/**
+ * The metrics `otelWebhooks` records, as data: list them in a metric
+ * catalog without creating a second recorder.
+ */
+export declare const webhookMetrics: readonly [{
+    readonly name: 'webhook_request_total';
+    readonly kind: 'counter';
+    readonly description: 'HTTP webhook requests by route template and status';
+    readonly attributes: {
+        readonly route: 'string';
+        readonly status: readonly ['success', 'failed'];
+    };
+}, {
+    readonly name: 'webhook_request_duration_ms';
+    readonly kind: 'histogram';
+    readonly unit: 'ms';
+    readonly description: 'HTTP webhook handler duration by route template and status';
+    readonly attributes: {
+        readonly route: 'string';
+        readonly status: readonly ['success', 'failed'];
+    };
+}];
+/** `summarizeEvent(event)` plus what a completion log needs. */
+export interface WebhookCall extends WebhookEventSummary {
+    /** `error` for 5xx, `warn` for 4xx, else `info`. */
+    level: 'info' | 'warn' | 'error';
+    outcome: 'success' | 'failed' | 'validation_failed';
+}
+/** `console` fits, as does any logger with these three methods. */
+export type WebhookLogger = Record<WebhookCall['level'], (message: string, fields: Record<string, string | number>) => void>;
 export interface OtelWebhooksOptions<E extends Env = any> {
     /** @default trace.getTracer('webhooks') */
     tracer?: Tracer;
@@ -15,7 +54,17 @@ export interface OtelWebhooksOptions<E extends Env = any> {
      * still active: log it, store it. A returned promise is handled like
      * `onEvent`'s.
      */
-    onWebhookCall?: (call: WebhookEventSummary, event: WebhookEvent<E>) => void | Promise<void>;
+    onWebhookCall?: (call: WebhookCall, event: WebhookEvent<E>) => void | Promise<void>;
+    /**
+     * Logs one `webhook.completed` event per request at `call.level`, with
+     * `route`, `method`, `status_code`, `duration_ms`, `status` (the outcome)
+     * and `error_type`. 404s and `ignoreRoutes` are skipped. Called with the
+     * request's span, so the logger can attach to it.
+     *
+     * @example
+     * logger: () => console
+     */
+    logger?: (span: Span) => WebhookLogger;
 }
 /**
  * `around` and `onEvent` that put each request in a server span and record

package/dist/otel.js

@@ -9,6 +9,25 @@ import {
   summarizeEvent
 } from "hono-webhooks";
 var UNMATCHED_ROUTE = "__unmatched__";
+var metricAttributes = {
+  route: "string",
+  status: ["success", "failed"]
+};
+var webhookMetrics = [
+  {
+    name: "webhook_request_total",
+    kind: "counter",
+    description: "HTTP webhook requests by route template and status",
+    attributes: metricAttributes
+  },
+  {
+    name: "webhook_request_duration_ms",
+    kind: "histogram",
+    unit: "ms",
+    description: "HTTP webhook handler duration by route template and status",
+    attributes: metricAttributes
+  }
+];
 function otelWebhooks(options = {}) {
   const tracer = options.tracer ?? trace.getTracer("webhooks");
   const ignored = new Set(options.ignoreRoutes);
@@ -30,8 +49,13 @@ function otelWebhooks(options = {}) {
       });
     },
     onEvent: (event) => {
-      const call = summarizeEvent(event);
-      const success = call.status < 400;
+      const summary = summarizeEvent(event);
+      const success = summary.status < 400;
+      const call = {
+        ...summary,
+        level: summary.status >= 500 ? "error" : success ? "info" : "warn",
+        outcome: summary.validation ? "validation_failed" : success ? "success" : "failed"
+      };
       const span = spans.get(event.c);
       span?.setAttributes({
         "http.status_code": call.status,
@@ -47,7 +71,8 @@ function otelWebhooks(options = {}) {
       span?.setStatus({
         code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR
       });
-      if (call.route === null || !ignored.has(call.route)) {
+      const isIgnored = call.route !== null && ignored.has(call.route);
+      if (!isIgnored) {
         instruments ??= createInstruments(options.meter ?? metrics.getMeter("webhooks"));
         const attributes = {
           route: call.route ?? UNMATCHED_ROUTE,
@@ -56,22 +81,35 @@ function otelWebhooks(options = {}) {
         instruments.total.add(1, attributes);
         instruments.duration.record(event.durationMs, attributes);
       }
+      if (span && options.logger && call.route !== null && !isIgnored) {
+        options.logger(span)[call.level]("webhook.completed", {
+          event: "webhook.completed",
+          route: call.route,
+          method: call.method,
+          status_code: call.status,
+          duration_ms: call.durationMs,
+          status: call.outcome,
+          ...call.error && { error_type: call.error.name }
+        });
+      }
       return options.onWebhookCall?.(call, event);
     }
   };
 }
 function createInstruments(meter) {
+  const [total, duration] = webhookMetrics;
   return {
-    total: meter.createCounter("webhook_request_total", {
-      description: "HTTP webhook requests by route template and status"
+    total: meter.createCounter(total.name, {
+      description: total.description
     }),
-    duration: meter.createHistogram("webhook_request_duration_ms", {
-      unit: "ms",
-      description: "HTTP webhook handler duration by route template and status"
+    duration: meter.createHistogram(duration.name, {
+      unit: duration.unit,
+      description: duration.description
     })
   };
 }
 export {
   UNMATCHED_ROUTE,
-  otelWebhooks
+  otelWebhooks,
+  webhookMetrics
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-webhooks",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Type-safe webhook routes for Hono, validated with any Standard Schema library (Zod, Valibot, ArkType)",
   "type": "module",
   "main": "./dist/index.js",

package/src/otel.ts

@@ -18,6 +18,54 @@ import {
 /** The `route` label for 404s, which match no webhook. */
 export const UNMATCHED_ROUTE = '__unmatched__'
 
+/** A metric `otelWebhooks` records, described for a metric catalog. */
+export interface WebhookMetricDefinition {
+	name: string
+	kind: 'counter' | 'histogram'
+	unit?: string
+	description: string
+	/** Attribute key to its closed set of values, or `'string'` when open. */
+	attributes: Record<string, readonly string[] | 'string'>
+}
+
+const metricAttributes = {
+	route: 'string',
+	status: ['success', 'failed']
+} as const
+
+/**
+ * The metrics `otelWebhooks` records, as data: list them in a metric
+ * catalog without creating a second recorder.
+ */
+export const webhookMetrics = [
+	{
+		name: 'webhook_request_total',
+		kind: 'counter',
+		description: 'HTTP webhook requests by route template and status',
+		attributes: metricAttributes
+	},
+	{
+		name: 'webhook_request_duration_ms',
+		kind: 'histogram',
+		unit: 'ms',
+		description: 'HTTP webhook handler duration by route template and status',
+		attributes: metricAttributes
+	}
+] as const satisfies readonly WebhookMetricDefinition[]
+
+/** `summarizeEvent(event)` plus what a completion log needs. */
+export interface WebhookCall extends WebhookEventSummary {
+	/** `error` for 5xx, `warn` for 4xx, else `info`. */
+	level: 'info' | 'warn' | 'error'
+	outcome: 'success' | 'failed' | 'validation_failed'
+}
+
+/** `console` fits, as does any logger with these three methods. */
+export type WebhookLogger = Record<
+	WebhookCall['level'],
+	(message: string, fields: Record<string, string | number>) => void
+>
+
 export interface OtelWebhooksOptions<E extends Env = any> {
 	/** @default trace.getTracer('webhooks') */
 	tracer?: Tracer
@@ -31,9 +79,19 @@ export interface OtelWebhooksOptions<E extends Env = any> {
 	 * `onEvent`'s.
 	 */
 	onWebhookCall?: (
-		call: WebhookEventSummary,
+		call: WebhookCall,
 		event: WebhookEvent<E>
 	) => void | Promise<void>
+	/**
+	 * Logs one `webhook.completed` event per request at `call.level`, with
+	 * `route`, `method`, `status_code`, `duration_ms`, `status` (the outcome)
+	 * and `error_type`. 404s and `ignoreRoutes` are skipped. Called with the
+	 * request's span, so the logger can attach to it.
+	 *
+	 * @example
+	 * logger: () => console
+	 */
+	logger?: (span: Span) => WebhookLogger
 }
 
 /**
@@ -77,8 +135,17 @@ export function otelWebhooks<E extends Env = any>(
 			)
 		},
 		onEvent: (event) => {
-			const call = summarizeEvent(event)
-			const success = call.status < 400
+			const summary = summarizeEvent(event)
+			const success = summary.status < 400
+			const call: WebhookCall = {
+				...summary,
+				level: summary.status >= 500 ? 'error' : success ? 'info' : 'warn',
+				outcome: summary.validation
+					? 'validation_failed'
+					: success
+						? 'success'
+						: 'failed'
+			}
 
 			const span = spans.get(event.c)
 			span?.setAttributes({
@@ -96,7 +163,8 @@ export function otelWebhooks<E extends Env = any>(
 				code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR
 			})
 
-			if (call.route === null || !ignored.has(call.route)) {
+			const isIgnored = call.route !== null && ignored.has(call.route)
+			if (!isIgnored) {
 				// Created lazily so a meter provider registered after import still applies.
 				instruments ??= createInstruments(
 					options.meter ?? metrics.getMeter('webhooks')
@@ -109,19 +177,32 @@ export function otelWebhooks<E extends Env = any>(
 				instruments.duration.record(event.durationMs, attributes)
 			}
 
+			if (span && options.logger && call.route !== null && !isIgnored) {
+				options.logger(span)[call.level]('webhook.completed', {
+					event: 'webhook.completed',
+					route: call.route,
+					method: call.method,
+					status_code: call.status,
+					duration_ms: call.durationMs,
+					status: call.outcome,
+					...(call.error && { error_type: call.error.name })
+				})
+			}
+
 			return options.onWebhookCall?.(call, event)
 		}
 	}
 }
 
 function createInstruments(meter: Meter) {
+	const [total, duration] = webhookMetrics
 	return {
-		total: meter.createCounter('webhook_request_total', {
-			description: 'HTTP webhook requests by route template and status'
+		total: meter.createCounter(total.name, {
+			description: total.description
 		}),
-		duration: meter.createHistogram('webhook_request_duration_ms', {
-			unit: 'ms',
-			description: 'HTTP webhook handler duration by route template and status'
+		duration: meter.createHistogram(duration.name, {
+			unit: duration.unit,
+			description: duration.description
 		})
 	}
 }