hono-webhooks 0.4.1 → 0.5.1

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
 		})
 	}
 }