fastify-xlogger

createJobContext(params)

Create a correlated child logger for background jobs with start, complete, and fail helpers.

createJobContext(params)

Creates a Pino child logger bound to a correlation ID and job name. Provides start(), complete(), and fail() helpers that emit structured job.started, job.completed, and job.failed events. Use this to correlate background job logs back to the originating request.

Signature

fastify.xlogger.createJobContext(params: {
  jobName: string
  requestId?: string
  orgId?: string
  userId?: string
  correlationId?: string
}): {
  context: object
  log: pino.Logger
  start(data?: object): void
  complete(data?: object): void
  fail(err: Error, data?: object): void
}

Params

Name	Type	Required	Default	Description
`jobName`	`string`	Yes	—	Job name included on every log entry
`requestId`	`string`	No	—	Original request ID to correlate back to the HTTP request
`orgId`	`string`	No	—	Organization ID
`userId`	`string`	No	—	User ID
`correlationId`	`string`	No	Auto-generated	Stable ID for this job run; generated as `job_{timestamp}_{random}` if not provided

Returns

Property	Type	Description
`context`	`object`	The correlation context object (correlationId, jobName, etc.)
`log`	`pino.Logger`	Child logger with all context fields bound
`start(data?)`	`function`	Emits `job.started` at `info` level
`complete(data?)`	`function`	Emits `job.completed` at `info` level
`fail(err, data?)`	`function`	Emits `job.failed` at `error` level with the error

Throws

Error: [xLogger] createJobContext requires a string 'jobName' parameter

Examples

Basic background job with lifecycle logging

fastify.post("/emails/send-digest", async (request) => {
  const job = fastify.xlogger.createJobContext({
    jobName: "sendDigestEmail",
    requestId: request.id,
    userId: request.user.id,
  });

  // Hand off to background processing
  setImmediate(async () => {
    job.start({ recipientCount: users.length });

    try {
      await sendDigestEmails(users);
      job.complete({ sent: users.length });
    } catch (err) {
      job.fail(err, { failedAt: "sendDigestEmails" });
    }
  });

  return { queued: true };
});

Correlate with a queue worker

async function processQueueMessage(message) {
  const job = fastify.xlogger.createJobContext({
    jobName: "processOrder",
    requestId: message.headers["x-request-id"],
    orgId: message.body.orgId,
    correlationId: message.headers["x-correlation-id"],
  });

  job.start({ orderId: message.body.orderId });

  try {
    await fulfillOrder(message.body.orderId);
    job.complete({ orderId: message.body.orderId });
  } catch (err) {
    job.fail(err);
  }
}

AI Context

package: "@xenterprises/fastify-xlogger"
method: fastify.xlogger.createJobContext(params)
use-when: Structured logging for background jobs with start/complete/fail lifecycle events and correlation back to the originating request
params: jobName (required), requestId, orgId, userId, correlationId
returns: { context, log, start(data?), complete(data?), fail(err, data?) }

Edit this pageorReport an issue

createBoundaryLogger(vendor, operation, request?)

Create a timed boundary logger that automatically captures call duration.

extractContext(request)

Extract the canonical request context object from a Fastify request.