hotelme-nuxt-logger 1.5.0 → 1.6.0

package/README.md

@@ -163,6 +163,7 @@ logger: {
     enabled: true,
     ignorePaths: ['/nuxt_img/'],                 // + типові /_nuxt/, /_ipx/, /__nuxt, clientErrorEndpoint
     ignoreUserAgents: ['^Slackbot-LinkExpanding ', '^kube-probe/'],
+    slowMs: 1000,                                // порятунок повільних, env OTEL_TRACES_SLOW_MS
   },
 }
 ```
@@ -175,6 +176,20 @@ Env (читає SDK):
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_ENDPOINT` | — (обов'язкова: без неї трейсинг не вмикається, лог `otel_disabled`) |
 | `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG` | `parentbased_always_on` |
 
+Env модуля (перекриває `slowMs` з nuxt.config):
+
+| Змінна | Типово |
+|---|---|
+| `OTEL_TRACES_SLOW_MS` | — (0 — без порятунку) |
+
+Напр. 25% трейсів + повільні ≥ 1 с з решти:
+
+```yaml
+OTEL_TRACES_SAMPLER: parentbased_traceidratio
+OTEL_TRACES_SAMPLER_ARG: "0.25"
+OTEL_TRACES_SLOW_MS: "1000"
+```
+
 Що робить модуль:
 
 - **Активний контекст на весь запит.** Плагін обгортає `nitroApp.h3App.handler`, тож middleware, handler'и та SSR-рендер виконуються всередині `context.with(serverSpan)` — span'и з коду застосунку стають дочірніми без обгорток.
@@ -185,7 +200,14 @@ Env (читає SDK):
   - сторінка → `route.name` з Vue Router без i18n-суфікса: `GET weather-citynameid`, `GET index` (аліаси теж). Локаль — в атрибуті `i18n.locale`;
   - Nitro-хендлер → шаблон з файлової структури: `GET /api/city_info`, `GET /record/**`;
   - решта (відповідь з server middleware, невідомий шлях) → `GET /api/*` / `GET /*`; точний шлях — в `url.path`, статус — в `http.response.status_code`.
-- **Фільтри** (статика, `ignorePaths`, `ignoreUserAgents`) не міняють поведінку запиту: він обробляється як завжди, але в невибраному (sampled=0) контексті — без span'ів у нього, його внутрішніх викликів і бекенда (`traceparent …-00`). Потрібен parent-based семплер (типовий).
+- **Фільтри** (статика, `ignorePaths`, `ignoreUserAgents`) не міняють поведінку запиту: він обробляється як завжди, але в невибраному (sampled=0) контексті — без span'ів у нього, його внутрішніх викликів і бекенда (`traceparent …-00`; libwts3 з `OTEL_TRACES_SLOW_MS` все ж відправить свій повільний запит — без батька з цього боку). Потрібен parent-based семплер (типовий).
+- **Вибірка «head + порятунок повільних»** (`slowMs` > 0 і семплер вибирає < 100%):
+  - частка з `OTEL_TRACES_SAMPLER_ARG` вибирається на старті root span'а за trace id, як у `parentbased_traceidratio` — `traceparent …-01` іде в бекенд, трейс повний. Підтримуються `always_on` / `always_off` / `traceidratio` (з `parentbased_` чи без — семплер завжди parent-based); інший семплер (`jaeger_remote` тощо) → warn `otel_config_invalid`, порятунок вимкнено;
+  - решта пишеться в пам'ять (`traceparent …-00`) і буферизується до кінця свого локального root span'а — окремо для кожного запиту, навіть з одним trace id. Root тривав ≥ `slowMs` → експортуються він (`sampling.kept_by: "slow"`) і всі його локальні дочірні span'и (`/api/*`, CLIENT span'и вихідних fetch з тривалістю); інакше буфер скидається. Так само працює `OTEL_TRACES_SLOW_MS` у libwts3;
+  - span'и бекенда в такому трейсі є, лише якщо бекенд врятував їх сам: libwts3 на `…-00` теж пише в пам'ять і відправляє запит, що тривав ≥ свого `OTEL_TRACES_SLOW_MS` (типово 1000). Повільний бекенд робить повільним і root тут, тож трейс зв'язний; швидкого бекенда в ньому немає;
+  - вхідний `traceparent …-01` — вибраний, `…-00` — та сама логіка порятунку; фільтри (статика, `ignorePaths`, `ignoreUserAgents`) не пишуться взагалі;
+  - буфер обмежено: 2000 трейсів у польоті, 512 span'ів на трейс.
+- **`?force_otel=1`** у запиті (як у libwts3) — трейс вибраний завжди: попри частку семплера, фільтри (`ignorePaths`, `ignoreUserAgents`, статика) і вхідний `traceparent …-00`. Позначка в контексті, тож вибрані й дочірні span'и (внутрішні `/api/*`, вихідні fetch), а бекенд отримує `traceparent …-01` і пише свою частину повністю. Root — з `sampling.kept_by: "force"`. Працює з `always_*` / `traceidratio` (з `parentbased_` чи без); з іншим семплером (`jaeger_remote`) параметр ігнорується, `otel_initialized` пише `force_otel: false`. Параметр публічний: будь-хто може форсувати трейс — як і в libwts3.
 - **Flush при зупинці**: span'и батчуються до 5 с, на `close` provider робить shutdown.
 - Помилки експорту (`diag`) пишуться JSON-логером як `otel_diag`.
 

package/dist/module.d.cts

@@ -56,6 +56,14 @@ interface OtelOptions {
      * @default []
      */
     ignoreUserAgents?: string[];
+    /**
+     * Трейси поза вибіркою семплера з `OTEL_TRACES_SAMPLER*` (`always_*`,
+     * `traceidratio`, з `parentbased_` чи без), чий server span тривав ≥ `slowMs`,
+     * теж експортуються — увесь запит з локальними дочірніми span'ами, як
+     * `OTEL_TRACES_SLOW_MS` у libwts3. Бекенд рятує свою частину сам. Перекривається env
+     * `OTEL_TRACES_SLOW_MS`. 0 — вимкнено.
+     */
+    slowMs?: number;
 }
 declare const _default: any;
 

package/dist/module.d.mts

@@ -56,6 +56,14 @@ interface OtelOptions {
      * @default []
      */
     ignoreUserAgents?: string[];
+    /**
+     * Трейси поза вибіркою семплера з `OTEL_TRACES_SAMPLER*` (`always_*`,
+     * `traceidratio`, з `parentbased_` чи без), чий server span тривав ≥ `slowMs`,
+     * теж експортуються — увесь запит з локальними дочірніми span'ами, як
+     * `OTEL_TRACES_SLOW_MS` у libwts3. Бекенд рятує свою частину сам. Перекривається env
+     * `OTEL_TRACES_SLOW_MS`. 0 — вимкнено.
+     */
+    slowMs?: number;
 }
 declare const _default: any;
 

package/dist/module.d.ts

@@ -56,6 +56,14 @@ interface OtelOptions {
      * @default []
      */
     ignoreUserAgents?: string[];
+    /**
+     * Трейси поза вибіркою семплера з `OTEL_TRACES_SAMPLER*` (`always_*`,
+     * `traceidratio`, з `parentbased_` чи без), чий server span тривав ≥ `slowMs`,
+     * теж експортуються — увесь запит з локальними дочірніми span'ами, як
+     * `OTEL_TRACES_SLOW_MS` у libwts3. Бекенд рятує свою частину сам. Перекривається env
+     * `OTEL_TRACES_SLOW_MS`. 0 — вимкнено.
+     */
+    slowMs?: number;
 }
 declare const _default: any;
 

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.0.0 || ^4.0.0"
   },
-  "version": "1.5.0",
+  "version": "1.6.0",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "2.0.0"

package/dist/runtime/server/otel/config.d.ts

@@ -1,8 +1,10 @@
+import { type Sampler } from '@opentelemetry/sdk-trace-base';
 /** Серіалізована форма `logger.otel` з nuxt.config (див. module.ts). */
 export interface OtelRuntimeConfig {
     ignorePaths?: string[];
     ignoreStaticAssets?: boolean;
     ignoreUserAgents?: string[];
+    slowMs?: number;
 }
 export interface OtelSettings {
     ignorePaths: string[];
@@ -13,3 +15,25 @@ export declare const TRACER_NAME = "hotelme-nuxt-logger";
 export declare function otelRuntimeConfig(): OtelRuntimeConfig;
 /** Регекспи компілюються один раз, на першому запиті. */
 export declare function otelSettings(): OtelSettings;
+export interface OtelSampling {
+    /** Частка head-вибірки з OTEL_TRACES_SAMPLER*, 0–1 */
+    ratio: number;
+    /** Поріг порятунку повільних трейсів, мс */
+    slowMs: number;
+}
+/**
+ * Той самий семплер, що SDK зібрав би з env сам (`buildSamplerFromEnv` не
+ * експортується) — щоб обгорнути його ForceSampler'ом. undefined — семплер,
+ * якого тут немає: лишається на SDK.
+ */
+export declare function envSampler(): Sampler | undefined;
+/**
+ * Порятунок повільних: `OTEL_TRACES_SLOW_MS` (перекриває `logger.otel.slowMs`)
+ * > 0 і семплер з `OTEL_TRACES_SAMPLER*` вибирає менше 100%. Інакше undefined —
+ * семплер з env без порятунку (envSampler), як до 1.6.0.
+ *
+ * Семплер з порятунком завжди parent-based: `traceidratio` без префікса
+ * поводиться як `parentbased_traceidratio` — фільтри serverSpan.ts без цього
+ * не працюють.
+ */
+export declare function otelSampling(): OtelSampling | undefined;

package/dist/runtime/server/otel/config.js

@@ -1,4 +1,6 @@
 import { useRuntimeConfig } from "#imports";
+import { AlwaysOffSampler, AlwaysOnSampler, ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
+import { logger } from "../../logger.js";
 export const TRACER_NAME = "hotelme-nuxt-logger";
 export function otelRuntimeConfig() {
   return useRuntimeConfig().logger?.otel ?? {};
@@ -15,3 +17,43 @@ export function otelSettings() {
   };
   return settings;
 }
+function envNumber(name) {
+  const raw = process.env[name]?.trim();
+  if (!raw) return void 0;
+  const value = Number(raw);
+  if (Number.isFinite(value)) return value;
+  logger.warn("otel_config_invalid", { error: `${name}=${raw} is not a number, ignored` });
+  return void 0;
+}
+function envSamplerConfig() {
+  const sampler = process.env.OTEL_TRACES_SAMPLER?.trim().toLowerCase() || "parentbased_always_on";
+  const parentBased = sampler.startsWith("parentbased_");
+  switch (parentBased ? sampler.slice("parentbased_".length) : sampler) {
+    case "always_on":
+      return { ratio: 1, parentBased };
+    case "always_off":
+      return { ratio: 0, parentBased };
+    case "traceidratio": {
+      const ratio = envNumber("OTEL_TRACES_SAMPLER_ARG");
+      return { ratio: ratio !== void 0 && ratio >= 0 && ratio <= 1 ? ratio : 1, parentBased };
+    }
+    default:
+      return void 0;
+  }
+}
+export function envSampler() {
+  const config = envSamplerConfig();
+  if (!config) return void 0;
+  const root = config.ratio >= 1 ? new AlwaysOnSampler() : config.ratio <= 0 ? new AlwaysOffSampler() : new TraceIdRatioBasedSampler(config.ratio);
+  return config.parentBased ? new ParentBasedSampler({ root }) : root;
+}
+export function otelSampling() {
+  const slowMs = envNumber("OTEL_TRACES_SLOW_MS") ?? otelRuntimeConfig().slowMs ?? 0;
+  if (slowMs <= 0) return void 0;
+  const ratio = envSamplerConfig()?.ratio;
+  if (ratio === void 0) {
+    logger.warn("otel_config_invalid", { error: `OTEL_TRACES_SLOW_MS ignored: unsupported OTEL_TRACES_SAMPLER=${process.env.OTEL_TRACES_SAMPLER}` });
+    return void 0;
+  }
+  return ratio < 1 ? { ratio, slowMs } : void 0;
+}

package/dist/runtime/server/otel/plugin.d.ts

@@ -5,7 +5,13 @@
  * - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT
  *   (insecure чи TLS — за схемою URL). Без них трейсинг не вмикається:
  *   експортер SDK інакше мовчки слав би на localhost:4317.
- * - OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG (типово parentbased_always_on)
+ * - OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG (типово parentbased_always_on).
+ *
+ * OTEL_TRACES_SLOW_MS (config.ts → otelSampling) — порятунок трейсів поза
+ * вибіркою, чий root тривав довше порогу (див. sampling.ts). Тоді семплер —
+ * HeadSampler з тією ж часткою, що в OTEL_TRACES_SAMPLER_ARG.
+ *
+ * `?force_otel=1` у запиті — трейс вибраний завжди (ForceSampler, як у libwts3).
  *
  * Root trace id — з `X-Request-ID`, див. requestTraceId.ts.
  *

package/dist/runtime/server/otel/plugin.js

@@ -11,6 +11,8 @@ import { logger } from "../../logger.js";
 import { currentRequestEvent, requestIdOf } from "../requestContext.js";
 import { serverSpanContext } from "./serverSpan.js";
 import { requestIdGenerator } from "./requestTraceId.js";
+import { envSampler, otelSampling } from "./config.js";
+import { ForceSampler, HeadSampler, SlowTraceSpanProcessor } from "./sampling.js";
 const diagLogger = {
   error: (message, ...args) => logger.error("otel_diag", { error: message, args }),
   warn: (message, ...args) => logger.warn("otel_diag", { error: message, args }),
@@ -47,14 +49,18 @@ export default defineNitroPlugin((nitroApp) => {
   }
   diag.setLogger(diagLogger, DiagLogLevel.WARN);
   const serviceName = process.env.OTEL_SERVICE_NAME || String(useRuntimeConfig().public.projectName || "hotelme");
-  const spanProcessor = new BatchSpanProcessor(new OTLPTraceExporter(), {
+  const batchProcessor = new BatchSpanProcessor(new OTLPTraceExporter(), {
     maxQueueSize: 2048,
     maxExportBatchSize: 512,
     scheduledDelayMillis: 5e3,
     exportTimeoutMillis: 1e4
   });
+  const sampling = otelSampling();
+  const spanProcessor = sampling ? new SlowTraceSpanProcessor(batchProcessor, sampling.slowMs) : batchProcessor;
+  const baseSampler = sampling ? new HeadSampler(sampling.ratio) : envSampler();
   const provider = new NodeTracerProvider({
     resource: resourceFromAttributes({ "service.name": serviceName }),
+    ...baseSampler && { sampler: new ForceSampler(baseSampler) },
     spanProcessors: [spanProcessor],
     idGenerator: requestIdGenerator
   });
@@ -77,5 +83,12 @@ export default defineNitroPlugin((nitroApp) => {
       context.disable();
     }
   });
-  logger.info("otel_initialized", { service: serviceName, endpoint });
+  logger.info("otel_initialized", {
+    service: serviceName,
+    endpoint,
+    sampler: process.env.OTEL_TRACES_SAMPLER || "parentbased_always_on",
+    sampler_arg: process.env.OTEL_TRACES_SAMPLER_ARG,
+    slow_ms: sampling?.slowMs,
+    force_otel: !!baseSampler
+  });
 });

package/dist/runtime/server/otel/sampling.d.ts

@@ -0,0 +1,64 @@
+import { type Attributes, type Context, type Link, type SpanKind } from '@opentelemetry/api';
+import { type ReadableSpan, type Sampler, type SamplingResult, type Span, type SpanProcessor } from '@opentelemetry/sdk-trace-base';
+/** Контекст, у якому ForceSampler вибирає кожен span — його й усіх дочірніх. */
+export declare function forceSampled(context: Context): Context;
+/**
+ * `?force_otel=1` як у libwts3: запит вибраний попри частку семплера, фільтри
+ * й вхідний `traceparent …-00`. Позначка живе в контексті, тож дочірні span'и
+ * (внутрішні `/api/*`, вихідні fetch) теж вибрані, а бекенд отримує
+ * `traceparent …-01` і пише свою частину повністю. Решта — `base`.
+ */
+export declare class ForceSampler implements Sampler {
+    private readonly base;
+    constructor(base: Sampler);
+    shouldSample(context: Context, traceId: string, spanName: string, spanKind: SpanKind, attributes: Attributes, links: Link[]): SamplingResult;
+    toString(): string;
+}
+/**
+ * `parentbased_traceidratio`, у якого решта трейсів — RECORD замість
+ * NOT_RECORD: span'и пишуться в пам'ять для SlowTraceSpanProcessor, але
+ * назовні йде `traceparent …-00`: бекенд вирішує сам (libwts3 теж рятує
+ * повільні).
+ *
+ * Батько вибраний → вибраний. Невибраний батько:
+ * - власний record-only span або вхідний `traceparent …-00` → RECORD;
+ * - unsampledContext із serverSpan.ts (статика, ignorePaths, ignoreUserAgents) —
+ *   локальний non-recording span → NOT_RECORD, фільтри працюють як раніше.
+ */
+export declare class HeadSampler implements Sampler {
+    private readonly ratio;
+    constructor(ratio: number);
+    shouldSample(context: Context, traceId: string): SamplingResult;
+    toString(): string;
+}
+/**
+ * Порятунок повільних трейсів, які не потрапили в head-вибірку — як
+ * OTEL_TRACES_SLOW_MS у libwts3: рішення на весь запит, а не на окремий span.
+ *
+ * Вибрані span'и йдуть у `next` одразу. Record-only (див. HeadSampler)
+ * буферизуються до кінця свого локального root'а — server span'а без батька
+ * або з віддаленим батьком. Root тривав ≥ `slowMs` → увесь запит іде в `next`
+ * з прапорцем sampled, root — з `sampling.kept_by: "slow"`; інакше буфер
+ * скидається. Бекенд отримав `traceparent …-00`, тож його span'и в трейсі є,
+ * лише якщо він сам їх врятував (libwts3: тривав ≥ свого OTEL_TRACES_SLOW_MS).
+ *
+ * Ключ буфера — span id локального root'а, не trace id: кілька запитів з одним
+ * trace id (один вхідний `traceparent`, повтор `X-Request-ID`) вирішуються
+ * кожен за своєю тривалістю.
+ *
+ * Рішення пам'ятається, щоб span'и, які закінчились після root'а
+ * (fire-and-forget fetch), пішли за ним, а не зависли в буфері.
+ */
+export declare class SlowTraceSpanProcessor implements SpanProcessor {
+    private readonly next;
+    private readonly slowMs;
+    /** Record-only span → span id його локального root'а */
+    private readonly roots;
+    private readonly pending;
+    private readonly decisions;
+    constructor(next: SpanProcessor, slowMs: number);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/runtime/server/otel/sampling.js

@@ -0,0 +1,126 @@
+import { createContextKey, isSpanContextValid, trace, TraceFlags } from "@opentelemetry/api";
+import { hrTimeToMilliseconds } from "@opentelemetry/core";
+import {
+  SamplingDecision,
+  TraceIdRatioBasedSampler
+} from "@opentelemetry/sdk-trace-base";
+const SAMPLED = { decision: SamplingDecision.RECORD_AND_SAMPLED };
+const RECORDED = { decision: SamplingDecision.RECORD };
+const DROPPED = { decision: SamplingDecision.NOT_RECORD };
+const FORCED = createContextKey("hotelme-nuxt-logger.force_otel");
+export function forceSampled(context) {
+  return context.setValue(FORCED, true);
+}
+export class ForceSampler {
+  constructor(base) {
+    this.base = base;
+  }
+  shouldSample(context, traceId, spanName, spanKind, attributes, links) {
+    if (context.getValue(FORCED)) return SAMPLED;
+    return this.base.shouldSample(context, traceId, spanName, spanKind, attributes, links);
+  }
+  toString() {
+    return `ForceSampler{${this.base}}`;
+  }
+}
+export class HeadSampler {
+  ratio;
+  constructor(ratio) {
+    this.ratio = new TraceIdRatioBasedSampler(ratio);
+  }
+  shouldSample(context, traceId) {
+    const parentSpan = trace.getSpan(context);
+    const parent = parentSpan?.spanContext();
+    if (!parentSpan || !parent || !isSpanContextValid(parent)) {
+      return this.ratio.shouldSample(context, traceId).decision === SamplingDecision.RECORD_AND_SAMPLED ? SAMPLED : RECORDED;
+    }
+    if (parent.traceFlags & TraceFlags.SAMPLED) return SAMPLED;
+    return parent.isRemote || parentSpan.isRecording() ? RECORDED : DROPPED;
+  }
+  toString() {
+    return `HeadSampler{${this.ratio}}`;
+  }
+}
+const MAX_PENDING_TRACES = 2e3;
+const MAX_SPANS_PER_TRACE = 512;
+const MAX_DECISIONS = 2e3;
+function rememberBounded(map, key, value, max) {
+  if (map.size >= max) map.delete(map.keys().next().value);
+  map.set(key, value);
+}
+function isLocalRoot(span) {
+  return !span.parentSpanContext || !!span.parentSpanContext.isRemote;
+}
+function asSampled(span, extraAttributes) {
+  const spanContext = { ...span.spanContext(), traceFlags: span.spanContext().traceFlags | TraceFlags.SAMPLED };
+  return {
+    name: span.name,
+    kind: span.kind,
+    spanContext: () => spanContext,
+    parentSpanContext: span.parentSpanContext,
+    startTime: span.startTime,
+    endTime: span.endTime,
+    status: span.status,
+    attributes: extraAttributes ? { ...span.attributes, ...extraAttributes } : span.attributes,
+    links: span.links,
+    events: span.events,
+    duration: span.duration,
+    ended: span.ended,
+    resource: span.resource,
+    instrumentationScope: span.instrumentationScope,
+    droppedAttributesCount: span.droppedAttributesCount,
+    droppedEventsCount: span.droppedEventsCount,
+    droppedLinksCount: span.droppedLinksCount
+  };
+}
+export class SlowTraceSpanProcessor {
+  constructor(next, slowMs) {
+    this.next = next;
+    this.slowMs = slowMs;
+  }
+  /** Record-only span → span id його локального root'а */
+  roots = /* @__PURE__ */ new WeakMap();
+  pending = /* @__PURE__ */ new Map();
+  decisions = /* @__PURE__ */ new Map();
+  onStart(span, parentContext) {
+    if (!(span.spanContext().traceFlags & TraceFlags.SAMPLED)) {
+      const parent = trace.getSpan(parentContext);
+      const root = !isLocalRoot(span) && parent ? this.roots.get(parent) : void 0;
+      this.roots.set(span, root ?? span.spanContext().spanId);
+    }
+    this.next.onStart(span, parentContext);
+  }
+  onEnd(span) {
+    if (span.spanContext().traceFlags & TraceFlags.SAMPLED) return this.next.onEnd(span);
+    const root = this.roots.get(span) ?? span.spanContext().spanId;
+    const decision = this.decisions.get(root);
+    if (decision !== void 0) {
+      if (decision) this.next.onEnd(asSampled(span));
+      return;
+    }
+    if (!isLocalRoot(span)) {
+      let spans2 = this.pending.get(root);
+      if (!spans2) {
+        spans2 = [];
+        rememberBounded(this.pending, root, spans2, MAX_PENDING_TRACES);
+      }
+      if (spans2.length < MAX_SPANS_PER_TRACE) spans2.push(span);
+      return;
+    }
+    const spans = this.pending.get(root) ?? [];
+    this.pending.delete(root);
+    const keep = hrTimeToMilliseconds(span.duration) >= this.slowMs;
+    rememberBounded(this.decisions, root, keep, MAX_DECISIONS);
+    if (!keep) return;
+    for (const child of spans) this.next.onEnd(asSampled(child));
+    this.next.onEnd(asSampled(span, { "sampling.kept_by": "slow" }));
+  }
+  forceFlush() {
+    return this.next.forceFlush();
+  }
+  shutdown() {
+    this.pending.clear();
+    this.decisions.clear();
+    return this.next.shutdown();
+  }
+}

package/dist/runtime/server/otel/serverSpan.d.ts

@@ -20,6 +20,9 @@ declare module 'h3' {
  * /api-виклики, вихідні fetch і span'и бекенда стали б осиротілими
  * root-трейсами. Дочірні запити успадковують його через parent-based семплер.
  *
+ * `?force_otel=1` (як у libwts3) — трейс вибраний попри фільтри, частку
+ * семплера й вхідний `traceparent …-00`, root з `sampling.kept_by: "force"`.
+ *
  * Кладе в event.context `otelSpan` (назва сторінки, `i18n.locale`), віддає
  * `X-Trace-Id` у відповіді.
  */

package/dist/runtime/server/otel/serverSpan.js

@@ -3,6 +3,7 @@ import { context, isSpanContextValid, propagation, trace, SpanKind, SpanStatusCo
 import { isTracingSuppressed } from "@opentelemetry/core";
 import { requestIdOf } from "../requestContext.js";
 import { otelSettings, TRACER_NAME } from "./config.js";
+import { forceSampled } from "./sampling.js";
 import { requestIdGenerator } from "./requestTraceId.js";
 const STATIC_ASSET = /\.(css|m?js|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|map|json|txt|xml)$/i;
 function unsampledContext(active) {
@@ -22,15 +23,18 @@ export function serverSpanContext(event) {
   const settings = otelSettings();
   const userAgent = getHeader(event, "user-agent") ?? "";
   const [pathname = "", query = ""] = event.path.split("?");
-  if (isTracingSuppressed(active) || settings.ignoreUserAgent?.test(userAgent) || settings.ignorePaths.some((prefix) => pathname.startsWith(prefix)) || settings.ignoreStaticAssets && STATIC_ASSET.test(pathname)) {
-    return isTracingSuppressed(active) ? active : unsampledContext(active);
+  if (isTracingSuppressed(active)) return active;
+  const forced = new URLSearchParams(query).get("force_otel") === "1";
+  if (!forced && (settings.ignoreUserAgent?.test(userAgent) || settings.ignorePaths.some((prefix) => pathname.startsWith(prefix)) || settings.ignoreStaticAssets && STATIC_ASSET.test(pathname))) {
+    return unsampledContext(active);
   }
   const carrier = {};
   const traceparent = getHeader(event, "traceparent");
   const tracestate = getHeader(event, "tracestate");
   if (traceparent) carrier.traceparent = traceparent;
   if (tracestate) carrier.tracestate = tracestate;
-  const parentCtx = propagation.extract(active, carrier);
+  const extracted = propagation.extract(active, carrier);
+  const parentCtx = forced ? forceSampled(extracted) : extracted;
   const span = trace.getTracer(TRACER_NAME).startSpan(
     `${event.method} ${pathname.startsWith("/api/") ? "/api/*" : "/*"}`,
     {
@@ -40,7 +44,8 @@ export function serverSpanContext(event) {
         "url.path": pathname,
         "url.query": query,
         "server.address": getHeader(event, "host") ?? "",
-        "user_agent.original": userAgent
+        "user_agent.original": userAgent,
+        ...forced && { "sampling.kept_by": "force" }
       }
     },
     parentCtx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotelme-nuxt-logger",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Стандартний logger для Nuxt проектів з JSON виводом сумісним з бекенд-логами",
   "keywords": [
     "nuxt",