azify-logger 1.0.45 → 1.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azify-logger",
-  "version": "1.0.45",
+  "version": "1.0.46",
   "description": "Azify Logger Client - Centralized logging for OpenSearch",
   "main": "index.js",
   "types": "index.d.ts",
@@ -65,6 +65,7 @@
     "passport": "^0.6.0",
     "passport-azure-ad": "^4.3.5",
     "require-in-the-middle": "^7.4.0",
+    "semver": "7.5.2",
     "uuid": "^9.0.1"
   },
   "overrides": {
@@ -73,10 +74,13 @@
     "@opentelemetry/resources": "1.0.1",
     "@opentelemetry/semantic-conventions": "1.0.1",
     "@opentelemetry/sdk-node": "0.27.0",
-    "@opentelemetry/auto-instrumentations-node": "0.27.0"
+    "@opentelemetry/auto-instrumentations-node": "0.27.0",
+    "@opentelemetry/resource-detector-gcp": {
+      "semver": "7.5.2"
+    }
   },
   "engines": {
-    "node": ">=12 <=22"
+    "node": ">=20 <=22"
   },
   "bin": {
     "azify-logger-worker": "scripts/redis-worker.js"
@@ -91,6 +95,7 @@
     "init.js",
     "register.js",
     "store.js",
+    "store.d.ts",
     "register-otel.js",
     "register-restify.js",
     "middleware-restify.js",

package/register.js

@@ -1137,21 +1137,24 @@ try {
               const traceCtx = ctx || otelCtx
               const method = (options?.method || 'GET').toUpperCase()
               const urlString = typeof url === 'string' ? url : (url && url.toString && url.toString()) || 'unknown'
-              const rawTraceId = traceCtx?.traceId || (require('crypto').randomUUID && require('crypto').randomUUID())
+              const existingHeaders = (options && options.headers && typeof options.headers === 'object') ? options.headers : {}
+              const headerTraceId = existingHeaders['x-trace-id'] || existingHeaders['X-Trace-ID'] || null
+              const headerSpanId = existingHeaders['x-span-id'] || existingHeaders['X-Span-ID'] || null
+              const headerParentSpanId = existingHeaders['x-parent-span-id'] || existingHeaders['X-Parent-Span-ID'] || null
+              const headerRequestId = existingHeaders['x-request-id'] || existingHeaders['X-Request-ID'] || null
+              const rawTraceId = headerTraceId || traceCtx?.traceId || (require('crypto').randomUUID && require('crypto').randomUUID())
               const traceId = typeof rawTraceId === 'string' ? toTraceIdHex(rawTraceId) : rawTraceId
-              const parentSpanId = traceCtx?.spanId || null
-              const requestId = traceCtx?.requestId || ctx?.requestId || (require('crypto').randomUUID && require('crypto').randomUUID())
-              const spanId = randomBytes(8).toString('hex')
+              const parentSpanId = headerParentSpanId || traceCtx?.spanId || null
+              const requestId = headerRequestId || traceCtx?.requestId || ctx?.requestId || (require('crypto').randomUUID && require('crypto').randomUUID())
+              const spanId = headerSpanId || randomBytes(8).toString('hex')
               const requestMeta = { traceId, spanId, parentSpanId, requestId, method, url: urlString }
               markSource(requestMeta, 'http-client')
               const startTime = performance.now()
               if (HTTP_CLIENT_MODE !== 'off') {
                 sendOutboundLog('info', `[REQUEST] ${method} ${urlString}`, requestMeta)
               }
-              if (traceCtx && traceCtx.traceId) {
-                const headers = (options && options.headers) || {}
-                options = { ...options, headers: { ...headers, 'X-Trace-ID': traceId, 'X-Span-ID': spanId, 'X-Parent-Span-ID': traceCtx.parentSpanId || '', 'X-Request-ID': requestId } }
-              }
+              const headers = (options && options.headers && typeof options.headers === 'object') ? options.headers : {}
+              options = { ...options, headers: { ...headers, 'X-Trace-ID': traceId, 'X-Span-ID': spanId, 'X-Parent-Span-ID': parentSpanId || '', 'X-Request-ID': requestId } }
               const wrappedCb = callback ? function(err, data) {
                 const duration = Number((performance.now() - startTime).toFixed(2))
                 if (HTTP_CLIENT_MODE !== 'off') {
@@ -1203,19 +1206,24 @@ try {
               const origin = (opts && opts.origin) || ''
               const path = (opts && opts.path) != null ? opts.path : '/'
               const urlString = origin ? (origin + (path.startsWith('/') ? path : '/' + path)) : 'unknown'
-              const rawTraceId = traceCtx?.traceId || (require('crypto').randomUUID && require('crypto').randomUUID())
+              const existingHeaders = (opts && opts.headers && typeof opts.headers === 'object') ? opts.headers : {}
+              const headerTraceId = existingHeaders['x-trace-id'] || existingHeaders['X-Trace-ID'] || null
+              const headerSpanId = existingHeaders['x-span-id'] || existingHeaders['X-Span-ID'] || null
+              const headerParentSpanId = existingHeaders['x-parent-span-id'] || existingHeaders['X-Parent-Span-ID'] || null
+              const headerRequestId = existingHeaders['x-request-id'] || existingHeaders['X-Request-ID'] || null
+              const rawTraceId = headerTraceId || traceCtx?.traceId || (require('crypto').randomUUID && require('crypto').randomUUID())
               const traceId = typeof rawTraceId === 'string' ? toTraceIdHex(rawTraceId) : rawTraceId
-              const parentSpanId = traceCtx?.spanId || null
-              const requestId = traceCtx?.requestId || ctx?.requestId || (require('crypto').randomUUID && require('crypto').randomUUID())
-              const spanId = randomBytes(8).toString('hex')
+              const parentSpanId = headerParentSpanId || traceCtx?.spanId || null
+              const requestId = headerRequestId || traceCtx?.requestId || ctx?.requestId || (require('crypto').randomUUID && require('crypto').randomUUID())
+              const spanId = headerSpanId || randomBytes(8).toString('hex')
               const requestMeta = { traceId, spanId, parentSpanId, requestId, method: methodStr, url: urlString }
               markSource(requestMeta, 'http-client')
               const startTime = performance.now()
               if (HTTP_CLIENT_MODE !== 'off') {
                 sendOutboundLog('info', `[REQUEST] ${methodStr} ${urlString}`, requestMeta)
               }
-              if (traceCtx && traceCtx.traceId && opts && typeof opts === 'object') {
-                const headers = { ...(opts.headers || {}), 'X-Trace-ID': traceId, 'X-Span-ID': spanId, 'X-Parent-Span-ID': traceCtx.parentSpanId || '', 'X-Request-ID': requestId }
+              if (opts && typeof opts === 'object') {
+                const headers = { ...(opts.headers || {}), 'X-Trace-ID': traceId, 'X-Span-ID': spanId, 'X-Parent-Span-ID': parentSpanId || '', 'X-Request-ID': requestId }
                 opts = { ...opts, headers }
               }
               const wrappedCb = typeof callback === 'function' ? function(err, data) {
@@ -1273,19 +1281,24 @@ try {
                     const origin = (opts && opts.origin) || ''
                     const path = (opts && opts.path) != null ? opts.path : '/'
                     const urlString = origin ? (origin + (path.startsWith('/') ? path : '/' + path)) : 'unknown'
-                    const rawTraceId = traceCtx?.traceId || (require('crypto').randomUUID && require('crypto').randomUUID())
+                    const existingHeaders = (opts && opts.headers && typeof opts.headers === 'object') ? opts.headers : {}
+                    const headerTraceId = existingHeaders['x-trace-id'] || existingHeaders['X-Trace-ID'] || null
+                    const headerSpanId = existingHeaders['x-span-id'] || existingHeaders['X-Span-ID'] || null
+                    const headerParentSpanId = existingHeaders['x-parent-span-id'] || existingHeaders['X-Parent-Span-ID'] || null
+                    const headerRequestId = existingHeaders['x-request-id'] || existingHeaders['X-Request-ID'] || null
+                    const rawTraceId = headerTraceId || traceCtx?.traceId || (require('crypto').randomUUID && require('crypto').randomUUID())
                     const traceId = typeof rawTraceId === 'string' ? toTraceIdHex(rawTraceId) : rawTraceId
-                    const parentSpanId = traceCtx?.spanId || null
-                    const requestId = traceCtx?.requestId || ctx?.requestId || (require('crypto').randomUUID && require('crypto').randomUUID())
-                    const spanId = randomBytes(8).toString('hex')
+                    const parentSpanId = headerParentSpanId || traceCtx?.spanId || null
+                    const requestId = headerRequestId || traceCtx?.requestId || ctx?.requestId || (require('crypto').randomUUID && require('crypto').randomUUID())
+                    const spanId = headerSpanId || randomBytes(8).toString('hex')
                     const requestMeta = { traceId, spanId, parentSpanId, requestId, method: methodStr, url: urlString }
                     markSource(requestMeta, 'http-client')
                     const startTime = performance.now()
                     if (HTTP_CLIENT_MODE !== 'off') {
                       sendOutboundLog('info', `[REQUEST] ${methodStr} ${urlString}`, requestMeta)
                     }
-                    if (traceCtx && traceCtx.traceId && opts && typeof opts === 'object') {
-                      const headers = { ...(opts.headers || {}), 'X-Trace-ID': traceId, 'X-Span-ID': spanId, 'X-Parent-Span-ID': traceCtx.parentSpanId || '', 'X-Request-ID': requestId }
+                    if (opts && typeof opts === 'object') {
+                      const headers = { ...(opts.headers || {}), 'X-Trace-ID': traceId, 'X-Span-ID': spanId, 'X-Parent-Span-ID': parentSpanId || '', 'X-Request-ID': requestId }
                       opts = { ...opts, headers }
                     }
                     const wrappedCb = typeof callback === 'function' ? function(err, data) {

package/server.js

@@ -1697,14 +1697,14 @@ async function registerAlertRulesForApp(appName, rules, options = {}) {
 }
 
 function generateTraceId() {
-  return Math.random().toString(36).substring(2, 15) +
-         Math.random().toString(36).substring(2, 15)
+  return require('crypto').randomBytes(16).toString('hex')
 }
 
 function generateSpanId() {
-  return Math.random().toString(36).substring(2, 15)
+  return require('crypto').randomBytes(8).toString('hex')
 }
 
+
 function getOrCreateTraceContext(requestId) {
   if (traceContextMap.has(requestId)) {
     return traceContextMap.get(requestId)
@@ -1859,12 +1859,12 @@ async function handleLog(req, res) {
 
   let traceContext = null
 
-  if (meta && meta.traceId && meta.spanId) {
+  if (meta && meta.traceId) {
     const tid = toTraceIdHex32(meta.traceId)
     if (tid) {
       traceContext = {
         traceId: tid,
-        spanId: String(meta.spanId).slice(0, 16),
+        spanId: meta.spanId != null && meta.spanId !== '' ? String(meta.spanId).slice(0, 16) : generateSpanId(),
         parentSpanId: meta.parentSpanId != null && meta.parentSpanId !== '' ? String(meta.parentSpanId) : null
       }
     }
@@ -2054,7 +2054,57 @@ async function handleLog(req, res) {
 
   res.json({ success: true, message: 'Log enviado com sucesso', index: indexName })
 
-  _enqueueOpenSearchWrite(osUrl, indexName, logEntry, serviceName)
+  const docToSend = _trimLogEntryForOpenSearch(logEntry)
+  _enqueueOpenSearchWrite(osUrl, indexName, docToSend, serviceName)
+}
+
+const _opensearchMaxFields = Math.min(Number(process.env.AZIFY_LOGGER_OPENSEARCH_MAX_FIELDS) || 0, 2000) || 900
+
+function _countFields(obj, depth = 0) {
+  if (depth > 15) return 0
+  if (obj == null || typeof obj !== 'object') return 1
+  let n = 0
+  for (const key of Object.keys(obj)) {
+    const v = obj[key]
+    if (v != null && typeof v === 'object' && !Array.isArray(v) && !Buffer.isBuffer(v)) n += _countFields(v, depth + 1)
+    else n += 1
+  }
+  return n
+}
+
+function _stringifyValue(value) {
+  try {
+    return typeof value === 'object' ? JSON.stringify(value) : String(value)
+  } catch (_) {
+    return '[Unable to serialize]'
+  }
+}
+
+function _trimLogEntryForOpenSearch(doc) {
+  if (_countFields(doc) <= _opensearchMaxFields) return doc
+  const out = {}
+  for (const key of Object.keys(doc)) {
+    const value = doc[key]
+    if (value != null && typeof value === 'object' && !Array.isArray(value) && !Buffer.isBuffer(value)) {
+      if (_countFields(value) > 80) {
+        out[key + 'Json'] = _stringifyValue(value)
+      } else {
+        out[key] = value
+      }
+    } else {
+      out[key] = value
+    }
+  }
+  if (_countFields(out) > _opensearchMaxFields) {
+    for (const k of Object.keys(out)) {
+      const v = out[k]
+      if (v != null && typeof v === 'object' && !Array.isArray(v) && !Buffer.isBuffer(v)) {
+        out[k + 'Json'] = _stringifyValue(v)
+        delete out[k]
+      }
+    }
+  }
+  return out
 }
 
 const _openSearchWriteQueue = []
@@ -2072,23 +2122,82 @@ const _logDedupeWindowMs = 5000
 const _logDedupeMaxKeys = 15000
 const _logDedupeSeen = new Map()
 const _logDedupeBucketMs = 80
+const _logDedupeGenericBucketMs = 250
+
+function _normalizeReqResMessageForDedupe(msg) {
+  const s = typeof msg === 'string' ? msg : String(msg || '')
+  return s.replace(/\s+\d+(\.\d+)?ms\s*$/i, '').trimEnd()
+}
+
+function _httpClientDedupeFingerprint(logEntry) {
+  if (!logEntry || logEntry.source !== 'http-client') return null
+  const msg = typeof logEntry.message === 'string' ? logEntry.message.substring(0, 500) : String(logEntry.message || '')
+  const msgLower = msg.trimStart().toLowerCase()
+  const isReq = msgLower.startsWith('[request]')
+  const isRes = msgLower.startsWith('[response]')
+  if (!isReq && !isRes) return null
+
+  const methodRaw =
+    (logEntry.method != null && String(logEntry.method).trim()) ||
+    (logEntry.request && logEntry.request.method != null && String(logEntry.request.method).trim()) ||
+    ''
+  const m = methodRaw.toUpperCase()
+  let url = ''
+  if (logEntry.url != null && String(logEntry.url).trim()) {
+    url = String(logEntry.url).trim()
+  } else if (logEntry.request && typeof logEntry.request === 'object') {
+    url = String(logEntry.request.url || logEntry.request.path || '').trim()
+  }
+  if (!m || !url) return null
+
+  if (isReq) {
+    return `REQUEST|${m}|${url}`
+  }
+  let st = logEntry.statusCode != null ? String(logEntry.statusCode).trim() : ''
+  if (!st && /\bERROR\b/i.test(msg)) {
+    st = 'ERR'
+  }
+  if (!st) {
+    const mStatus = msg.match(/\s(\d{3})\s+(?:\d+(?:\.\d+)?ms\s*)?$/i)
+    if (mStatus) st = mStatus[1]
+  }
+  return `RESPONSE|${m}|${url}|${st || 'na'}`
+}
 
 function _logDedupeKey(serviceName, logEntry) {
   const msg = typeof logEntry.message === 'string' ? logEntry.message.substring(0, 500) : String(logEntry.message || '')
-  const msgLower = msg.toLowerCase()
+  const msgLower = msg.trimStart().toLowerCase()
   const isReqRes = msgLower.includes('[request]') || msgLower.includes('[response]')
   const traceId = logEntry.traceId != null ? String(logEntry.traceId).trim() : ''
   const spanId = logEntry.spanId != null ? String(logEntry.spanId).trim() : ''
+  const msgNorm = _normalizeReqResMessageForDedupe(msg)
+  const msgSig = msgNorm.length > 200 ? msgNorm.slice(0, 200) : msgNorm
   if (isReqRes) {
-    const kind = msgLower.includes('[request]') ? 'REQUEST' : 'RESPONSE'
-    if (traceId && spanId) return `r|${serviceName}|${traceId}|${spanId}|${kind}`
+    const kind = msgLower.startsWith('[request]')
+      ? 'REQUEST'
+      : msgLower.startsWith('[response]')
+        ? 'RESPONSE'
+        : (msgLower.includes('[request]') ? 'REQUEST' : 'RESPONSE')
+    const httpFp = _httpClientDedupeFingerprint(logEntry)
+    if (httpFp) {
+      if (traceId) return `rh|${serviceName}|${traceId}|${httpFp}`
+      const requestId = (logEntry.requestId != null ? String(logEntry.requestId).trim() : '') || ''
+      if (requestId) return `rh|${serviceName}|${requestId}|${httpFp}`
+      return null
+    }
+    if (traceId && spanId) return `r|${serviceName}|${traceId}|${spanId}|${kind}|${msgSig}`
     const ts = logEntry['@timestamp'] != null ? Number(logEntry['@timestamp']) : Date.now()
     const bucket = Math.floor(ts / _logDedupeBucketMs) * _logDedupeBucketMs
-    return `r|${serviceName}|${bucket}|${kind}`
+    return `r|${serviceName}|${bucket}|${kind}|${msgSig}`
   }
   if (traceId && spanId) return `t|${serviceName}|${traceId}|${spanId}|${msg}`
   const requestId = (logEntry.requestId != null ? String(logEntry.requestId).trim() : '') || ''
-  if (!requestId) return null
+  if (!requestId) {
+    const ts = logEntry['@timestamp'] != null ? Number(logEntry['@timestamp']) : Date.now()
+    const bucket = Math.floor(ts / _logDedupeGenericBucketMs) * _logDedupeGenericBucketMs
+    const msgSig = msg.length > 200 ? msg.slice(0, 200) : msg
+    return `g|${serviceName}|${bucket}|${msgSig}`
+  }
   const ts = logEntry['@timestamp'] != null ? Number(logEntry['@timestamp']) : Date.now()
   const bucket = Math.floor(ts / _logDedupeBucketMs) * _logDedupeBucketMs
   return `b|${serviceName}|${requestId}|${msg}|${bucket}`

package/store.d.ts

@@ -0,0 +1,68 @@
+export type AzifyRequestContext = {
+  traceId: string
+  spanId: string
+  parentSpanId: string | null
+  requestId: string | null
+}
+
+export type AzifyJobTraceRecord = {
+  traceId: string
+  spanId?: string | null
+  parentSpanId?: string | null
+  requestId?: string | null
+}
+
+export declare const AZIFY_JOB_TRACE_FIELD: '__azifyTraceContext'
+
+export function prepareBullJobTraceContext(data: unknown): {
+  cleanedForLog: unknown
+  ctx: AzifyRequestContext
+  dataForDownstream: unknown
+}
+
+export function captureOriginTraceMeta(): {
+  originTraceId?: string
+  originRequestId?: string
+}
+
+export function addCurrentTraceToBullJobPayload<T>(data: T): T
+
+export function traceAttachmentForBullJob(): Record<string, unknown>
+
+export function runBullJobHandlerInTraceContext<TJob extends { data: unknown }, R>(
+  job: TJob,
+  handler: (job: TJob) => R,
+): R
+
+export function runInBullJobTraceContext<T>(
+  jobData: unknown,
+  fn: (x: {
+    ctx: AzifyRequestContext
+    cleanedForLog: unknown
+    dataForDownstream: unknown
+  }) => T,
+): T
+
+export function runNestBullJobWithTrace<TJob extends { data: unknown }, R>(
+  job: TJob,
+  fn: (x: {
+    job: TJob
+    ctx: AzifyRequestContext
+    cleanedForLog: unknown
+    dataForDownstream: unknown
+  }) => R,
+): R
+
+export function startRequestContext(
+  initial?: Record<string, unknown>,
+): AzifyRequestContext
+export function runWithRequestContext<T>(ctx: AzifyRequestContext, fn: () => T): T
+export function getRequestContext(): AzifyRequestContext | null
+export function getActiveRequestId(): string | null
+export function getLastJobContext(): AzifyRequestContext | null
+export function setLastJobContext(ctx: AzifyRequestContext | null): void
+export function mergeTraceIntoJobPayload(
+  data: unknown,
+  traceContext: AzifyJobTraceRecord | null,
+): unknown
+export function toTraceIdHex(hex32: string | null | undefined): string

package/store.js

@@ -1,5 +1,7 @@
 const { AsyncLocalStorage } = require('async_hooks')
 
+const AZIFY_JOB_TRACE_FIELD = '__azifyTraceContext'
+
 const als = new AsyncLocalStorage()
 let lastJobContext = null
 
@@ -21,6 +23,16 @@ function fastGenerateId(length = 16) {
   return result
 }
 
+function newRequestIdForJob() {
+  try {
+    const { randomUUID } = require('crypto')
+    if (typeof randomUUID === 'function') {
+      return randomUUID()
+    }
+  } catch (_) {}
+  return `${fastGenerateId(16)}-${fastGenerateId(8)}`
+}
+
 function toTraceIdHex(hex32) {
   const raw = hex32 != null && typeof hex32 === 'string' ? String(hex32).replace(/[^0-9a-fA-F]/g, '').slice(0, 32) : ''
   const hex = raw || fastGenerateId(16)
@@ -47,6 +59,29 @@ function getRequestContext() {
   return als.getStore() || null
 }
 
+function getActiveRequestId() {
+  const ctx = getRequestContext()
+  if (!ctx?.requestId || String(ctx.requestId) === '') return null
+  return String(ctx.requestId)
+}
+
+function captureOriginTraceMeta() {
+  try {
+    const ctx = getRequestContext() || getLastJobContext()
+    if (!ctx || typeof ctx !== 'object') return {}
+    const out = {}
+    if (ctx.traceId != null && String(ctx.traceId) !== '') {
+      out.originTraceId = String(ctx.traceId)
+    }
+    if (ctx.requestId != null && String(ctx.requestId) !== '') {
+      out.originRequestId = String(ctx.requestId)
+    }
+    return out
+  } catch (_) {
+    return {}
+  }
+}
+
 function mergeTraceIntoJobPayload(data, traceContext) {
   if (!traceContext || !traceContext.traceId) return data
   const base = data && typeof data === 'object' && !Array.isArray(data) ? data : {}
@@ -59,14 +94,132 @@ function mergeTraceIntoJobPayload(data, traceContext) {
   }
 }
 
+function normalizedJobTrace(raw) {
+  if (!raw || typeof raw !== 'object' || typeof raw.traceId !== 'string') return null
+  return {
+    traceId: String(raw.traceId),
+    spanId: raw.spanId != null ? raw.spanId : null,
+    parentSpanId: raw.parentSpanId != null ? raw.parentSpanId : null,
+    requestId: raw.requestId != null && raw.requestId !== '' ? String(raw.requestId) : null
+  }
+}
+
+function alsContextFromJobTrace(trace) {
+  const fallbackRid = newRequestIdForJob()
+  if (!trace) {
+    return startRequestContext({ requestId: fallbackRid })
+  }
+  const traceHex = String(trace.traceId).replace(/[^0-9a-fA-F]/g, '').slice(0, 32)
+  const spanHex = trace.spanId
+    ? String(trace.spanId).replace(/[^0-9a-fA-F]/g, '').slice(0, 16)
+    : undefined
+  return startRequestContext({
+    traceHex: traceHex || undefined,
+    spanHex: spanHex || undefined,
+    parentSpanId: trace.parentSpanId != null && trace.parentSpanId !== '' ? String(trace.parentSpanId) : undefined,
+    requestId: trace.requestId || fallbackRid
+  })
+}
+
+function captureTraceForJobEnqueue() {
+  try {
+    const ctx = getRequestContext() || getLastJobContext()
+    if (!ctx || typeof ctx !== 'object' || ctx.traceId == null || String(ctx.traceId) === '') {
+      return null
+    }
+    return normalizedJobTrace({
+      traceId: String(ctx.traceId),
+      spanId: ctx.spanId,
+      parentSpanId: ctx.parentSpanId,
+      requestId: ctx.requestId
+    })
+  } catch (_) {
+    return null
+  }
+}
+
+function attachTraceToBullJobData(data, traceRecord) {
+  if (!traceRecord || !traceRecord.traceId) return data
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return data
+  return {
+    ...data,
+    [AZIFY_JOB_TRACE_FIELD]: traceRecord
+  }
+}
+
+function addCurrentTraceToBullJobPayload(data) {
+  const trace = captureTraceForJobEnqueue()
+  if (!trace) return data
+  return attachTraceToBullJobData(data, trace)
+}
+
+function traceAttachmentForBullJob() {
+  const trace = captureTraceForJobEnqueue()
+  if (!trace) return {}
+  return { [AZIFY_JOB_TRACE_FIELD]: trace }
+}
+
+function prepareBullJobTraceContext(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    const ctx = alsContextFromJobTrace(null)
+    return { cleanedForLog: data, ctx, dataForDownstream: data }
+  }
+  const rawTrace = data[AZIFY_JOB_TRACE_FIELD]
+  const hasKey = Object.prototype.hasOwnProperty.call(data, AZIFY_JOB_TRACE_FIELD)
+  let cleaned
+  if (hasKey) {
+    const copy = { ...data }
+    delete copy[AZIFY_JOB_TRACE_FIELD]
+    cleaned = copy
+  } else {
+    cleaned = { ...data }
+  }
+  const trace = normalizedJobTrace(rawTrace)
+  const ctx = alsContextFromJobTrace(trace)
+  const dataForDownstream = trace
+    ? { ...cleaned, [AZIFY_JOB_TRACE_FIELD]: trace }
+    : cleaned
+  return { cleanedForLog: cleaned, ctx, dataForDownstream }
+}
+
+function runBullJobHandlerInTraceContext(job, handler) {
+  const { ctx, cleanedForLog } = prepareBullJobTraceContext(job.data)
+  const nextJob =
+    cleanedForLog !== job.data ? { ...job, data: cleanedForLog } : job
+  return runWithRequestContext(ctx, () => handler(nextJob))
+}
+
+function runInBullJobTraceContext(jobData, fn) {
+  const { ctx, cleanedForLog, dataForDownstream } =
+    prepareBullJobTraceContext(jobData)
+  return runWithRequestContext(ctx, () =>
+    fn({ ctx, cleanedForLog, dataForDownstream }),
+  )
+}
+
+function runNestBullJobWithTrace(job, fn) {
+  return runInBullJobTraceContext(job.data, (bundle) =>
+    fn({ job, ...bundle }),
+  )
+}
+
 module.exports = {
   als,
+  AZIFY_JOB_TRACE_FIELD,
   startRequestContext,
   runWithRequestContext,
   getRequestContext,
+  getActiveRequestId,
   getLastJobContext,
   setLastJobContext,
   mergeTraceIntoJobPayload,
+  prepareBullJobTraceContext,
+  runBullJobHandlerInTraceContext,
+  runInBullJobTraceContext,
+  runNestBullJobWithTrace,
+  addCurrentTraceToBullJobPayload,
+  traceAttachmentForBullJob,
+  captureOriginTraceMeta,
   toTraceIdHex
 }