@modainteract/moda-interact-shared 0.3.0 → 0.5.0

package/README.md

@@ -4,8 +4,8 @@ Shared TypeScript contracts and reusable platform primitives used by multiple
 Moda Interact services.
 
 This package is a **library**, not a deployable service. It does not own
-transport, persistence, background workers, provider SDK integration, or
-application business workflows.
+business transports, persistence, background workers, provider SDK integration,
+or application business workflows.
 
 ## Install
 
@@ -28,10 +28,152 @@ including:
 - canonical queue/job-name constants where multiple repositories must agree;
 - deterministic correlation/job identifier helpers;
 - small pure utilities used by more than one service;
-- reusable structured application logging primitives.
+- reusable structured application logging primitives;
+- the reusable base Node OpenTelemetry runtime, including tracing and metrics
+  providers, exporters, sampling, HTTP/Undici instrumentation, lifecycle, and
+  generic observability helpers.
 
 The package deliberately keeps framework and runtime dependencies small.
 
+## Node observability runtime
+
+The package provides a browser-safe semantic observability entry and a
+Node-only runtime entry:
+
+```ts
+import {
+  getActiveTraceId,
+  withObservedSpan,
+} from "@modainteract/moda-interact-shared/observability";
+
+import {
+  initNodeObservability,
+} from "@modainteract/moda-interact-shared/observability/node";
+```
+
+Import `./observability/node` only from a process preload. It installs tracing,
+metrics, HTTP/HTTPS and Undici/fetch instrumentation before framework or worker
+modules load:
+
+```text
+node --import ./observability.mjs <framework-or-worker-entrypoint>
+```
+
+```js
+// observability.mjs
+import { initNodeObservability } from
+  "@modainteract/moda-interact-shared/observability/node";
+
+initNodeObservability({
+  serviceName: "moda-interact-messaging",
+  environment: process.env.DEPLOYMENT_ENVIRONMENT_NAME,
+  instrument: { http: true, fetch: true, prisma: false },
+});
+```
+
+Set `prisma: true` only for processes that load Prisma, and keep the preload
+before the first Prisma application import.
+
+The runtime uses the canonical `service.namespace`, `service.name`, and
+`deployment.environment.name` resource attributes. It honors
+`OTEL_TRACES_SAMPLER`, ratio arguments for ratio samplers, signal-specific or
+generic OTLP endpoints, and bounded batch/export settings. With no trace or
+metric endpoint those pipelines are no-ops while structured stdout logging
+continues.
+
+`forceFlush()` covers traces, metrics, OpenTelemetry Logs, and direct Loki.
+Initialization, export, flush, and shutdown failures are best-effort and do not
+become application startup or business-operation failures.
+
+### BullMQ telemetry
+
+Create the shared BullMQ telemetry adapter once per Queue or Worker options
+object and pass it through BullMQ's native `telemetry` option:
+
+```ts
+import { createBullMQTelemetry } from
+  "@modainteract/moda-interact-shared/observability/bullmq";
+
+const telemetry = createBullMQTelemetry({
+  serviceName: "moda-messaging-worker",
+  enableMetrics: true,
+});
+
+new Worker(queueName, processor, { connection, telemetry });
+```
+
+The adapter uses the global trace and meter providers installed by the Node
+runtime. BullMQ owns propagation metadata in its job options; applications must
+not copy or mutate queue payloads solely to carry trace context. BullMQ metrics
+use queue name, bounded job name, and job state dimensions, never Moda job,
+shop, checkout, conversation, or message IDs.
+
+### GenAI active spans
+
+Use the GenAI helpers to model one inbound conversation turn as an independent
+trace with active agent, tool, and automatically instrumented child spans:
+
+```ts
+import {
+  observeAgentInvocation,
+  observeAgentTool,
+  observeConversationTurn,
+} from "@modainteract/moda-interact-shared/observability/genai";
+
+await observeConversationTurn("whatsapp", () =>
+  observeAgentInvocation({ agentName: "commerce-agent" }, () =>
+    observeAgentTool("lookup-products", executeTool),
+  ),
+);
+```
+
+Pass `recordMetrics: false` to activate a helper's span without recording its
+GenAI metrics. The option applies only to that helper invocation, so pass it to
+each nested helper whose metrics should be suppressed:
+
+```ts
+const spansOnly = { recordMetrics: false } as const;
+
+await observeConversationTurn("whatsapp", () =>
+  observeAgentInvocation({ agentName: "commerce-agent" }, () =>
+    observeAgentTool("lookup-products", executeTool, spansOnly),
+    spansOnly,
+  ),
+  spansOnly,
+);
+```
+
+An optional `mapException` callback can replace the application failure with a
+bounded telemetry-safe representation for `span.recordException`. The original
+thrown value is still rethrown unchanged. If the mapper throws or returns no
+usable fields, the exception event is omitted and the span remains `ERROR`;
+the original value is never recorded as fallback. Apply the mapper to every
+nested helper that may observe the same rethrown failure:
+
+```ts
+const safeObservation = {
+  recordMetrics: false,
+  mapException: () => ({
+    name: "ProviderError",
+    message: "Provider operation failed",
+  }),
+} as const;
+
+await observeAgentTool("lookup-products", executeTool, safeObservation);
+```
+
+The helpers use only the global tracer and meter providers installed by the
+Node runtime. They create no SDK, provider, exporter, or network request, and
+remain lightweight no-ops when providers are absent. Six module-singleton
+instruments record turn, agent, and tool duration and operation outcomes.
+Metric attributes are limited to `outcome=success|error`; turn metrics also use
+the closed `channel=whatsapp|other` vocabulary. Arbitrary agent, provider,
+model, tool, and Moda business identifiers never become metric dimensions.
+
+Agent, provider, model, and tool names are trimmed and bounded on spans only.
+Prompt, completion, message, and tool payload bodies are never accepted or
+captured by default.
+
 ## What this package does not own
 
 This package does **not** own:
@@ -42,13 +184,13 @@ This package does **not** own:
 - Shopify or Meta webhook HTTP handlers;
 - Shopify or Meta SDK integration;
 - application recovery/business logic;
-- OpenTelemetry spans or application-specific metrics;
-- OpenTelemetry tracing/metrics SDK bootstraps;
+- service/domain-specific span names, business attributes, or application
+  metrics;
 - deployment OTLP endpoint/credential wiring or observability backends;
 - Render deployment configuration.
 
-Those capabilities remain in the repository that owns the corresponding
-runtime concern.
+Those service-specific semantics and deployment concerns remain in the
+repository that owns the corresponding runtime.
 
 ---
 
@@ -503,7 +645,7 @@ not recursively written back through the shared logger.
 
 ### Loki labels and cardinality
 
-The only default Loki labels are the canonical low-cardinality identity:
+Moda explicitly configures exactly three canonical low-cardinality labels:
 
 ```text
 service_namespace
@@ -511,9 +653,15 @@ service_name
 environment
 ```
 
+`winston-loki@6.1.7` additionally adds its own low-cardinality `level` label
+to every pushed stream, so a stream carries the three Moda labels plus
+`level`. This is transport-library behaviour and does not change Moda's label
+configuration.
+
 Dynamic/high-cardinality identifiers must **not** be promoted to Loki stream
 labels. The implementation explicitly retains
-`useWinstonMetaAsLabels: false`. In particular, do not label by:
+`useWinstonMetaAsLabels: false`, so winston metadata is never promoted to
+labels. In particular, do not label by:
 
 ```text
 traceId
@@ -573,12 +721,14 @@ choice.
 - stdout and OpenTelemetry emission are isolated and best-effort: a failure in
   either must not change application/business correctness.
 
-### Tracing/metrics remain service-specific
+### Tracing/metrics ownership
 
 The shared logger does **not** create spans, counters or histograms.
 
-Service-specific OpenTelemetry tracing and metrics remain in the owning runtime
-repository, for example:
+The shared observability runtime owns the generic Node SDK, tracing and metrics
+provider mechanics, exporters, sampling, HTTP/Undici instrumentation, generic
+helpers, and lifecycle. Service repositories own their span names, business
+attributes, application-specific metrics, and domain semantics, for example:
 
 ```text
 Shopify operation
@@ -615,6 +765,19 @@ The public package exposes independent entry points.
     Node-only logging bootstrap
     (OpenTelemetry LoggerProvider, batching, OTLP HTTP exporter;
      Winston + winston-loki direct transport)
+
+@modainteract/moda-interact-shared/observability
+    browser-safe generic observability helpers
+
+@modainteract/moda-interact-shared/observability/node
+    reusable Node OpenTelemetry SDK, tracing/metrics providers, exporters,
+    sampling, HTTP/Undici instrumentation, and lifecycle
+
+@modainteract/moda-interact-shared/observability/bullmq
+    Node-only BullMQ native telemetry adapter
+
+@modainteract/moda-interact-shared/observability/genai
+    Node/runtime GenAI conversation-turn, agent, and tool active-span helpers
 ```
 
 Consumers should prefer the narrowest appropriate subpath.
@@ -631,27 +794,31 @@ Examples of repository ownership:
 - normalizes/validates Shopify events;
 - publishes the appropriate queue jobs;
 - uses the shared structured logger for generic log mechanics;
-- owns Shopify-specific observability semantics and OpenTelemetry.
+- uses the shared observability runtime for generic OpenTelemetry mechanics;
+- owns Shopify-specific observability semantics and application metrics.
 
 **moda-interact-background**
 
 - parses shared cross-service contracts before acting;
 - runs BullMQ workers and recovery workflows;
 - uses the shared logger for generic structured logging;
-- owns worker/recovery OpenTelemetry.
+- uses the shared observability runtime for generic OpenTelemetry mechanics;
+- owns worker/recovery observability semantics and application metrics.
 
 **moda-interact-messaging**
 
 - owns Meta/WhatsApp ingress;
 - uses the shared logger for generic structured logging;
-- owns Meta/WhatsApp-specific observability and OpenTelemetry.
+- uses the shared observability runtime for generic OpenTelemetry mechanics;
+- owns Meta/WhatsApp-specific observability semantics and application metrics.
 
 **moda-interact-admin**
 
 - owns the internal admin application;
 - may use the same shared logger where server-side operational logging is
   required;
-- owns admin-specific application telemetry.
+- uses the shared observability runtime for generic OpenTelemetry mechanics;
+- owns admin-specific observability semantics and application metrics.
 
 **moda-interact-database**
 

package/dist/chunk-5JNEZEKV.js

@@ -0,0 +1,374 @@
+import {
+  setLokiLogEmitter
+} from "./chunk-XU4XX7SD.js";
+
+// src/logging/node.ts
+import { logs } from "@opentelemetry/api-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  BatchLogRecordProcessor,
+  LoggerProvider
+} from "@opentelemetry/sdk-logs";
+
+// src/logging/node/loki.ts
+import {
+  createLogger as createWinstonLogger,
+  format
+} from "winston";
+import LokiTransport from "winston-loki";
+var DEFAULT_SERVICE_NAMESPACE = "moda-interact";
+var runtime = null;
+function requireNonEmpty(value, field) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+  return normalized;
+}
+function initNodeLokiLogging(options) {
+  if (runtime) {
+    return runtime;
+  }
+  const serviceName = requireNonEmpty(options.serviceName, "serviceName");
+  const environment = requireNonEmpty(options.environment, "environment");
+  const serviceNamespace = requireNonEmpty(
+    options.serviceNamespace ?? DEFAULT_SERVICE_NAMESPACE,
+    "serviceNamespace"
+  );
+  const host = nonEmpty(options.host) ?? envString("LOKI_URL");
+  const enabled = options.forceEnable === true || envBool("LOKI_ENABLED") !== false && host !== void 0;
+  const labels = Object.freeze({
+    service_namespace: serviceNamespace,
+    service_name: serviceName,
+    environment
+  });
+  if (!enabled || !host) {
+    setLokiLogEmitter(null);
+    runtime = {
+      enabled: false,
+      host: null,
+      labels,
+      forceFlush: async () => {
+      },
+      shutdown: async () => {
+      }
+    };
+    return runtime;
+  }
+  const basicAuth = nonEmpty(options.basicAuth) ?? buildBasicAuth(
+    envString("LOKI_USERNAME"),
+    envString("LOKI_PASSWORD")
+  );
+  const transport = new LokiTransport({
+    host,
+    json: true,
+    batching: options.batching ?? envBool("LOKI_BATCHING") ?? true,
+    interval: options.intervalSeconds ?? envInt("LOKI_BATCH_INTERVAL_SECONDS", 5),
+    timeout: options.timeoutMs ?? envInt("LOKI_TIMEOUT_MS", 1e4),
+    // Prefer bounded loss to unbounded memory growth when the logging backend
+    // is unavailable. Loki must never become an application dependency.
+    clearOnError: options.clearOnError ?? envBool("LOKI_CLEAR_ON_ERROR") ?? true,
+    // Current winston-loki guidance recommends keeping timestamp replacement
+    // enabled unless there is a specific reason not to.
+    replaceTimestamp: true,
+    // Moda owns flush/shutdown explicitly from the process bootstrap.
+    gracefulShutdown: false,
+    // Critical cardinality rule: only these architecture-approved static
+    // labels may be indexed. Never promote Winston meta/data to labels.
+    labels,
+    useWinstonMetaAsLabels: false,
+    ...basicAuth ? { basicAuth } : {},
+    ...options.headers ? { headers: options.headers } : {},
+    // Do not recursively log Loki connection errors through the shared logger.
+    // Doing so could create a failure loop while Loki is unavailable.
+    onConnectionError: () => {
+    }
+  });
+  const lokiLogger = createWinstonLogger({
+    level: "debug",
+    format: format.json(),
+    transports: [transport],
+    exitOnError: false
+  });
+  setLokiLogEmitter((record) => {
+    writeCanonicalRecord(lokiLogger, record);
+  });
+  runtime = {
+    enabled: true,
+    host,
+    labels,
+    forceFlush: async () => {
+      await safeFlush(transport);
+    },
+    shutdown: async () => {
+      setLokiLogEmitter(null);
+      await safeFlush(transport);
+      await safeCloseTransport(transport);
+      try {
+        lokiLogger.close();
+      } catch {
+      }
+    }
+  };
+  return runtime;
+}
+function getNodeLokiLoggingRuntime() {
+  return runtime;
+}
+function writeCanonicalRecord(logger, record) {
+  try {
+    logger.log({
+      ...record,
+      level: record.level,
+      message: record.event
+    });
+  } catch {
+  }
+}
+async function safeFlush(transport) {
+  try {
+    await transport.flush();
+  } catch {
+  }
+}
+async function safeCloseTransport(transport) {
+  try {
+    const closeable = transport;
+    if (typeof closeable.close === "function") {
+      await Promise.resolve(closeable.close());
+    }
+  } catch {
+  }
+}
+function buildBasicAuth(username, password) {
+  if (!username || !password) {
+    return void 0;
+  }
+  return `${username}:${password}`;
+}
+function envString(name) {
+  return nonEmpty(process.env[name]);
+}
+function nonEmpty(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function envBool(name) {
+  const value = envString(name);
+  if (value === void 0) {
+    return void 0;
+  }
+  const normalized = value.toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(normalized)) {
+    return false;
+  }
+  return void 0;
+}
+function envInt(name, fallback) {
+  const value = envString(name);
+  if (value === void 0) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+// src/logging/node.ts
+var DEFAULT_SERVICE_NAMESPACE2 = "moda-interact";
+var runtime2 = null;
+function requireNonEmpty2(value, field) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+  return normalized;
+}
+function initNodeOpenTelemetryLogging(options) {
+  if (runtime2) {
+    return runtime2;
+  }
+  const serviceName = requireNonEmpty2(options.serviceName, "serviceName");
+  const environment = requireNonEmpty2(options.environment, "environment");
+  const serviceNamespace = requireNonEmpty2(
+    options.serviceNamespace ?? DEFAULT_SERVICE_NAMESPACE2,
+    "serviceNamespace"
+  );
+  const config = resolveLogsConfig(options);
+  if (!config.enabled || !config.endpoint) {
+    runtime2 = {
+      enabled: false,
+      endpoint: null,
+      forceFlush: async () => {
+      },
+      shutdown: async () => {
+      }
+    };
+    return runtime2;
+  }
+  const exporter = new OTLPLogExporter({
+    url: config.endpoint,
+    headers: config.headers,
+    concurrencyLimit: envInt2("OTEL_LOG_EXPORT_CONCURRENCY_LIMIT", 2)
+  });
+  const processor = new BatchLogRecordProcessor({
+    exporter,
+    maxQueueSize: envInt2("OTEL_BLRP_MAX_QUEUE_SIZE", 2048),
+    maxExportBatchSize: envInt2("OTEL_BLRP_MAX_EXPORT_BATCH_SIZE", 512),
+    scheduledDelayMillis: envInt2("OTEL_BLRP_SCHEDULE_DELAY", 1e3),
+    exportTimeoutMillis: envInt2("OTEL_BLRP_EXPORT_TIMEOUT", 3e4)
+  });
+  const provider = new LoggerProvider({
+    resource: resourceFromAttributes({
+      "service.namespace": serviceNamespace,
+      "service.name": serviceName,
+      "deployment.environment.name": environment
+    }),
+    processors: [processor],
+    logRecordLimits: {
+      attributeCountLimit: 64,
+      attributeValueLengthLimit: 4096
+    }
+  });
+  logs.setGlobalLoggerProvider(provider);
+  runtime2 = {
+    enabled: true,
+    endpoint: config.endpoint,
+    forceFlush: async () => {
+      try {
+        await provider.forceFlush();
+      } catch {
+      }
+    },
+    shutdown: async () => {
+      try {
+        await provider.shutdown();
+      } catch {
+      }
+    }
+  };
+  return runtime2;
+}
+function getNodeOpenTelemetryLoggingRuntime() {
+  return runtime2;
+}
+function resolveLogsEndpoint(explicitEndpoint) {
+  const explicit = nonEmpty2(explicitEndpoint);
+  if (explicit) {
+    return explicit;
+  }
+  const signalEndpoint = envString2("OTEL_EXPORTER_OTLP_LOGS_ENDPOINT");
+  if (signalEndpoint) {
+    return signalEndpoint;
+  }
+  const genericEndpoint = envString2("OTEL_EXPORTER_OTLP_ENDPOINT");
+  if (!genericEndpoint) {
+    return void 0;
+  }
+  const normalized = genericEndpoint.replace(/\/+$/, "");
+  if (normalized.endsWith("/v1/logs")) {
+    return normalized;
+  }
+  return `${normalized}/v1/logs`;
+}
+function parseOtlpHeaders(value) {
+  const raw = nonEmpty2(value);
+  if (!raw) {
+    return void 0;
+  }
+  const headers = {};
+  for (const part of raw.split(",")) {
+    const separator = part.indexOf("=");
+    if (separator <= 0) {
+      continue;
+    }
+    const rawKey = part.slice(0, separator).trim();
+    const rawValue = part.slice(separator + 1).trim();
+    if (!rawKey) {
+      continue;
+    }
+    headers[safeDecodeURIComponent(rawKey)] = safeDecodeURIComponent(rawValue);
+  }
+  return Object.keys(headers).length > 0 ? headers : void 0;
+}
+function resolveLogsConfig(options) {
+  if (!options.forceEnable && envBool2("OTEL_SDK_DISABLED") === true) {
+    return {
+      enabled: false,
+      endpoint: void 0,
+      headers: void 0
+    };
+  }
+  const exporterName = envString2("OTEL_LOGS_EXPORTER") ?? "otlp";
+  if (!options.forceEnable && exporterName !== "otlp") {
+    return {
+      enabled: false,
+      endpoint: void 0,
+      headers: void 0
+    };
+  }
+  const endpoint = resolveLogsEndpoint(options.endpoint);
+  if (!endpoint) {
+    return {
+      enabled: false,
+      endpoint: void 0,
+      headers: void 0
+    };
+  }
+  const headers = options.headers ?? parseOtlpHeaders(
+    envString2("OTEL_EXPORTER_OTLP_LOGS_HEADERS") ?? envString2("OTEL_EXPORTER_OTLP_HEADERS")
+  );
+  return {
+    enabled: true,
+    endpoint,
+    headers
+  };
+}
+function envString2(name) {
+  return nonEmpty2(process.env[name]);
+}
+function nonEmpty2(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function envBool2(name) {
+  const value = envString2(name);
+  if (value === void 0) {
+    return void 0;
+  }
+  return ["1", "true", "yes", "on"].includes(value.toLowerCase());
+}
+function envInt2(name, fallback) {
+  const value = envString2(name);
+  if (value === void 0) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export {
+  initNodeLokiLogging,
+  getNodeLokiLoggingRuntime,
+  initNodeOpenTelemetryLogging,
+  getNodeOpenTelemetryLoggingRuntime,
+  resolveLogsEndpoint,
+  parseOtlpHeaders
+};
+//# sourceMappingURL=chunk-5JNEZEKV.js.map