@devopsplaybook.io/otel-utils-fastify 1.3.1 → 1.4.0

package/README.md

@@ -48,6 +48,10 @@ StandardTracerFastifyRegisterHooks(fastify, tracer, logger, {
   ignoreList: ["GET-/api/health"],
   ignoreListPrefix: ["GET-/api/public/"],
   ignoreListSuffix: ["/metrics", "/health"],
+  // Optional: record the http.server.request.duration histogram
+  standardMeter: meter,
+  // Optional: keep span-name cardinality bounded for unmatched routes (404s)
+  // unmatchedRouteSpanName: "method",
 });
 
 // In route handlers, retrieve the current span for manual instrumentation
@@ -81,24 +85,28 @@ fastify.get("/api/files", async (req, res) => {
 
 Registers five Fastify hooks:
 
-| Hook             | Behavior                                                                                                                                                                                                                                                                                                      |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `onRequest`      | Extracts W3C trace context from incoming headers. Creates a `SpanKind.SERVER` span named after the route (`METHOD-<route template>`, path fallback when no route matched) and stores it plus its context in internal `WeakMap`s. Skips OPTIONS requests, paths outside `rootApiPath`, and ignored span names. |
-| `onResponse`     | Sets span status (OK for status <= 299, ERROR otherwise), records `http.response.status_code`, ends the span, and removes it from the `WeakMap`s.                                                                                                                                                             |
-| `onError`        | Sets span status to ERROR, records `error.type` and the exception, and logs the error via `ModuleLogger` with trace context. Non-`Error` throws are normalized to an `Error` first.                                                                                                                           |
-| `onRequestAbort` | Ends the span with ERROR status and `error.type = "client_abort"` when the client aborts the request.                                                                                                                                                                                                         |
-| `onTimeout`      | Ends the span with ERROR status and `error.type = "timeout"` when the connection times out.                                                                                                                                                                                                                   |
+| Hook             | Behavior                                                                                                                                                                                                                                                                                                                                              |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onRequest`      | Extracts W3C trace context from incoming headers. Creates a `SpanKind.SERVER` span named after the route (`METHOD-<route template>`; path or method fallback when no route matched, see `unmatchedRouteSpanName`) and stores it plus its context in internal `WeakMap`s. Skips OPTIONS requests, paths outside `rootApiPath`, and ignored span names. |
+| `onResponse`     | Ends the span: records `http.response.status_code` and sets the span status per the current OTel HTTP semantic conventions for server spans — **unset for 1xx–4xx, ERROR for 5xx** — then ends the span and removes it from the `WeakMap`s. A span on which `onError` already recorded an error keeps its ERROR status.                               |
+| `onError`        | Sets span status to ERROR, records `error.type` and the exception, and logs the error via `ModuleLogger` with trace context: **`warn` (no stack) for client errors** (`statusCode < 500`, e.g. validation 400 or 403), `error` otherwise. Non-`Error` throws are normalized to an `Error` first.                                                      |
+| `onRequestAbort` | Ends the span with ERROR status and `error.type = "client_abort"` when the client aborts the request.                                                                                                                                                                                                                                                 |
+| `onTimeout`      | Ends the span with ERROR status and `error.type = "timeout"` when the connection times out.                                                                                                                                                                                                                                                           |
 
 Registration is idempotent per Fastify instance: a second registration on the same instance is ignored with a warning. Hooks are registered globally and cannot be removed — register them **once**, at the root of the Fastify instance.
 
+Tracing is **fail-open**: a fault in any hook (including a throwing tracer, span or logger) is caught, logged once at warn level through the `ModuleLogger`, and the request continues untraced — instrumentation never fails the request.
+
 **Options:**
 
-| Field              | Type        | Default  | Description                                                                                                                                                                                |
-| ------------------ | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `rootApiPath`      | `string?`   | `"/api"` | Only trace the path itself and paths under `"<rootApiPath>/"` (boundary check: `/apiary` is **not** traced, `/apiary/...` neither). `"/"` traces everything. Trailing slashes are ignored. |
-| `ignoreList`       | `string[]?` | —        | Exact span names to skip. Format: `"METHOD-/route"`, using the route template for parameterized routes (e.g. `"GET-/api/files/_id"`).                                                      |
-| `ignoreListPrefix` | `string[]?` | —        | Skip when span name **starts with** any of these (native `startsWith`).                                                                                                                    |
-| `ignoreListSuffix` | `string[]?` | —        | Skip when span name **ends with** any of these (native `endsWith`).                                                                                                                        |
+| Field                    | Type                  | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------ | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rootApiPath`            | `string?`             | `"/api"` | Only trace the path itself and paths under `"<rootApiPath>/"` (boundary check: `/apiary` is **not** traced, `/apiary/...` neither). `"/"` traces everything. Trailing slashes are ignored.                                                                                                                                                                                                                                                                                                                     |
+| `ignoreList`             | `string[]?`           | —        | Exact span names to skip. Format: `"METHOD-/route"`, using the route template for parameterized routes (e.g. `"GET-/api/files/_id"`).                                                                                                                                                                                                                                                                                                                                                                          |
+| `ignoreListPrefix`       | `string[]?`           | —        | Skip when span name **starts with** any of these (native `startsWith`).                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `ignoreListSuffix`       | `string[]?`           | —        | Skip when span name **ends with** any of these (native `endsWith`).                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `unmatchedRouteSpanName` | `"path" \| "method"?` | `"path"` | Span-name policy for requests that did not match a route (e.g. 404s). `"path"`: sanitized request path — today's behavior; note the unbounded cardinality from scanner/probe traffic and that attacker payloads end up as span names. `"method"`: method only (e.g. `GET`), keeping cardinality bounded (current semconv recommends a low-cardinality name when available); ignore lists then match `"GET"` for unmatched requests. The full path is always kept in `url.path`; matched routes are unaffected. |
+| `standardMeter`          | `StandardMeter?`      | —        | When provided, records the `http.server.request.duration` histogram (seconds) for traced requests. See [Metrics](#metrics-http-server-requestduration) below.                                                                                                                                                                                                                                                                                                                                                  |
 
 All three ignore lists are checked **in order** (exact → prefix → suffix) with **short-circuit evaluation** — as soon as one matches, the remaining checks are skipped for maximum performance.
 
@@ -107,23 +115,40 @@ All three ignore lists are checked **in order** (exact → prefix → suffix) wi
 Span names follow `METHOD-<route>`:
 
 - Matched routes use the **route template**: `GET /api/files/:id` → span name `GET-/api/files/_id`.
-- Unmatched routes (e.g. 404) fall back to the request path: `GET /api/unknown` → `GET-/api/unknown`.
+- Unmatched routes (e.g. 404) fall back to the request path: `GET /api/unknown` → `GET-/api/unknown`, unless `unmatchedRouteSpanName: "method"` is set, in which case the span name is the method only (`GET`).
 - The query string is never part of the span name.
 - Span names are sanitized with the same regex used by `@devopsplaybook.io/otel-utils` (`[^a-zA-Z0-9-_/]` → `_`), so `ignoreList` entries match the exported span name.
 - Spans are created with `SpanKind.SERVER` and the usual synthetic `StandardTracer` attributes (`http.request_method=BACKEND`, synthetic `http.route`) are **not** added — real HTTP attributes are set instead.
 
 Attributes set on each HTTP span:
 
-| Attribute                   | Value                                                                    |
-| --------------------------- | ------------------------------------------------------------------------ |
-| `http.request.method`       | Request method (`GET`, `POST`, ...)                                      |
-| `url.path`                  | Request path, **without** query string                                   |
-| `http.route`                | Route template — only when the request matched a route                   |
-| `http.response.status_code` | Response status code                                                     |
-| `error.type`                | Error name, or `client_abort` / `timeout` for aborted/timed out requests |
+| Attribute                   | Value                                                                                                                                                                                                    |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `http.request.method`       | Request method (`GET`, `POST`, ...)                                                                                                                                                                      |
+| `url.path`                  | Request path, **without** query string                                                                                                                                                                   |
+| `http.route`                | Route template — only when the request matched a route                                                                                                                                                   |
+| `http.response.status_code` | Response status code                                                                                                                                                                                     |
+| `error.type`                | `error.name` when it is not the generic `Error`, otherwise `error.code` (e.g. `FST_ERR_VALIDATION` for Fastify errors), otherwise `Error` — or `client_abort` / `timeout` for aborted/timed out requests |
 
 The query string is not recorded (`url.query` is not set).
 
+### Metrics: `http.server.request.duration`
+
+When a [`StandardMeter`](https://github.com/devopsplaybookio/otel-utils) is passed in `standardMeter`, the hooks record one histogram observation per traced request at span end:
+
+- Name: `http.server.request.duration` (seconds). `StandardMeter` prefixes the service id, so it is exported as `<SERVICE_ID>.http.server.request.duration`.
+- Attributes: `http.request.method`, `http.route` (only when a route matched) and `http.response.status_code` — or `error.type` (`client_abort` / `timeout`) instead of a status code for aborted/timed-out requests.
+- The same `rootApiPath` / ignore-list filtering applies: only traced requests record, and the histogram counts are the traced request counts.
+
+```typescript
+const meter = new StandardMeter(config);
+StandardTracerFastifyRegisterHooks(fastify, tracer, logger, {
+  standardMeter: meter,
+});
+```
+
+When the option is omitted (default), no metrics are recorded.
+
 ### `OTelRequestSpan(req)`
 
 Retrieves the active span for a Fastify request from the internal `WeakMap`.
@@ -166,7 +191,7 @@ fastify.get("/api/files/:id", async (req, res) => {
 
 ### Deprecated: `req.tracerSpanApi`
 
-The span is also assigned to `req.tracerSpanApi` as a deprecated compatibility alias. Use `OTelRequestSpan(req)` instead.
+The span is also assigned to `req.tracerSpanApi` as a deprecated compatibility alias. **Deprecated in favor of `OTelRequestSpan(req)`**: it keeps working for the whole 1.x line and is **planned for removal in 2.0.0**, only after the known consumers (`common-utils`, `kubernetes-web-lightclient`) have migrated to `OTelRequestSpan(req)`. New code must use `OTelRequestSpan(req)`.
 
 ## Architecture
 
@@ -190,7 +215,17 @@ onResponse / onError / onRequestAbort / onTimeout
         └── WeakMap.delete(req)
 ```
 
-The span and context are stored in `WeakMap`s rather than as properties on the request object, avoiding type pollution and allowing natural garbage collection. The `tracerSpanApi` alias is deleted when the span ends (it is a plain property, so it must be removed explicitly).
+The span and context are stored in `WeakMap`s rather than as properties on the request object, avoiding type pollution and allowing natural garbage collection. The `tracerSpanApi` alias is set to `undefined` when the span ends (it is a plain property, so it must be cleaned up explicitly).
+
+## Behavior changes in 1.4.0
+
+- **Span status policy aligns with the current OTel HTTP semantic conventions** (consumer-visible): span status is left **unset for 1xx–4xx** responses (previously OK for ≤ 299 and ERROR for 4xx+) and stays ERROR for 5xx, exceptions, `client_abort` and `timeout`. Status-based dashboards will see fewer ERROR spans (routine 404/4xx traffic no longer counts as server errors) and no more OK statuses.
+- **Client errors are logged at warn level**: `onError` logs errors with `statusCode < 500` via `logger.warn` (no stack), all others via `logger.error` as before — routine validation/auth failures no longer inflate error logs/alerts.
+- **`error.type` is more specific**: `error.name` when not the generic `Error`, otherwise `error.code` (e.g. `FST_ERR_VALIDATION`), otherwise `Error`.
+- **Tracing is fail-open**: a fault in a hook (throwing tracer/span/logger) is caught, logged once at warn level, and the request continues untraced instead of failing with a 500.
+- **Absolute-form request targets** (`GET http://host/api/x HTTP/1.1`) are now traced with the parsed pathname (`url.path=/api/x`); previously they were silently not traced.
+- New opt-in options (defaults preserve previous behavior): `unmatchedRouteSpanName` and `standardMeter`.
+- A span on which `onError` recorded an error is never downgraded by a 2xx response produced by a custom error handler (regression fix).
 
 ## Behavior changes in 1.3.0
 

package/dist/src/StandardTracerFastify.d.ts

@@ -1,4 +1,4 @@
-import { StandardLogger, StandardTracer } from "@devopsplaybook.io/otel-utils";
+import { StandardLogger, StandardMeter, StandardTracer } from "@devopsplaybook.io/otel-utils";
 import { Context } from "@opentelemetry/api";
 import { Span } from "@opentelemetry/sdk-trace-base";
 import { FastifyInstance, FastifyRequest } from "fastify";
@@ -32,6 +32,32 @@ export interface StandardTracerFastifyRegisterHooksOptions {
      * Example: `["/health", "/metrics"]` ignores all methods targeting those paths.
      */
     ignoreListSuffix?: string[];
+    /**
+     * Span-name policy for requests that did not match a route (e.g. 404s).
+     *
+     * - `"path"` (default): span name falls back to the sanitized request path.
+     *   Unbounded span-name cardinality from scanner/probe traffic and attack
+     *   payloads recorded as span names are possible; the current HTTP semantic
+     *   conventions recommend a low-cardinality name when available.
+     * - `"method"`: span name is the request method only (e.g. `GET`), keeping
+     *   cardinality bounded. Note that `ignoreList`/`ignoreListPrefix`/
+     *   `ignoreListSuffix` then match `"GET"` for unmatched requests.
+     *
+     * The full request path is always kept in the `url.path` attribute.
+     * Matched routes are unaffected.
+     */
+    unmatchedRouteSpanName?: "path" | "method";
+    /**
+     * Optional {@link StandardMeter} used to record the
+     * `http.server.request.duration` histogram (in seconds) for traced requests.
+     * Recorded attributes: `http.request.method`, `http.route` (only when a
+     * route matched) and `http.response.status_code` — or `error.type` instead
+     * of a status code for aborted/timed-out requests. Note that
+     * {@link StandardMeter} prefixes the metric name with the service id, so it
+     * is exported as `<SERVICE_ID>.http.server.request.duration`.
+     * When omitted, no metrics are recorded.
+     */
+    standardMeter?: StandardMeter;
 }
 /**
  * Registers Fastify lifecycle hooks that automatically create and manage
@@ -39,12 +65,18 @@ export interface StandardTracerFastifyRegisterHooksOptions {
  *
  * - Extracts incoming W3C trace context from request headers for distributed tracing.
  * - Creates a `SpanKind.SERVER` span named `METHOD-<route>` (route template for
- *   matched routes, e.g. `GET-/api/files/_id` for `/api/files/:id`; path
- *   fallback when no route matched), with `http.request.method`, `url.path`
- *   (path only, no query string) and `http.route` (route template) attributes.
- * - Marks spans as ERROR on 4xx/5xx responses or when exceptions occur.
+ *   matched routes, e.g. `GET-/api/files/_id` for `/api/files/:id`; path or
+ *   method fallback when no route matched, see `unmatchedRouteSpanName`), with
+ *   `http.request.method`, `url.path` (path only, no query string) and
+ *   `http.route` (route template) attributes.
+ * - Sets the span status according to the current HTTP semantic conventions for
+ *   server spans: unset for 1xx-4xx responses, ERROR for 5xx responses and
+ *   exceptions. A span that already recorded an error is never downgraded.
  * - Ends the span on response, handler error, client abort or connection timeout.
- * - Logs errors via the provided {@link StandardLogger} with trace context.
+ * - Logs errors via the provided {@link StandardLogger} with trace context;
+ *   client errors (`statusCode < 500`) are logged at warn level.
+ * - Tracing is fail-open: a fault in any hook is caught, logged once at warn
+ *   level and the request continues untraced.
  * - Skips OPTIONS requests and requests outside the configured `rootApiPath`.
  * - Additional filtering via `ignoreList` (exact), `ignoreListPrefix`, `ignoreListSuffix`
  *   — checked in that order with short-circuit evaluation.

package/dist/src/StandardTracerFastify.js

@@ -11,8 +11,11 @@ const propagator = new core_1.W3CTraceContextPropagator();
 // `ignoreList` entries are matched against the exported span name.
 const SPAN_NAME_SANITIZE_RE = /[^a-zA-Z0-9-_/]/g;
 const DEFAULT_ROOT_API_PATH = "/api";
+const INTERNAL_URL_BASE = "http://internal";
 const requestSpans = new WeakMap();
 const requestContexts = new WeakMap();
+const requestStartTimes = new WeakMap();
+const requestsWithRecordedErrors = new WeakSet();
 const registeredFastifyInstances = new WeakSet();
 /**
  * Registers Fastify lifecycle hooks that automatically create and manage
@@ -20,12 +23,18 @@ const registeredFastifyInstances = new WeakSet();
  *
  * - Extracts incoming W3C trace context from request headers for distributed tracing.
  * - Creates a `SpanKind.SERVER` span named `METHOD-<route>` (route template for
- *   matched routes, e.g. `GET-/api/files/_id` for `/api/files/:id`; path
- *   fallback when no route matched), with `http.request.method`, `url.path`
- *   (path only, no query string) and `http.route` (route template) attributes.
- * - Marks spans as ERROR on 4xx/5xx responses or when exceptions occur.
+ *   matched routes, e.g. `GET-/api/files/_id` for `/api/files/:id`; path or
+ *   method fallback when no route matched, see `unmatchedRouteSpanName`), with
+ *   `http.request.method`, `url.path` (path only, no query string) and
+ *   `http.route` (route template) attributes.
+ * - Sets the span status according to the current HTTP semantic conventions for
+ *   server spans: unset for 1xx-4xx responses, ERROR for 5xx responses and
+ *   exceptions. A span that already recorded an error is never downgraded.
  * - Ends the span on response, handler error, client abort or connection timeout.
- * - Logs errors via the provided {@link StandardLogger} with trace context.
+ * - Logs errors via the provided {@link StandardLogger} with trace context;
+ *   client errors (`statusCode < 500`) are logged at warn level.
+ * - Tracing is fail-open: a fault in any hook is caught, logged once at warn
+ *   level and the request continues untraced.
  * - Skips OPTIONS requests and requests outside the configured `rootApiPath`.
  * - Additional filtering via `ignoreList` (exact), `ignoreListPrefix`, `ignoreListSuffix`
  *   — checked in that order with short-circuit evaluation.
@@ -45,6 +54,8 @@ const registeredFastifyInstances = new WeakSet();
  * @param options         - Optional path filtering and ignore lists.
  */
 function StandardTracerFastifyRegisterHooks(fastify, standardTracer, standardLogger, options) {
+    var _a;
+    var _b;
     const logger = standardLogger.createModuleLogger("Fastify");
     if (registeredFastifyInstances.has(fastify)) {
         logger.warn("StandardTracerFastifyRegisterHooks is already registered on this Fastify instance: ignoring the duplicate registration.");
@@ -52,80 +63,176 @@ function StandardTracerFastifyRegisterHooks(fastify, standardTracer, standardLog
     }
     registeredFastifyInstances.add(fastify);
     const rootApiPath = normalizeRootApiPath(options === null || options === void 0 ? void 0 : options.rootApiPath);
+    const unmatchedRouteSpanName = (_b = options === null || options === void 0 ? void 0 : options.unmatchedRouteSpanName) !== null && _b !== void 0 ? _b : "path";
+    const requestDurationHistogram = (_a = options === null || options === void 0 ? void 0 : options.standardMeter) === null || _a === void 0 ? void 0 : _a.createHistogram(semantic_conventions_1.METRIC_HTTP_SERVER_REQUEST_DURATION);
+    // Per-registration guard against per-request log flooding when tracing fails.
+    let hookFailureLogged = false;
+    const logHookFailureOnce = (hook, error) => {
+        if (hookFailureLogged) {
+            return;
+        }
+        hookFailureLogged = true;
+        try {
+            logger.warn(`Tracing hook "${hook}" failed (${error instanceof Error ? error.message : String(error)}): continuing without tracing.`);
+        }
+        catch {
+            // A failing logger must not affect the request either.
+        }
+    };
+    const clearRequestState = (req) => {
+        requestSpans.delete(req);
+        requestContexts.delete(req);
+        requestStartTimes.delete(req);
+        requestsWithRecordedErrors.delete(req);
+        // Deprecated alias: assigning undefined avoids a V8 hidden-class
+        // transition per request; the tests assert `!== undefined`.
+        req.tracerSpanApi = undefined;
+    };
     const endSpan = (req, end = {}) => {
         const span = requestSpans.get(req);
         if (!span) {
             return;
         }
-        requestSpans.delete(req);
-        requestContexts.delete(req);
-        delete req.tracerSpanApi;
-        if (end.errorType) {
-            span.setStatus({ code: api_1.SpanStatusCode.ERROR });
-            span.setAttribute(semantic_conventions_1.ATTR_ERROR_TYPE, end.errorType);
+        const errorRecorded = requestsWithRecordedErrors.has(req);
+        const startTime = requestStartTimes.get(req);
+        clearRequestState(req);
+        try {
+            if (end.errorType) {
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+                span.setAttribute(semantic_conventions_1.ATTR_ERROR_TYPE, end.errorType);
+            }
+            else if (end.statusCode !== undefined) {
+                // Status policy per the current OTel HTTP semantic conventions for
+                // server spans: leave the status unset for 1xx-4xx, ERROR for 5xx.
+                // A span on which onError already recorded an error is never
+                // downgraded (defense in depth; onError set ERROR already).
+                if (!errorRecorded && end.statusCode >= 500) {
+                    span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+                }
+                span.setAttribute(semantic_conventions_1.ATTR_HTTP_RESPONSE_STATUS_CODE, end.statusCode);
+            }
+            if (requestDurationHistogram) {
+                // The start time is always set in onRequest when the histogram is
+                // configured (same guard), so the lookup cannot miss here.
+                const durationSeconds = Number(process.hrtime.bigint() - startTime) / 1e9;
+                const attributes = {
+                    [semantic_conventions_1.ATTR_HTTP_REQUEST_METHOD]: req.method,
+                };
+                const routeTemplate = req.routeOptions.url;
+                if (routeTemplate) {
+                    attributes[semantic_conventions_1.ATTR_HTTP_ROUTE] = routeTemplate;
+                }
+                if (end.errorType) {
+                    attributes[semantic_conventions_1.ATTR_ERROR_TYPE] = end.errorType;
+                }
+                else if (end.statusCode !== undefined) {
+                    attributes[semantic_conventions_1.ATTR_HTTP_RESPONSE_STATUS_CODE] = end.statusCode;
+                }
+                requestDurationHistogram.record(durationSeconds, attributes);
+            }
         }
-        else if (end.statusCode !== undefined) {
-            span.setStatus({
-                code: end.statusCode > 299 ? api_1.SpanStatusCode.ERROR : api_1.SpanStatusCode.OK,
-            });
-            span.setAttribute(semantic_conventions_1.ATTR_HTTP_RESPONSE_STATUS_CODE, end.statusCode);
+        finally {
+            span.end();
         }
-        span.end();
     };
     fastify.addHook("onRequest", async (req) => {
         var _a, _b, _c;
-        if (req.method === "OPTIONS") {
-            return;
+        try {
+            if (req.method === "OPTIONS") {
+                return;
+            }
+            const path = getRequestPath(req.url);
+            if (rootApiPath !== "/" &&
+                path !== rootApiPath &&
+                !path.startsWith(`${rootApiPath}/`)) {
+                return;
+            }
+            const routeTemplate = req.routeOptions.url;
+            let spanName;
+            if (routeTemplate) {
+                spanName = sanitizeSpanName(`${req.method}-${routeTemplate}`);
+            }
+            else if (unmatchedRouteSpanName === "method") {
+                spanName = sanitizeSpanName(req.method);
+            }
+            else {
+                spanName = sanitizeSpanName(`${req.method}-${path}`);
+            }
+            if (((_a = options === null || options === void 0 ? void 0 : options.ignoreList) === null || _a === void 0 ? void 0 : _a.includes(spanName)) ||
+                ((_b = options === null || options === void 0 ? void 0 : options.ignoreListPrefix) === null || _b === void 0 ? void 0 : _b.some((p) => spanName.startsWith(p))) ||
+                ((_c = options === null || options === void 0 ? void 0 : options.ignoreListSuffix) === null || _c === void 0 ? void 0 : _c.some((s) => spanName.endsWith(s)))) {
+                return;
+            }
+            const callerContext = propagator.extract(api_1.ROOT_CONTEXT, req.headers, api_1.defaultTextMapGetter);
+            // The span is created inside the extracted context so that it becomes a
+            // child of the caller span when the request carries a `traceparent`.
+            const span = api_1.context.with(callerContext, () => standardTracer.startSpan(spanName, undefined, {
+                kind: api_1.SpanKind.SERVER,
+            }));
+            span.setAttribute(semantic_conventions_1.ATTR_HTTP_REQUEST_METHOD, req.method);
+            span.setAttribute(semantic_conventions_1.ATTR_URL_PATH, path);
+            if (routeTemplate) {
+                span.setAttribute(semantic_conventions_1.ATTR_HTTP_ROUTE, routeTemplate);
+            }
+            requestSpans.set(req, span);
+            requestContexts.set(req, api_1.trace.setSpan(callerContext, span));
+            if (requestDurationHistogram) {
+                requestStartTimes.set(req, process.hrtime.bigint());
+            }
+            // Deprecated alias kept for consumers that reimplemented the accessor
+            // (`req.tracerSpanApi` before 1.1.0); use OTelRequestSpan(req) instead.
+            req.tracerSpanApi = span;
         }
-        const path = req.url.split("?")[0];
-        if (rootApiPath !== "/" &&
-            path !== rootApiPath &&
-            !path.startsWith(`${rootApiPath}/`)) {
-            return;
+        catch (error) {
+            clearRequestState(req);
+            logHookFailureOnce("onRequest", error);
         }
-        const routeTemplate = req.routeOptions.url;
-        const spanName = sanitizeSpanName(`${req.method}-${routeTemplate || path}`);
-        if (((_a = options === null || options === void 0 ? void 0 : options.ignoreList) === null || _a === void 0 ? void 0 : _a.includes(spanName)) ||
-            ((_b = options === null || options === void 0 ? void 0 : options.ignoreListPrefix) === null || _b === void 0 ? void 0 : _b.some((p) => spanName.startsWith(p))) ||
-            ((_c = options === null || options === void 0 ? void 0 : options.ignoreListSuffix) === null || _c === void 0 ? void 0 : _c.some((s) => spanName.endsWith(s)))) {
-            return;
-        }
-        const callerContext = propagator.extract(api_1.ROOT_CONTEXT, req.headers, api_1.defaultTextMapGetter);
-        // The span is created inside the extracted context so that it becomes a
-        // child of the caller span when the request carries a `traceparent`.
-        const span = api_1.context.with(callerContext, () => standardTracer.startSpan(spanName, undefined, {
-            kind: api_1.SpanKind.SERVER,
-        }));
-        span.setAttribute(semantic_conventions_1.ATTR_HTTP_REQUEST_METHOD, req.method);
-        span.setAttribute(semantic_conventions_1.ATTR_URL_PATH, path);
-        if (routeTemplate) {
-            span.setAttribute(semantic_conventions_1.ATTR_HTTP_ROUTE, routeTemplate);
-        }
-        requestSpans.set(req, span);
-        requestContexts.set(req, api_1.trace.setSpan(callerContext, span));
-        // Deprecated alias kept for consumers that reimplemented the accessor
-        // (`req.tracerSpanApi` before 1.1.0); use OTelRequestSpan(req) instead.
-        req.tracerSpanApi = span;
     });
     fastify.addHook("onResponse", async (req, reply) => {
-        endSpan(req, { statusCode: reply.statusCode });
+        try {
+            endSpan(req, { statusCode: reply.statusCode });
+        }
+        catch (error) {
+            logHookFailureOnce("onResponse", error);
+        }
     });
     fastify.addHook("onError", async (req, _reply, error) => {
-        const span = requestSpans.get(req);
-        if (!span) {
-            return;
+        try {
+            const span = requestSpans.get(req);
+            if (!span) {
+                return;
+            }
+            requestsWithRecordedErrors.add(req);
+            const normalizedError = error instanceof Error ? error : new Error(String(error));
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+            span.setAttribute(semantic_conventions_1.ATTR_ERROR_TYPE, getErrorType(normalizedError));
+            span.recordException(normalizedError);
+            if (isClientError(normalizedError)) {
+                logger.warn(normalizedError.message, span);
+            }
+            else {
+                logger.error(normalizedError.message, normalizedError, span);
+            }
+        }
+        catch (hookError) {
+            logHookFailureOnce("onError", hookError);
         }
-        const normalizedError = error instanceof Error ? error : new Error(String(error));
-        span.setStatus({ code: api_1.SpanStatusCode.ERROR });
-        span.setAttribute(semantic_conventions_1.ATTR_ERROR_TYPE, normalizedError.name);
-        span.recordException(normalizedError);
-        logger.error(normalizedError.message, normalizedError, span);
     });
     fastify.addHook("onRequestAbort", async (req) => {
-        endSpan(req, { errorType: "client_abort" });
+        try {
+            endSpan(req, { errorType: "client_abort" });
+        }
+        catch (error) {
+            logHookFailureOnce("onRequestAbort", error);
+        }
     });
     fastify.addHook("onTimeout", async (req, _reply) => {
-        endSpan(req, { errorType: "timeout" });
+        try {
+            endSpan(req, { errorType: "timeout" });
+        }
+        catch (error) {
+            logHookFailureOnce("onTimeout", error);
+        }
     });
 }
 function normalizeRootApiPath(rootApiPath) {
@@ -135,6 +242,39 @@ function normalizeRootApiPath(rootApiPath) {
 function sanitizeSpanName(name) {
     return name.replace(SPAN_NAME_SANITIZE_RE, "_");
 }
+/**
+ * Extracts the pathname from a request target. Origin-form targets
+ * (`/path?query`, virtually all traffic) are split directly; absolute-form
+ * targets (e.g. `GET http://host/path HTTP/1.1`, allowed by HTTP/1.1 but rare
+ * in practice) are parsed with the URL parser. Unparseable targets cannot
+ * reach this function: the HTTP parser rejects them before the hooks run, and
+ * a residual parse failure is caught by the fail-open `onRequest` guard.
+ */
+function getRequestPath(url) {
+    if (url.startsWith("/")) {
+        return url.split("?")[0];
+    }
+    return new URL(url, INTERNAL_URL_BASE).pathname;
+}
+function isClientError(error) {
+    const statusCode = error.statusCode;
+    return typeof statusCode === "number" && statusCode < 500;
+}
+/**
+ * Low-cardinality `error.type` value: the error name when it is not the
+ * generic `Error`, otherwise its `code` (e.g. `FST_ERR_VALIDATION` for Fastify
+ * validation errors), otherwise `"Error"`.
+ */
+function getErrorType(error) {
+    if (error.name && error.name !== "Error") {
+        return error.name;
+    }
+    const code = error.code;
+    if (typeof code === "string" && code !== "") {
+        return code;
+    }
+    return "Error";
+}
 /**
  * Retrieves the OpenTelemetry span associated with a Fastify request.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/otel-utils-fastify",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Utility to simplify integration with Open Telemetry for Fastify API Server",
   "keywords": [
     "Open Telemetry",
@@ -14,6 +14,13 @@
   "type": "commonjs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist"
   ],