@open-mercato/queue 0.6.7-develop.6828.1.ab1620a63e → 0.6.7-develop.6842.1.8cd8a8883c

package/src/strategies/local.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import crypto from 'node:crypto'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import type { Queue, QueuedJob, JobHandler, LocalQueueOptions, ProcessOptions, ProcessResult, EnqueueOptions, QueueJobScope } from '../types'
+import { attachTraceMetadata, runJobInTrace } from '../tracing'
 
 const packageLogger = createLogger('queue')
 
@@ -205,11 +206,13 @@ export function createLocalQueue<T = unknown>(
     const availableAt = options?.delayMs && options.delayMs > 0
       ? new Date(Date.now() + options.delayMs).toISOString()
       : undefined
+    const metadata = attachTraceMetadata(undefined)
     const job: StoredJob<T> = {
       id: generateId(),
       payload: data,
       createdAt: new Date().toISOString(),
       ...(availableAt ? { availableAt } : {}),
+      ...(metadata ? { metadata } : {}),
     }
     await withFileLock(async () => {
       const jobs = await readQueue()
@@ -255,12 +258,14 @@ export function createLocalQueue<T = unknown>(
       for (const job of jobsToProcess) {
         const attemptNumber = (job.attemptCount ?? 0) + 1
         try {
-          await Promise.resolve(
-            handler(job, {
-              jobId: job.id,
-              attemptNumber,
-              queueName: name,
-            })
+          await runJobInTrace(name, job.metadata, () =>
+            Promise.resolve(
+              handler(job, {
+                jobId: job.id,
+                attemptNumber,
+                queueName: name,
+              })
+            )
           )
           processed++
           lastJobId = job.id

package/src/tracing.ts

@@ -0,0 +1,58 @@
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+
+/**
+ * Distributed-trace propagation across the enqueue → worker boundary.
+ *
+ * The W3C trace carrier rides on the job's `metadata._trace` (a first-class
+ * metadata channel, not the user payload). Both halves are automatic — the
+ * strategies call `attachTraceMetadata` at enqueue and `runJobInTrace` at
+ * dispatch — so a worker joins the enqueuing request's trace with no per-worker
+ * code. Everything here is a cheap no-op when telemetry is off.
+ *
+ * This also covers anything that rides the queue: persistent event subscribers
+ * (the event bus enqueues) and outbound webhook delivery (queued) become part of
+ * the originating request's trace for free.
+ */
+const TRACE_META_KEY = '_trace'
+
+/**
+ * Attach the active trace context to a job's metadata. Returns `metadata`
+ * unchanged when telemetry is off (no active span → empty carrier), so jobs stay
+ * clean unless tracing is active.
+ */
+export function attachTraceMetadata(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  const carrier = getTelemetryRuntime()?.captureTraceContext() ?? {}
+  if (Object.keys(carrier).length === 0) return metadata
+  return { ...(metadata ?? {}), [TRACE_META_KEY]: carrier }
+}
+
+/**
+ * Run a job handler inside a span (`queue.<queueName>`) that continues the
+ * producer's trace from the carrier on `metadata`. With no carrier (or telemetry
+ * off) it runs `fn` under a fresh root span — and a no-op when off. The span
+ * ends when `fn` settles (sync or async).
+ */
+export function runJobInTrace<T>(
+  queueName: string,
+  metadata: Record<string, unknown> | undefined,
+  fn: () => T,
+): T {
+  const runtime = getTelemetryRuntime()
+  if (!runtime) return fn()
+  return runtime.continueTrace(
+    readTraceCarrier(metadata),
+    `queue.${queueName}`,
+    fn,
+    { kind: 'consumer' },
+  )
+}
+
+function readTraceCarrier(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, string> | undefined {
+  const raw = metadata?.[TRACE_META_KEY]
+  if (!raw || typeof raw !== 'object') return undefined
+  return raw as Record<string, string>
+}

package/src/types.ts

@@ -81,6 +81,8 @@ export type RedisConnectionOptions = {
   db?: number
   /** TLS configuration for rediss / encrypted Redis */
   tls?: Record<string, unknown>
+  /** IP family used by Redis DNS resolution */
+  family?: number
 }
 
 /**

package/src/worker/runner.ts

@@ -1,5 +1,9 @@
 import { createQueue } from '../factory'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  getTelemetryRuntime,
+  isTelemetryBackendEnabled,
+} from '@open-mercato/shared/lib/telemetry/runtime'
 import type { Queue, JobHandler, AsyncQueueOptions, QueueStrategyType } from '../types'
 
 const logger = createLogger('queue').child({ component: 'worker' })
@@ -71,6 +75,17 @@ function registerShutdownHandlers(): void {
     unregisterShutdownHandlers(sigtermHandler, sigintHandler)
     shutdownInProgress = false
 
+    // Flush buffered spans/logs before the process dies. A worker never returns
+    // from run(), so bin.ts's post-run shutdownTelemetry() is unreachable on this
+    // path — without this, the BatchSpanProcessor's ~5s tail is dropped on every
+    // restart/redeploy. Idempotent and a no-op when telemetry is off; a flush
+    // failure must not turn a clean shutdown into a failed one.
+    try {
+      await getTelemetryRuntime()?.shutdown()
+    } catch (error) {
+      logger.error('Error flushing telemetry during shutdown', { err: error })
+    }
+
     if (!hasError) {
       logger.info('Worker closed successfully')
     }
@@ -141,6 +156,15 @@ export async function runWorker<T = unknown>(
     strategy: strategyOption,
   } = options
 
+  // Worker processes don't run Next's instrumentation hook, so initialize
+  // telemetry here — this is the single bootstrap every standalone worker passes
+  // through. Import the telemetry package only for an explicit enabled backend;
+  // with the default/unset backend the worker never evaluates the package.
+  if (!getTelemetryRuntime() && isTelemetryBackendEnabled()) {
+    const { initTelemetry } = await import('@open-mercato/telemetry')
+    await initTelemetry()
+  }
+
   // Determine queue strategy from option, env var, or default to 'local'
   const strategy: QueueStrategyType = strategyOption
     ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')