OpenTelemetry Integration

Distributed tracing for Node.js task execution — one span per attempt.

Peer dependency: @opentelemetry/api. Import from the @byteveda/flexiq/contrib/otel subpath — it is not exported from the main barrel.

import { otelMiddleware } from "@byteveda/flexiq/contrib/otel";

queue.use(otelMiddleware());

One span (a single traced operation, OpenTelemetry's unit of work) is created per execution attempt, named flexiq.execute.<taskName>. The span ends with status OK on success and ERROR (with the exception recorded) on throw. A retry is a new attempt, so it produces a new span.

Span attributes

Attribute	Value
`flexiq.job_id`	The job's UUID
`flexiq.task_name`	Registered task name

Options

Option	Type	Default	Description
`tracerName`	`string`	`"flexiq"`	Name passed to `trace.getTracer()`
`attributePrefix`	`string`	`"flexiq"`	Prefix applied to span attribute keys
`spanName`	`(ctx) => string`	—	Override the span name per execution
`extraAttributes`	`(ctx) => Attributes`	—	Attach additional attributes to every span
`taskFilter`	`(taskName) => boolean`	—	Return `false` to skip tracing for a task

queue.use(
  otelMiddleware({
    tracerName: "my-service",
    attributePrefix: "app",
    spanName: (ctx) => `job.${ctx.taskName}`,
    extraAttributes: (ctx) => ({ "app.env": process.env.NODE_ENV ?? "dev" }),
    taskFilter: (name) => !name.startsWith("internal."),
  }),
);

otelMiddleware does not configure an exporter or a tracer provider. Set those up with the OpenTelemetry SDK before calling queue.runWorker().