hotelme-nuxt-logger 1.3.0 → 1.5.0

package/README.md

@@ -117,6 +117,8 @@ logger.warn('Rate limit approaching', { remaining: 10 })
 
 ### В API handlers
 
+`logger` та `getRequestId` auto-import'яться і в серверному коді Nitro (з 1.4.0). Явний імпорт, якщо треба: `import { logger } from 'hotelme-nuxt-logger/runtime/logger'`.
+
 ```typescript
 // server/api/hotels.get.ts
 export default defineEventHandler((event) => {
@@ -149,6 +151,52 @@ const response = await $fetch('/api/hotels', {
 })
 ```
 
+## OpenTelemetry (з 1.5.0)
+
+Трейсинг вимкнено за замовчуванням. Вмикається в nuxt.config — SDK, OTLP gRPC
+експортер і `@opentelemetry/api` вже є в залежностях модуля, ставити окремо не треба.
+
+```typescript
+logger: {
+  projectName: 'widgets-ssr',
+  otel: {
+    enabled: true,
+    ignorePaths: ['/nuxt_img/'],                 // + типові /_nuxt/, /_ipx/, /__nuxt, clientErrorEndpoint
+    ignoreUserAgents: ['^Slackbot-LinkExpanding ', '^kube-probe/'],
+  },
+}
+```
+
+Env (читає SDK):
+
+| Змінна | Типово |
+|---|---|
+| `OTEL_SERVICE_NAME` | `projectName` |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_ENDPOINT` | — (обов'язкова: без неї трейсинг не вмикається, лог `otel_disabled`) |
+| `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG` | `parentbased_always_on` |
+
+Що робить модуль:
+
+- **Активний контекст на весь запит.** Плагін обгортає `nitroApp.h3App.handler`, тож middleware, handler'и та SSR-рендер виконуються всередині `context.with(serverSpan)` — span'и з коду застосунку стають дочірніми без обгорток.
+- **Server span** на кожен запит, батько — вхідний `traceparent`. Без нього trace id = `X-Request-ID` без дефісів (`2e285875-f20c-…` → `2e285875f20c…`, як у libwts3), якщо це UUID / 32 hex; інакше випадковий. У `event.context`: `otelSpan`; у відповіді — `X-Trace-Id`. 5xx → статус ERROR, 4xx — ні.
+- **Вихідні fetch** (native `fetch`, `$fetch`, ofetch на зовнішній URL) — `@opentelemetry/instrumentation-undici` через diagnostics_channel: CLIENT span `GET <host>` (повний URL — в `url.full`), `traceparent` і `X-Request-ID` сторінки, якщо виклик не поставив свій. Поза запитом span'и не пишуться.
+- **Внутрішні SSR-виклики** (`$fetch('/api/…')` → Nitro localFetch) ідуть у тому ж async-ланцюжку, тож span роуту стає дочірнім span'а сторінки, а logger-middleware бере reqid сторінки. Заголовки руками не потрібні.
+- **Назва span'а** — шаблон, ніколи сирий шлях (кожна назва — окремий stream у VictoriaTraces), визначається сама після роутингу:
+  - сторінка → `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 семплер (типовий).
+- **Flush при зупинці**: span'и батчуються до 5 с, на `close` provider робить shutdown.
+- Помилки експорту (`diag`) пишуться JSON-логером як `otel_diag`.
+
+Хелпер (auto-import у Nitro або `import … from 'hotelme-nuxt-logger/runtime/otel'`), працює і з вимкненим трейсингом:
+
+```typescript
+// X-Request-ID сторінки (явна подія або поточна) — для бекендів, коли OTel вимкнено
+const headers = traceHeaders(event)
+
+```
+
 ## API
 
 ### Logger методи

package/dist/module.cjs

@@ -17,7 +17,13 @@ const module$1 = kit.defineNuxtModule({
     enableRequestLogging: true,
     enableErrorLogging: true,
     enableClientErrorLogging: true,
-    clientErrorEndpoint: "/_logger/client-error"
+    clientErrorEndpoint: "/_logger/client-error",
+    otel: {
+      enabled: false,
+      ignorePaths: ["/_nuxt/", "/_ipx/", "/__nuxt"],
+      ignoreStaticAssets: true,
+      ignoreUserAgents: []
+    }
   },
   setup(options, nuxt) {
     const moduleDir = typeof __dirname !== "undefined" ? __dirname : path.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('module.cjs', document.baseURI).href))));
@@ -26,6 +32,16 @@ const module$1 = kit.defineNuxtModule({
     const clientErrorEndpoint = options.clientErrorEndpoint || "/_logger/client-error";
     nuxt.options.runtimeConfig.public.loggerClientErrorEndpoint = clientErrorEndpoint;
     kit.addImportsDir(resolver.resolve("./runtime"));
+    kit.addServerImports([
+      { name: "logger", from: resolver.resolve("./runtime/logger") },
+      { name: "getRequestId", from: resolver.resolve("./runtime/logger") },
+      { name: "traceHeaders", from: resolver.resolve("./runtime/server/otel/tracing") }
+    ]);
+    const { enabled: otelEnabled, ignorePaths = [], ...otel } = options.otel ?? {};
+    nuxt.options.runtimeConfig.logger = {
+      ...nuxt.options.runtimeConfig.logger,
+      otel: { ...otel, ignorePaths: [.../* @__PURE__ */ new Set([...ignorePaths, clientErrorEndpoint])] }
+    };
     if (options.enableRequestLogging) {
       kit.addServerHandler({
         handler: resolver.resolve("./runtime/middleware/logger.server"),
@@ -46,6 +62,14 @@ const module$1 = kit.defineNuxtModule({
         handler: resolver.resolve("./runtime/server/routes/client-error.post")
       });
     }
+    if (otelEnabled) {
+      kit.addServerPlugin(resolver.resolve("./runtime/server/otel/plugin"));
+      kit.addPlugin({
+        src: resolver.resolve("./runtime/plugins/otelPageName.server"),
+        mode: "server"
+      });
+    }
+    kit.addServerPlugin(resolver.resolve("./runtime/server/contextPlugin"));
   }
 });
 

package/dist/module.d.cts

@@ -27,8 +27,37 @@ interface ModuleOptions {
      * @default '/_logger/client-error'
      */
     clientErrorEndpoint?: string;
+    /**
+     * OpenTelemetry-трейсинг (OTLP gRPC). Вимкнено за замовчуванням.
+     * Хелпер `traceHeaders` доступний й з вимкненим трейсингом.
+     */
+    otel?: OtelOptions;
+}
+interface OtelOptions {
+    /**
+     * Tracer provider, OTLP-експортер і server span на кожен запит.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Префікси шляхів без span'ів (разом з дочірніми). Додаються до типових.
+     * @default ['/_nuxt/', '/_ipx/', '/__nuxt', clientErrorEndpoint]
+     */
+    ignorePaths?: string[];
+    /**
+     * Без span'ів для статики (css, js, картинки, шрифти, json, txt, xml, map).
+     * @default true
+     */
+    ignoreStaticAssets?: boolean;
+    /**
+     * Regex-рядки User-Agent без span'ів (k8s probe, боти прев'ю посилань), напр.
+     * `'^kube-probe/'`, `'^Slackbot-LinkExpanding '`. Трейсинг вимикається на
+     * весь запит, разом із його внутрішніми /api-викликами та вихідними fetch.
+     * @default []
+     */
+    ignoreUserAgents?: string[];
 }
 declare const _default: any;
 
 export { _default as default };
-export type { ModuleOptions };
+export type { ModuleOptions, OtelOptions };

package/dist/module.d.mts

@@ -27,8 +27,37 @@ interface ModuleOptions {
      * @default '/_logger/client-error'
      */
     clientErrorEndpoint?: string;
+    /**
+     * OpenTelemetry-трейсинг (OTLP gRPC). Вимкнено за замовчуванням.
+     * Хелпер `traceHeaders` доступний й з вимкненим трейсингом.
+     */
+    otel?: OtelOptions;
+}
+interface OtelOptions {
+    /**
+     * Tracer provider, OTLP-експортер і server span на кожен запит.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Префікси шляхів без span'ів (разом з дочірніми). Додаються до типових.
+     * @default ['/_nuxt/', '/_ipx/', '/__nuxt', clientErrorEndpoint]
+     */
+    ignorePaths?: string[];
+    /**
+     * Без span'ів для статики (css, js, картинки, шрифти, json, txt, xml, map).
+     * @default true
+     */
+    ignoreStaticAssets?: boolean;
+    /**
+     * Regex-рядки User-Agent без span'ів (k8s probe, боти прев'ю посилань), напр.
+     * `'^kube-probe/'`, `'^Slackbot-LinkExpanding '`. Трейсинг вимикається на
+     * весь запит, разом із його внутрішніми /api-викликами та вихідними fetch.
+     * @default []
+     */
+    ignoreUserAgents?: string[];
 }
 declare const _default: any;
 
 export { _default as default };
-export type { ModuleOptions };
+export type { ModuleOptions, OtelOptions };

package/dist/module.d.ts

@@ -27,8 +27,37 @@ interface ModuleOptions {
      * @default '/_logger/client-error'
      */
     clientErrorEndpoint?: string;
+    /**
+     * OpenTelemetry-трейсинг (OTLP gRPC). Вимкнено за замовчуванням.
+     * Хелпер `traceHeaders` доступний й з вимкненим трейсингом.
+     */
+    otel?: OtelOptions;
+}
+interface OtelOptions {
+    /**
+     * Tracer provider, OTLP-експортер і server span на кожен запит.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Префікси шляхів без span'ів (разом з дочірніми). Додаються до типових.
+     * @default ['/_nuxt/', '/_ipx/', '/__nuxt', clientErrorEndpoint]
+     */
+    ignorePaths?: string[];
+    /**
+     * Без span'ів для статики (css, js, картинки, шрифти, json, txt, xml, map).
+     * @default true
+     */
+    ignoreStaticAssets?: boolean;
+    /**
+     * Regex-рядки User-Agent без span'ів (k8s probe, боти прев'ю посилань), напр.
+     * `'^kube-probe/'`, `'^Slackbot-LinkExpanding '`. Трейсинг вимикається на
+     * весь запит, разом із його внутрішніми /api-викликами та вихідними fetch.
+     * @default []
+     */
+    ignoreUserAgents?: string[];
 }
 declare const _default: any;
 
 export { _default as default };
-export type { ModuleOptions };
+export type { ModuleOptions, OtelOptions };

package/dist/module.json

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

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { defineNuxtModule, createResolver, addImportsDir, addServerHandler, addServerPlugin, addPlugin } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addImportsDir, addServerImports, addServerHandler, addServerPlugin, addPlugin } from '@nuxt/kit';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 
@@ -23,7 +23,13 @@ const module = defineNuxtModule({
     enableRequestLogging: true,
     enableErrorLogging: true,
     enableClientErrorLogging: true,
-    clientErrorEndpoint: "/_logger/client-error"
+    clientErrorEndpoint: "/_logger/client-error",
+    otel: {
+      enabled: false,
+      ignorePaths: ["/_nuxt/", "/_ipx/", "/__nuxt"],
+      ignoreStaticAssets: true,
+      ignoreUserAgents: []
+    }
   },
   setup(options, nuxt) {
     const moduleDir = typeof __dirname !== "undefined" ? __dirname : dirname(fileURLToPath(import.meta.url));
@@ -32,6 +38,16 @@ const module = defineNuxtModule({
     const clientErrorEndpoint = options.clientErrorEndpoint || "/_logger/client-error";
     nuxt.options.runtimeConfig.public.loggerClientErrorEndpoint = clientErrorEndpoint;
     addImportsDir(resolver.resolve("./runtime"));
+    addServerImports([
+      { name: "logger", from: resolver.resolve("./runtime/logger") },
+      { name: "getRequestId", from: resolver.resolve("./runtime/logger") },
+      { name: "traceHeaders", from: resolver.resolve("./runtime/server/otel/tracing") }
+    ]);
+    const { enabled: otelEnabled, ignorePaths = [], ...otel } = options.otel ?? {};
+    nuxt.options.runtimeConfig.logger = {
+      ...nuxt.options.runtimeConfig.logger,
+      otel: { ...otel, ignorePaths: [.../* @__PURE__ */ new Set([...ignorePaths, clientErrorEndpoint])] }
+    };
     if (options.enableRequestLogging) {
       addServerHandler({
         handler: resolver.resolve("./runtime/middleware/logger.server"),
@@ -52,6 +68,14 @@ const module = defineNuxtModule({
         handler: resolver.resolve("./runtime/server/routes/client-error.post")
       });
     }
+    if (otelEnabled) {
+      addServerPlugin(resolver.resolve("./runtime/server/otel/plugin"));
+      addPlugin({
+        src: resolver.resolve("./runtime/plugins/otelPageName.server"),
+        mode: "server"
+      });
+    }
+    addServerPlugin(resolver.resolve("./runtime/server/contextPlugin"));
   }
 });
 

package/dist/runtime/plugins/otelPageName.server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Назва роута сторінки для server span'а (див. resolvedRouteName у serverSpan).
+ *
+ * `router.resolve`, а не `afterEach`: початкова навігація SSR відбувається ще в
+ * плагіні роутера Nuxt, до цього плагіна, і може впасти в route middleware
+ * (404, редирект) — тоді `currentRoute` лишається порожнім. Resolve лише
+ * зіставляє URL з таблицею роутів, незалежно від результату навігації.
+ * Аліаси (`/widgets/weather` → `index`) дають назву основного роута.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/plugins/otelPageName.server.js

@@ -0,0 +1,12 @@
+import { defineNuxtPlugin, useRequestEvent } from "#imports";
+const I18N_SEPARATOR = "___";
+export default defineNuxtPlugin((nuxtApp) => {
+  const event = useRequestEvent();
+  const url = nuxtApp.ssrContext?.url;
+  if (!event?.context.otelSpan || !url) return;
+  const name = nuxtApp.$router.resolve(url).name;
+  if (typeof name !== "string") return;
+  const [baseName, locale] = name.split(I18N_SEPARATOR);
+  event.context.otelPageName = baseName;
+  if (locale) event.context.otelSpan.setAttribute("i18n.locale", locale);
+});

package/dist/runtime/server/contextPlugin.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Весь pipeline запиту (middleware, handler, SSR-рендер) — всередині
+ * AsyncLocalStorage з його подією, див. requestContext.ts. Той самий прийом,
+ * що й `experimental.asyncContext` у Nitro: toNodeListener і localFetch читають
+ * `h3App.handler` на кожен запит.
+ */
+declare const _default: import("nitropack").NitroAppPlugin;
+export default _default;

package/dist/runtime/server/contextPlugin.js

@@ -0,0 +1,6 @@
+import { defineNitroPlugin } from "nitropack/runtime";
+import { runInRequestContext } from "./requestContext.js";
+export default defineNitroPlugin((nitroApp) => {
+  const handler = nitroApp.h3App.handler;
+  nitroApp.h3App.handler = (event) => runInRequestContext(event, () => handler(event));
+});

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

@@ -0,0 +1,15 @@
+/** Серіалізована форма `logger.otel` з nuxt.config (див. module.ts). */
+export interface OtelRuntimeConfig {
+    ignorePaths?: string[];
+    ignoreStaticAssets?: boolean;
+    ignoreUserAgents?: string[];
+}
+export interface OtelSettings {
+    ignorePaths: string[];
+    ignoreStaticAssets: boolean;
+    ignoreUserAgent?: RegExp;
+}
+export declare const TRACER_NAME = "hotelme-nuxt-logger";
+export declare function otelRuntimeConfig(): OtelRuntimeConfig;
+/** Регекспи компілюються один раз, на першому запиті. */
+export declare function otelSettings(): OtelSettings;

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

@@ -0,0 +1,17 @@
+import { useRuntimeConfig } from "#imports";
+export const TRACER_NAME = "hotelme-nuxt-logger";
+export function otelRuntimeConfig() {
+  return useRuntimeConfig().logger?.otel ?? {};
+}
+let settings;
+export function otelSettings() {
+  if (settings) return settings;
+  const config = otelRuntimeConfig();
+  const userAgents = (config.ignoreUserAgents ?? []).filter(Boolean);
+  settings = {
+    ignorePaths: config.ignorePaths ?? [],
+    ignoreStaticAssets: config.ignoreStaticAssets ?? true,
+    ignoreUserAgent: userAgents.length ? new RegExp(userAgents.map((ua) => `(?:${ua})`).join("|"), "i") : void 0
+  };
+  return settings;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Tracer provider з OTLP gRPC експортером.
+ *
+ * Env, які SDK читає сам:
+ * - 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)
+ *
+ * Root trace id — з `X-Request-ID`, див. requestTraceId.ts.
+ *
+ * service.name: env OTEL_SERVICE_NAME → `logger.projectName`.
+ */
+declare const _default: import("nitropack").NitroAppPlugin;
+export default _default;

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

@@ -0,0 +1,81 @@
+import { defineNitroPlugin } from "nitropack/runtime";
+import { useRuntimeConfig } from "#imports";
+import { context, diag, DiagLogLevel, propagation, trace } from "@opentelemetry/api";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
+import { logger } from "../../logger.js";
+import { currentRequestEvent, requestIdOf } from "../requestContext.js";
+import { serverSpanContext } from "./serverSpan.js";
+import { requestIdGenerator } from "./requestTraceId.js";
+const diagLogger = {
+  error: (message, ...args) => logger.error("otel_diag", { error: message, args }),
+  warn: (message, ...args) => logger.warn("otel_diag", { error: message, args }),
+  info: () => {
+  },
+  debug: () => {
+  },
+  verbose: () => {
+  }
+};
+function hasHeader(request, name) {
+  const { headers } = request;
+  if (typeof headers === "string") return new RegExp(`(^|\\r\\n)${name}:`, "i").test(headers);
+  for (let i = 0; i < headers.length; i += 2) {
+    if (String(headers[i]).toLowerCase() === name) return true;
+  }
+  return false;
+}
+function undiciInstrumentation() {
+  return new UndiciInstrumentation({
+    requireParentforSpans: true,
+    requestHook: (span, request) => {
+      span.updateName(`${request.method} ${new URL(request.origin).hostname}`);
+      const reqid = requestIdOf(currentRequestEvent());
+      if (reqid && !hasHeader(request, "x-request-id")) request.addHeader("x-request-id", reqid);
+    }
+  });
+}
+export default defineNitroPlugin((nitroApp) => {
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (!endpoint) {
+    logger.warn("otel_disabled", { error: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT not set" });
+    return;
+  }
+  diag.setLogger(diagLogger, DiagLogLevel.WARN);
+  const serviceName = process.env.OTEL_SERVICE_NAME || String(useRuntimeConfig().public.projectName || "hotelme");
+  const spanProcessor = new BatchSpanProcessor(new OTLPTraceExporter(), {
+    maxQueueSize: 2048,
+    maxExportBatchSize: 512,
+    scheduledDelayMillis: 5e3,
+    exportTimeoutMillis: 1e4
+  });
+  const provider = new NodeTracerProvider({
+    resource: resourceFromAttributes({ "service.name": serviceName }),
+    spanProcessors: [spanProcessor],
+    idGenerator: requestIdGenerator
+  });
+  provider.register();
+  const unregisterInstrumentations = registerInstrumentations({
+    tracerProvider: provider,
+    instrumentations: [undiciInstrumentation()]
+  });
+  const handler = nitroApp.h3App.handler;
+  nitroApp.h3App.handler = (event) => context.with(serverSpanContext(event), () => handler(event));
+  nitroApp.hooks.hook("close", async () => {
+    unregisterInstrumentations();
+    try {
+      await provider.shutdown();
+    } catch (error) {
+      logger.error("otel_shutdown_failed", { error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      trace.disable();
+      propagation.disable();
+      context.disable();
+    }
+  });
+  logger.info("otel_initialized", { service: serviceName, endpoint });
+});

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

@@ -0,0 +1,10 @@
+import { type IdGenerator } from '@opentelemetry/sdk-trace-base';
+/**
+ * Trace id як у libwts3: `X-Request-ID` поточного запиту без дефісів
+ * (`2e285875-f20c-4c86-b6c0-dead22613ca9` → `2e285875f20c4c86b6c0dead22613ca9`),
+ * щоб reqid з логів напряму відкривав трейс. Не UUID / 32 hex — випадковий.
+ *
+ * Tracer викликає generateTraceId лише для span'а без батька, тобто server
+ * span'а запиту без вхідного `traceparent`.
+ */
+export declare const requestIdGenerator: IdGenerator;

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

@@ -0,0 +1,11 @@
+import { isValidTraceId } from "@opentelemetry/api";
+import { RandomIdGenerator } from "@opentelemetry/sdk-trace-base";
+import { currentRequestEvent, requestIdOf } from "../requestContext.js";
+const random = new RandomIdGenerator();
+export const requestIdGenerator = {
+  generateTraceId: () => {
+    const traceId = requestIdOf(currentRequestEvent())?.replace(/-/g, "").toLowerCase();
+    return traceId && /^[0-9a-f]{32}$/.test(traceId) && isValidTraceId(traceId) ? traceId : random.generateTraceId();
+  },
+  generateSpanId: () => random.generateSpanId()
+};

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

@@ -0,0 +1,26 @@
+import { type H3Event } from 'h3';
+import { type Context } from '@opentelemetry/api';
+declare module 'h3' {
+    interface H3EventContext {
+        /** Назва роута сторінки з Vue Router, ставить plugins/otelPageName.server */
+        otelPageName?: string;
+    }
+}
+/**
+ * Контекст, у якому виконується весь pipeline запиту (див. plugin.ts).
+ *
+ * Server span з батьком із вхідного W3C `traceparent`, а для внутрішнього
+ * SSR-виклику (`$fetch('/api/…')` → localFetch) — з активного контексту
+ * сторінки: localFetch іде в тому ж async-ланцюжку, тож span роуту стає
+ * дочірнім без жодних заголовків. Без батька trace id — з `X-Request-ID`
+ * (requestIdGenerator).
+ *
+ * Відфільтровані запити (статика, ignorePaths, ignoreUserAgents) отримують
+ * невибраний контекст, а не просто відсутність span'а: інакше їхні внутрішні
+ * /api-виклики, вихідні fetch і span'и бекенда стали б осиротілими
+ * root-трейсами. Дочірні запити успадковують його через parent-based семплер.
+ *
+ * Кладе в event.context `otelSpan` (назва сторінки, `i18n.locale`), віддає
+ * `X-Trace-Id` у відповіді.
+ */
+export declare function serverSpanContext(event: H3Event): Context;

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

@@ -0,0 +1,64 @@
+import { getHeader, setResponseHeader } from "h3";
+import { context, isSpanContextValid, propagation, trace, SpanKind, SpanStatusCode, TraceFlags } from "@opentelemetry/api";
+import { isTracingSuppressed } from "@opentelemetry/core";
+import { requestIdOf } from "../requestContext.js";
+import { otelSettings, TRACER_NAME } from "./config.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) {
+  return trace.setSpanContext(active, {
+    traceId: requestIdGenerator.generateTraceId(),
+    spanId: requestIdGenerator.generateSpanId(),
+    traceFlags: TraceFlags.NONE
+  });
+}
+function resolvedRouteName(event) {
+  if (event.context.otelPageName) return event.context.otelPageName;
+  const route = event.context.matchedRoute?.path;
+  return route && route !== "/**" ? route : void 0;
+}
+export function serverSpanContext(event) {
+  const active = context.active();
+  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);
+  }
+  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 span = trace.getTracer(TRACER_NAME).startSpan(
+    `${event.method} ${pathname.startsWith("/api/") ? "/api/*" : "/*"}`,
+    {
+      kind: SpanKind.SERVER,
+      attributes: {
+        "http.request.method": event.method,
+        "url.path": pathname,
+        "url.query": query,
+        "server.address": getHeader(event, "host") ?? "",
+        "user_agent.original": userAgent
+      }
+    },
+    parentCtx
+  );
+  event.context.otelSpan = span;
+  if (isSpanContextValid(span.spanContext())) {
+    setResponseHeader(event, "X-Trace-Id", span.spanContext().traceId);
+  }
+  const res = event.node.res;
+  res.once("close", () => {
+    const route = resolvedRouteName(event);
+    if (route) span.updateName(`${event.method} ${route}`);
+    span.setAttribute("request_id", requestIdOf(event) ?? "");
+    const statusSent = res.headersSent || res.writableFinished;
+    if (statusSent) span.setAttribute("http.response.status_code", res.statusCode);
+    if (!res.writableFinished) span.setAttribute("error.type", "aborted");
+    if (statusSent && res.statusCode >= 500) span.setStatus({ code: SpanStatusCode.ERROR });
+    span.end();
+  });
+  return trace.setSpan(parentCtx, span);
+}

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

@@ -0,0 +1,14 @@
+import type { H3Event } from 'h3';
+import type { Span } from '@opentelemetry/api';
+declare module 'h3' {
+    interface H3EventContext {
+        otelSpan?: Span;
+    }
+}
+/**
+ * `X-Request-ID` сторінки для вихідного запиту — щоб access-log бекенда мав
+ * той самий id, що й `stats`/`api request` цього pod'а. Подія — явна або
+ * поточна з AsyncLocalStorage. `traceparent` тут немає: його в кожен fetch
+ * додає instrumentation-undici, другий такий заголовок зламав би зв'язок.
+ */
+export declare function traceHeaders(event?: H3Event | undefined): Record<string, string>;

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

@@ -0,0 +1,5 @@
+import { currentRequestEvent, requestIdOf } from "../requestContext.js";
+export function traceHeaders(event = currentRequestEvent()) {
+  const reqid = requestIdOf(event);
+  return reqid ? { "X-Request-ID": reqid } : {};
+}

package/dist/runtime/server/requestContext.d.ts

@@ -0,0 +1,15 @@
+import type { H3Event } from 'h3';
+/**
+ * H3-подія запиту, всередині якого виконується поточний код (middleware,
+ * handler, SSR-рендер, їхні await'и). `undefined` поза запитом.
+ */
+export declare function currentRequestEvent(): H3Event | undefined;
+/** reqid події: від logger-middleware або сирий `X-Request-ID`. */
+export declare function requestIdOf(event: H3Event | undefined): string | undefined;
+/**
+ * Запускає `handler` з подією в AsyncLocalStorage. Внутрішній SSR-виклик
+ * (`$fetch('/api/…')` → Nitro localFetch) іде в тому ж async-ланцюжку, тож тут
+ * видно батьківську подію: її reqid стає `X-Request-ID` дочірнього запиту, і
+ * logger-middleware не генерує новий.
+ */
+export declare function runInRequestContext<T>(event: H3Event, handler: () => T): T;

package/dist/runtime/server/requestContext.js

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export function currentRequestEvent() {
+  return storage.getStore();
+}
+export function requestIdOf(event) {
+  const reqid = event?.context.reqid || event?.node.req.headers["x-request-id"];
+  return typeof reqid === "string" && reqid ? reqid : void 0;
+}
+export function runInRequestContext(event, handler) {
+  const parentReqid = requestIdOf(storage.getStore());
+  if (parentReqid && !event.node.req.headers["x-request-id"]) {
+    event.node.req.headers["x-request-id"] = parentReqid;
+  }
+  return storage.run(event, handler);
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "hotelme-nuxt-logger",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Стандартний logger для Nuxt проектів з JSON виводом сумісним з бекенд-логами",
   "keywords": [
     "nuxt",
     "nuxt-module",
     "logger",
     "logging",
-    "json-logger"
+    "json-logger",
+    "opentelemetry"
   ],
   "repository": {
     "type": "git",
@@ -20,6 +21,14 @@
       "types": "./dist/types.d.ts",
       "import": "./dist/module.mjs",
       "require": "./dist/module.cjs"
+    },
+    "./runtime/logger": {
+      "types": "./dist/runtime/logger.d.ts",
+      "import": "./dist/runtime/logger.js"
+    },
+    "./runtime/otel": {
+      "types": "./dist/runtime/server/otel/tracing.d.ts",
+      "import": "./dist/runtime/server/otel/tracing.js"
     }
   },
   "main": "./dist/module.cjs",
@@ -37,7 +46,15 @@
     "test": "echo \"No tests yet\""
   },
   "dependencies": {
-    "@nuxt/kit": "^3.0.0"
+    "@nuxt/kit": "^3.0.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/core": "^2.11.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.222.0",
+    "@opentelemetry/instrumentation": "^0.222.0",
+    "@opentelemetry/instrumentation-undici": "^0.32.0",
+    "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "@opentelemetry/sdk-trace-node": "^2.11.0"
   },
   "devDependencies": {
     "@nuxt/module-builder": "^0.8.0",