@vicacha-devs/strapi-plugin-opentelemetry 0.0.0-stage → 1.0.1

package/dist/server/index.mjs

@@ -0,0 +1,544 @@
+import { trace, SpanKind, SpanStatusCode, metrics } from "@opentelemetry/api";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { Resource } from "@opentelemetry/resources";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ConsoleSpanExporter, ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
+import { ATTR_SERVICE_VERSION, ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+  return value.slice(0, end);
+}
+const defaultConfig = {
+  enabled: true,
+  serviceName: "strapi",
+  serviceVersion: "1.0.0",
+  environment: process.env.NODE_ENV || "development",
+  otlpEndpoint: "",
+  otlpHeaders: {},
+  sampleRate: 1,
+  ignorePaths: ["/_health", "/favicon.ico"],
+  captureDocumentService: true,
+  consoleExporter: false,
+  metricExportIntervalMs: 6e4
+};
+function parseOtlpHeaders(raw) {
+  if (!raw || typeof raw !== "string") {
+    return {};
+  }
+  const headers = {};
+  for (const pair of raw.split(",")) {
+    const eqIdx = pair.indexOf("=");
+    if (eqIdx <= 0) continue;
+    const key = pair.slice(0, eqIdx).trim();
+    const value = pair.slice(eqIdx + 1).trim();
+    if (key) {
+      headers[key] = value;
+    }
+  }
+  return headers;
+}
+function resolveOtelConfig(rawConfig = {}) {
+  const envEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim() ?? "";
+  const envServiceName = process.env.OTEL_SERVICE_NAME?.trim() ?? "";
+  const envHeaders = parseOtlpHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS);
+  return {
+    ...defaultConfig,
+    ...rawConfig,
+    serviceName: rawConfig.serviceName || envServiceName || defaultConfig.serviceName,
+    otlpEndpoint: stripTrailingSlashes(rawConfig.otlpEndpoint || envEndpoint),
+    otlpHeaders: {
+      ...envHeaders,
+      ...rawConfig.otlpHeaders
+    },
+    ignorePaths: rawConfig.ignorePaths ?? defaultConfig.ignorePaths
+  };
+}
+function validateOtelConfig(pluginConfig) {
+  if (pluginConfig === null || typeof pluginConfig !== "object" || Array.isArray(pluginConfig)) {
+    throw new Error("OpenTelemetry plugin config must be an object");
+  }
+  const cfg = pluginConfig;
+  if (cfg.enabled !== void 0 && typeof cfg.enabled !== "boolean") {
+    throw new Error("OpenTelemetry plugin config.enabled must be a boolean");
+  }
+  if (cfg.serviceName !== void 0 && typeof cfg.serviceName !== "string") {
+    throw new Error("OpenTelemetry plugin config.serviceName must be a string");
+  }
+  if (cfg.serviceVersion !== void 0 && typeof cfg.serviceVersion !== "string") {
+    throw new Error(
+      "OpenTelemetry plugin config.serviceVersion must be a string"
+    );
+  }
+  if (cfg.environment !== void 0 && typeof cfg.environment !== "string") {
+    throw new Error("OpenTelemetry plugin config.environment must be a string");
+  }
+  if (cfg.otlpEndpoint !== void 0 && typeof cfg.otlpEndpoint !== "string") {
+    throw new Error(
+      "OpenTelemetry plugin config.otlpEndpoint must be a string"
+    );
+  }
+  if (cfg.otlpHeaders !== void 0 && (cfg.otlpHeaders === null || typeof cfg.otlpHeaders !== "object" || Array.isArray(cfg.otlpHeaders))) {
+    throw new Error(
+      "OpenTelemetry plugin config.otlpHeaders must be a key-value object"
+    );
+  }
+  if (cfg.sampleRate !== void 0 && (typeof cfg.sampleRate !== "number" || Number.isNaN(cfg.sampleRate) || cfg.sampleRate < 0 || cfg.sampleRate > 1)) {
+    throw new Error(
+      "OpenTelemetry plugin config.sampleRate must be a number between 0 and 1"
+    );
+  }
+  if (cfg.ignorePaths !== void 0 && (!Array.isArray(cfg.ignorePaths) || cfg.ignorePaths.some((p) => typeof p !== "string"))) {
+    throw new Error(
+      "OpenTelemetry plugin config.ignorePaths must be an array of strings"
+    );
+  }
+  if (cfg.captureDocumentService !== void 0 && typeof cfg.captureDocumentService !== "boolean") {
+    throw new Error(
+      "OpenTelemetry plugin config.captureDocumentService must be a boolean"
+    );
+  }
+  if (cfg.consoleExporter !== void 0 && typeof cfg.consoleExporter !== "boolean") {
+    throw new Error(
+      "OpenTelemetry plugin config.consoleExporter must be a boolean"
+    );
+  }
+  if (cfg.metricExportIntervalMs !== void 0 && (typeof cfg.metricExportIntervalMs !== "number" || cfg.metricExportIntervalMs < 1e3)) {
+    throw new Error(
+      "OpenTelemetry plugin config.metricExportIntervalMs must be a number >= 1000"
+    );
+  }
+}
+const MAX_MESSAGE_LENGTH = 1e3;
+const SENSITIVE_QUERY_KEYS = /(^|[?&])(token|access_token|refresh_token|id_token|api_key|apikey|key|secret|password|passwd|auth|signature|sig|code)=([^&\s]+)/gi;
+const BEARER_PATTERN = /\b(Bearer|Basic)\s+[A-Z0-9\-._~+/]+=*/gi;
+const EMAIL_PATTERN = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
+const MAX_INPUT_LENGTH = MAX_MESSAGE_LENGTH * 4;
+const isAlpha = (c) => c >= 65 && c <= 90 || c >= 97 && c <= 122;
+const isSchemeChar = (c) => isAlpha(c) || c >= 48 && c <= 57 || c === 43 || c === 46 || c === 45;
+const isWhitespace = (c) => c === 32 || c >= 9 && c <= 13 || c === 160 || c === 5760 || c >= 8192 && c <= 8202 || c === 8232 || c === 8233 || c === 8239 || c === 8287 || c === 12288 || c === 65279;
+function redactUrlCredentials(input) {
+  let out = "";
+  let from = 0;
+  let pos = 0;
+  for (; ; ) {
+    const idx = input.indexOf("://", pos);
+    if (idx === -1) break;
+    let start = idx;
+    while (start > from && isSchemeChar(input.charCodeAt(start - 1))) start--;
+    while (start < idx && !isAlpha(input.charCodeAt(start))) start++;
+    let end = -1;
+    if (start < idx) {
+      let i = idx + 3;
+      const userStart = i;
+      while (i < input.length) {
+        const c = input.charCodeAt(i);
+        if (c === 58 || c === 64 || isWhitespace(c)) break;
+        i++;
+      }
+      if (i > userStart && input.charCodeAt(i) === 58) {
+        i++;
+        const passStart = i;
+        while (i < input.length) {
+          const c = input.charCodeAt(i);
+          if (c === 64 || isWhitespace(c)) break;
+          i++;
+        }
+        if (i > passStart && input.charCodeAt(i) === 64) end = i + 1;
+      }
+    }
+    if (end === -1) {
+      pos = idx + 3;
+    } else {
+      out += `${input.slice(from, idx + 3)}[REDACTED]@`;
+      from = end;
+      pos = end;
+    }
+  }
+  return out + input.slice(from);
+}
+function sanitizeTelemetryText(input) {
+  if (!input) return "";
+  let sanitized = redactUrlCredentials(
+    input.slice(0, MAX_INPUT_LENGTH).replace(BEARER_PATTERN, "$1 [REDACTED]")
+  ).replace(SENSITIVE_QUERY_KEYS, "$1$2=[REDACTED]").replace(EMAIL_PATTERN, "[REDACTED_EMAIL]");
+  if (sanitized.length > MAX_MESSAGE_LENGTH) {
+    sanitized = `${sanitized.slice(0, MAX_MESSAGE_LENGTH)}...[truncated]`;
+  }
+  return sanitized;
+}
+function sanitizeError(err) {
+  const raw = err instanceof Error ? err : new Error(String(err));
+  const safeMessage = sanitizeTelemetryText(raw.message);
+  const safeError = new Error(safeMessage);
+  safeError.name = raw.name || "Error";
+  if (raw.stack) {
+    safeError.stack = sanitizeTelemetryText(raw.stack);
+  }
+  return safeError;
+}
+function extractPluginName(input) {
+  if (input.uid?.startsWith("plugin::")) {
+    const rest = input.uid.slice("plugin::".length);
+    const dotIdx = rest.indexOf(".");
+    return dotIdx > 0 ? rest.slice(0, dotIdx) : rest || void 0;
+  }
+  if (input.route) {
+    const match = /^\/(?:api\/)?([a-z0-9-]+)(?:\/|$)/i.exec(input.route);
+    if (match?.[1] && match[1] !== "api" && match[1] !== "admin") {
+      return match[1];
+    }
+  }
+  return void 0;
+}
+const TRACER_NAME$2 = "@vicacha-devs/strapi-plugin-opentelemetry";
+function registerDocumentServiceInstrumentation(documents, config) {
+  if (!config.enabled || !config.captureDocumentService || !documents?.use) {
+    return;
+  }
+  const tracer = trace.getTracer(TRACER_NAME$2, config.serviceVersion);
+  documents.use(async (context, next) => {
+    const spanName = `strapi.document.${context.action} ${context.uid}`;
+    const pluginName = extractPluginName({ uid: context.uid });
+    return tracer.startActiveSpan(
+      spanName,
+      {
+        kind: SpanKind.INTERNAL,
+        attributes: {
+          "strapi.document.uid": context.uid,
+          "strapi.document.action": context.action,
+          ...pluginName ? { "strapi.plugin": pluginName } : {}
+        }
+      },
+      async (span) => {
+        try {
+          const result = await next();
+          span.setStatus({ code: SpanStatusCode.OK });
+          return result;
+        } catch (err) {
+          const error = sanitizeError(err);
+          span.recordException(error);
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: error.message
+          });
+          throw err;
+        } finally {
+          span.end();
+        }
+      }
+    );
+  });
+}
+const WRAPPED_SYMBOL = Symbol.for("vicacha.strapi.otel.logger.wrapped");
+const TRACER_NAME$1 = "@vicacha-devs/strapi-plugin-opentelemetry";
+function instrumentStrapiLogger(logger, config) {
+  if (!config.enabled || !logger || typeof logger.error !== "function") {
+    return;
+  }
+  if (logger[WRAPPED_SYMBOL]) {
+    return;
+  }
+  const originalError = logger.error.bind(logger);
+  const tracer = trace.getTracer(TRACER_NAME$1, config.serviceVersion);
+  const meter = metrics.getMeter(TRACER_NAME$1, config.serviceVersion);
+  const loggedErrorCounter = meter.createCounter("strapi.log.errors", {
+    description: "Count of errors logged via strapi.log.error"
+  });
+  logger[WRAPPED_SYMBOL] = true;
+  logger.error = (...args) => {
+    try {
+      const firstArg = args[0];
+      if (typeof firstArg === "string" && firstArg.startsWith("[opentelemetry]")) {
+        return originalError(...args);
+      }
+      const errorObj = args.find((arg) => arg instanceof Error);
+      const safeError = errorObj ? sanitizeError(errorObj) : new Error(
+        sanitizeTelemetryText(
+          args.map((a) => typeof a === "string" ? a : "").filter(Boolean).join(" ") || "Logged error"
+        )
+      );
+      loggedErrorCounter.add(1, { "error.type": safeError.name });
+      const activeSpan = trace.getActiveSpan();
+      if (activeSpan) {
+        activeSpan.recordException(safeError);
+        activeSpan.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: safeError.message
+        });
+      } else {
+        tracer.startActiveSpan(
+          "strapi.log.error",
+          { kind: SpanKind.INTERNAL },
+          (span) => {
+            span.recordException(safeError);
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: safeError.message
+            });
+            span.end();
+          }
+        );
+      }
+    } catch {
+    }
+    return originalError(...args);
+  };
+}
+const TRACER_NAME = "@vicacha-devs/strapi-plugin-opentelemetry";
+function createOtelRequestMiddleware(config, logger) {
+  const tracer = trace.getTracer(TRACER_NAME, config.serviceVersion);
+  const meter = metrics.getMeter(TRACER_NAME, config.serviceVersion);
+  const durationHistogram = meter.createHistogram(
+    "http.server.request.duration",
+    {
+      description: "Duration of Strapi HTTP server requests in milliseconds",
+      unit: "ms"
+    }
+  );
+  const errorCounter = meter.createCounter("http.server.errors", {
+    description: "Count of failed Strapi HTTP requests (5xx or unhandled)"
+  });
+  return async function otelRequestTracker(ctx, next) {
+    if (!config.enabled || config.ignorePaths.some((prefix) => ctx.path.startsWith(prefix))) {
+      await next();
+      return;
+    }
+    const activeSpan = trace.getActiveSpan();
+    if (activeSpan) {
+      await executeWithSpan(activeSpan, ctx, next);
+      return;
+    }
+    await tracer.startActiveSpan(
+      `${ctx.method} ${ctx.path}`,
+      { kind: SpanKind.SERVER },
+      async (span) => {
+        try {
+          await executeWithSpan(span, ctx, next);
+        } finally {
+          span.end();
+        }
+      }
+    );
+  };
+  async function executeWithSpan(span, ctx, next) {
+    const startMs = performance.now();
+    span.setAttributes({
+      "http.request.method": ctx.method,
+      "url.path": ctx.path
+    });
+    try {
+      await next();
+      const route = ctx._matchedRoute || ctx.path;
+      const status = ctx.status ?? 200;
+      const pluginName = extractPluginName({ route });
+      span.setAttributes({
+        "http.route": route,
+        "http.response.status_code": status,
+        ...pluginName ? { "strapi.plugin": pluginName } : {}
+      });
+      attachUserContext(span, ctx);
+      if (status >= 500) {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: `HTTP ${status}`
+        });
+        errorCounter.add(1, {
+          "http.request.method": ctx.method,
+          "http.route": route,
+          "http.response.status_code": status,
+          ...pluginName ? { "strapi.plugin": pluginName } : {}
+        });
+      }
+      durationHistogram.record(performance.now() - startMs, {
+        "http.request.method": ctx.method,
+        "http.route": route,
+        "http.response.status_code": status,
+        ...pluginName ? { "strapi.plugin": pluginName } : {}
+      });
+    } catch (err) {
+      const error = sanitizeError(err);
+      const route = ctx._matchedRoute || ctx.path;
+      const pluginName = extractPluginName({ route });
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error.message
+      });
+      span.setAttribute("http.route", route);
+      if (pluginName) {
+        span.setAttribute("strapi.plugin", pluginName);
+      }
+      attachUserContext(span, ctx);
+      errorCounter.add(1, {
+        "http.request.method": ctx.method,
+        "http.route": route,
+        "error.type": error.name,
+        ...pluginName ? { "strapi.plugin": pluginName } : {}
+      });
+      durationHistogram.record(performance.now() - startMs, {
+        "http.request.method": ctx.method,
+        "http.route": route,
+        "error.type": error.name,
+        ...pluginName ? { "strapi.plugin": pluginName } : {}
+      });
+      const spanCtx = span.spanContext();
+      logger?.error(
+        `[opentelemetry] Unhandled request error: ${error.message}`,
+        {
+          trace_id: spanCtx.traceId,
+          span_id: spanCtx.spanId,
+          method: ctx.method,
+          path: ctx.path,
+          ...pluginName ? { plugin: pluginName } : {}
+        }
+      );
+      throw err;
+    }
+  }
+}
+function attachUserContext(span, ctx) {
+  const user = ctx.state?.user;
+  if (!user) return;
+  const userId = user.documentId ?? user.id;
+  if (userId !== void 0 && userId !== null) {
+    span.setAttribute("enduser.id", String(userId));
+  }
+}
+const SDK_SYMBOL = Symbol.for("vicacha.strapi.otel.sdk");
+const URL_ATTR_KEYS = ["url.full", "http.url", "url.query"];
+class SanitizingSpanExporter {
+  constructor(inner) {
+    this.inner = inner;
+  }
+  export(spans, resultCallback) {
+    for (const span of spans) {
+      const attrs = span.attributes;
+      for (const key of URL_ATTR_KEYS) {
+        if (typeof attrs[key] === "string") {
+          attrs[key] = sanitizeTelemetryText(attrs[key]);
+        }
+      }
+    }
+    this.inner.export(spans, resultCallback);
+  }
+  shutdown() {
+    return this.inner.shutdown();
+  }
+  forceFlush() {
+    return this.inner.forceFlush?.() ?? Promise.resolve();
+  }
+}
+function startOtelSdk(config) {
+  if (!config.enabled) {
+    return false;
+  }
+  const g = globalThis;
+  if (g[SDK_SYMBOL]) {
+    return false;
+  }
+  const resource = new Resource({
+    [ATTR_SERVICE_NAME]: config.serviceName,
+    [ATTR_SERVICE_VERSION]: config.serviceVersion,
+    "deployment.environment.name": config.environment
+  });
+  const rawTraceExporter = config.otlpEndpoint ? new OTLPTraceExporter({
+    url: `${config.otlpEndpoint}/v1/traces`,
+    headers: config.otlpHeaders
+  }) : config.consoleExporter ? new ConsoleSpanExporter() : void 0;
+  const traceExporter = rawTraceExporter ? new SanitizingSpanExporter(rawTraceExporter) : void 0;
+  const metricReader = config.otlpEndpoint ? new PeriodicExportingMetricReader({
+    exporter: new OTLPMetricExporter({
+      url: `${config.otlpEndpoint}/v1/metrics`,
+      headers: config.otlpHeaders
+    }),
+    exportIntervalMillis: config.metricExportIntervalMs
+  }) : void 0;
+  const sdk = new NodeSDK({
+    resource,
+    sampler: new ParentBasedSampler({
+      root: new TraceIdRatioBasedSampler(config.sampleRate)
+    }),
+    ...traceExporter ? { traceExporter } : {},
+    ...metricReader ? { metricReader } : {},
+    instrumentations: [
+      getNodeAutoInstrumentations({
+        "@opentelemetry/instrumentation-fs": { enabled: false },
+        "@opentelemetry/instrumentation-http": {
+          ignoreIncomingRequestHook: (req) => {
+            const url = req.url ?? "";
+            return config.ignorePaths.some((prefix) => url.startsWith(prefix));
+          }
+        }
+      })
+    ]
+  });
+  sdk.start();
+  g[SDK_SYMBOL] = sdk;
+  return true;
+}
+async function shutdownOtelSdk() {
+  const g = globalThis;
+  const sdk = g[SDK_SYMBOL];
+  if (!sdk) {
+    return;
+  }
+  delete g[SDK_SYMBOL];
+  await sdk.shutdown();
+}
+const PLUGIN_ID = "opentelemetry";
+function getPluginConfig(strapi) {
+  const raw = strapi.config.get(
+    `plugin::${PLUGIN_ID}`,
+    {}
+  );
+  return resolveOtelConfig(raw);
+}
+const index = {
+  register({ strapi }) {
+    const cfg = getPluginConfig(strapi);
+    if (!cfg.enabled) {
+      return;
+    }
+    startOtelSdk(cfg);
+    instrumentStrapiLogger(
+      strapi.log,
+      cfg
+    );
+    const requestMiddleware = createOtelRequestMiddleware(cfg, strapi.log);
+    strapi.server.use(
+      requestMiddleware
+    );
+    registerDocumentServiceInstrumentation(
+      strapi.documents,
+      cfg
+    );
+  },
+  bootstrap({ strapi }) {
+    const cfg = getPluginConfig(strapi);
+    if (cfg.enabled) {
+      strapi.log.info(
+        `[opentelemetry] Active for service "${cfg.serviceName}" (${cfg.otlpEndpoint || (cfg.consoleExporter ? "console" : "no-exporter")})`
+      );
+    }
+  },
+  async destroy() {
+    await shutdownOtelSdk();
+  },
+  config: {
+    default: defaultConfig,
+    validator: validateOtelConfig
+  },
+  middlewares: {
+    tracker: (_config, { strapi }) => {
+      const cfg = getPluginConfig(strapi);
+      return createOtelRequestMiddleware(cfg, strapi.log);
+    }
+  }
+};
+export {
+  index as default
+};

package/dist/server/logger-hook.d.ts

@@ -0,0 +1,12 @@
+import { OtelPluginConfig } from './config';
+declare const WRAPPED_SYMBOL: unique symbol;
+export interface StrapiLoggerWithError {
+    error: (...args: unknown[]) => unknown;
+    [WRAPPED_SYMBOL]?: boolean;
+}
+/**
+ * Wraps `strapi.log.error` so caught plugin/lifecycle errors that are logged
+ * without rethrowing are still recorded on the active span (or a new span).
+ */
+export declare function instrumentStrapiLogger(logger: StrapiLoggerWithError | undefined, config: OtelPluginConfig): void;
+export {};

package/dist/server/middleware.d.ts

@@ -0,0 +1,20 @@
+import { OtelPluginConfig } from './config';
+export interface KoaLikeContext {
+    method: string;
+    path: string;
+    status: number;
+    _matchedRoute?: string;
+    state?: {
+        user?: {
+            id?: string | number;
+            documentId?: string;
+        };
+    };
+}
+export interface StrapiLoggerLike {
+    error: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Enriches an active span and records HTTP metrics and errors for Strapi requests.
+ */
+export declare function createOtelRequestMiddleware(config: OtelPluginConfig, logger?: StrapiLoggerLike): (ctx: KoaLikeContext, next: () => Promise<void>) => Promise<void>;

package/dist/server/sanitize.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Linear-time equivalent of replacing
+ * /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^:@\s]+:[^@\s]+@)/g with "$1[REDACTED]@"
+ * (that pattern rescans long scheme-like runs from every start position).
+ */
+export declare function redactUrlCredentials(input: string): string;
+/**
+ * Redacts common secrets, credentials, tokens, and email addresses from telemetry text.
+ */
+export declare function sanitizeTelemetryText(input: string): string;
+/**
+ * Normalizes and sanitizes an unknown thrown value into a safe Error instance for span recording.
+ */
+export declare function sanitizeError(err: unknown): Error;
+/**
+ * Extracts a Strapi plugin name from a content-type UID (e.g. `plugin::bookings.booking`)
+ * or a route path (e.g. `/api/bookings/slots`).
+ */
+export declare function extractPluginName(input: {
+    uid?: string;
+    route?: string;
+}): string | undefined;

package/dist/server/sdk.d.ts

@@ -0,0 +1,10 @@
+import { OtelPluginConfig } from './config';
+/**
+ * Starts the OpenTelemetry NodeSDK once per process.
+ * Returns `true` if a new SDK instance was started, `false` if already running or disabled.
+ */
+export declare function startOtelSdk(config: OtelPluginConfig): boolean;
+/**
+ * Flushes and shuts down the active OpenTelemetry NodeSDK instance, if any.
+ */
+export declare function shutdownOtelSdk(): Promise<void>;