pg-boss 12.35.0 → 12.36.0

package/dist/telemetry.js

@@ -0,0 +1,349 @@
+import { context, defaultTextMapGetter, defaultTextMapSetter, metrics, propagation, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+import packageJson from '../package.json' with { type: 'json' };
+// The OpenTelemetry messaging semantic conventions, copied rather than imported: the messaging
+// attributes still live in the unstable "incubating" entry point of @opentelemetry/semantic-conventions,
+// which is not meant to be depended on by libraries.
+// https://opentelemetry.io/docs/specs/semconv/messaging/
+export const ATTR = {
+    messagingSystem: 'messaging.system',
+    operationName: 'messaging.operation.name',
+    operationType: 'messaging.operation.type',
+    destinationName: 'messaging.destination.name',
+    messageId: 'messaging.message.id',
+    batchMessageCount: 'messaging.batch.message_count',
+    errorType: 'error.type',
+    dbNamespace: 'db.namespace',
+    schema: 'pgboss.schema',
+    retryCount: 'pgboss.job.retry_count',
+    jobState: 'pgboss.job.state'
+};
+export const METRIC = {
+    operationDuration: 'messaging.client.operation.duration',
+    sentMessages: 'messaging.client.sent.messages',
+    consumedMessages: 'messaging.client.consumed.messages',
+    processDuration: 'messaging.process.duration',
+    queueJobs: 'pgboss.queue.jobs'
+};
+export const MESSAGING_SYSTEM = 'pg-boss';
+export const INSTRUMENTATION_SCOPE = 'pg-boss';
+// The bucket boundaries the messaging conventions recommend for their duration histograms.
+const DURATION_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10];
+function errorType(err) {
+    if (err instanceof Error)
+        return err.constructor.name;
+    return '_OTHER';
+}
+function spanName(operation, destination) {
+    return destination ? `${operation} ${destination}` : operation;
+}
+function metricAttributes(attributes, err) {
+    const { [ATTR.messageId]: _id, [ATTR.batchMessageCount]: _count, [ATTR.retryCount]: _retry, ...rest } = attributes;
+    return err === undefined ? rest : { ...rest, [ATTR.errorType]: errorType(err) };
+}
+function recordError(span, err) {
+    span.setAttribute(ATTR.errorType, errorType(err));
+    if (err instanceof Error) {
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+    }
+}
+function seconds(startedAt) {
+    return (performance.now() - startedAt) / 1000;
+}
+class Telemetry {
+    enabled;
+    #propagate;
+    #propagator;
+    #schema;
+    #namespace;
+    #tracer;
+    #meterProvider;
+    #queues;
+    #instrumentsFor = null;
+    #instruments = null;
+    #observing = false;
+    constructor(options = {}, schema, queues) {
+        this.enabled = options.enabled !== false;
+        this.#propagate = this.enabled && options.propagateContext === true;
+        this.#propagator = options.propagator ?? propagation;
+        this.#schema = schema;
+        this.#namespace = { [ATTR.schema]: schema };
+        this.#tracer = (options.tracerProvider ?? trace.getTracerProvider()).getTracer(INSTRUMENTATION_SCOPE, packageJson.version);
+        this.#meterProvider = options.meterProvider;
+        this.#queues = queues;
+    }
+    // db.namespace follows the PostgreSQL convention, {database}|{schema}, so the same schema in two
+    // databases stays apart. The database is only known once start() has asked for it.
+    setDatabase(database) {
+        this.#namespace = { [ATTR.dbNamespace]: `${database}|${this.#schema}`, [ATTR.schema]: this.#schema };
+    }
+    #baseAttributes(operation, type, destination) {
+        const attributes = {
+            [ATTR.messagingSystem]: MESSAGING_SYSTEM,
+            [ATTR.operationName]: operation,
+            [ATTR.operationType]: type,
+            ...this.#namespace
+        };
+        if (destination)
+            attributes[ATTR.destinationName] = destination;
+        return attributes;
+    }
+    // The global meter provider has no proxy the way the tracer provider does: a meter taken before
+    // an SDK registers stays a no-op forever. Resolving the provider on every use and rebuilding the
+    // instruments when it changes is what lets an SDK started after pg-boss still receive metrics.
+    #getInstruments() {
+        if (!this.enabled)
+            return null;
+        const provider = this.#meterProvider ?? metrics.getMeterProvider();
+        if (provider === this.#instrumentsFor && this.#instruments)
+            return this.#instruments;
+        this.#instruments?.queueJobs.removeCallback(this.#observeQueues);
+        const meter = provider.getMeter(INSTRUMENTATION_SCOPE, packageJson.version);
+        this.#instrumentsFor = provider;
+        this.#instruments = {
+            operationDuration: meter.createHistogram(METRIC.operationDuration, {
+                description: 'Duration of messaging operation initiated by a producer or consumer client.',
+                unit: 's',
+                advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+            }),
+            sentMessages: meter.createCounter(METRIC.sentMessages, {
+                description: 'Number of messages producer attempted to send to the broker.',
+                unit: '{message}'
+            }),
+            consumedMessages: meter.createCounter(METRIC.consumedMessages, {
+                description: 'Number of messages that were delivered to the application.',
+                unit: '{message}'
+            }),
+            processDuration: meter.createHistogram(METRIC.processDuration, {
+                description: 'Duration of processing operation.',
+                unit: 's',
+                advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+            }),
+            queueJobs: meter.createObservableGauge(METRIC.queueJobs, {
+                description: 'Jobs in a queue by state, as of the last queue cache refresh.',
+                unit: '{job}'
+            })
+        };
+        if (this.#observing) {
+            this.#instruments.queueJobs.addCallback(this.#observeQueues);
+        }
+        return this.#instruments;
+    }
+    #observeQueues = (result) => {
+        const queues = this.#queues();
+        if (!queues)
+            return;
+        for (const queue of Object.values(queues)) {
+            const attributes = { [ATTR.messagingSystem]: MESSAGING_SYSTEM, [ATTR.destinationName]: queue.name, ...this.#namespace };
+            result.observe(queue.deferredCount ?? 0, { ...attributes, [ATTR.jobState]: 'deferred' });
+            result.observe(queue.readyCount ?? 0, { ...attributes, [ATTR.jobState]: 'ready' });
+            result.observe(queue.blockedCount ?? 0, { ...attributes, [ATTR.jobState]: 'blocked' });
+            result.observe(queue.activeCount ?? 0, { ...attributes, [ATTR.jobState]: 'active' });
+            result.observe(queue.failedCount ?? 0, { ...attributes, [ATTR.jobState]: 'failed' });
+        }
+    };
+    // Starts reporting pgboss.queue.jobs from the queue cache. Called by start(), undone by stop().
+    observeQueues() {
+        if (!this.enabled || this.#observing)
+            return;
+        this.#observing = true;
+        this.#getInstruments()?.queueJobs.addCallback(this.#observeQueues);
+    }
+    unobserveQueues() {
+        if (!this.#observing)
+            return;
+        this.#observing = false;
+        this.#instruments?.queueJobs.removeCallback(this.#observeQueues);
+    }
+    // Moves the queue gauge to a meter provider registered after start(), which otherwise waits for
+    // the next send, fetch or settle. Called on each queue cache refresh.
+    refreshInstruments() {
+        if (this.#observing)
+            this.#getInstruments();
+    }
+    /**
+     * Runs a job-creating operation in a PRODUCER span and hands `fn` the trace context to store on
+     * each job it inserts, or null when there is nothing to propagate. `attempted` is the number of
+     * jobs it creates itself, counted whether or not they land. A function instead counts from the
+     * result, and counts nothing when `fn` throws.
+     */
+    async send(operation, destination, attempted, fn, idsOf = () => null) {
+        if (!this.enabled)
+            return fn(null);
+        const attributes = this.#baseAttributes(operation, 'send', destination);
+        if (typeof attempted === 'number' && attempted > 1)
+            attributes[ATTR.batchMessageCount] = attempted;
+        const span = this.#tracer.startSpan(spanName(operation, destination), { kind: SpanKind.PRODUCER, attributes });
+        const spanContext = trace.setSpan(context.active(), span);
+        const startedAt = performance.now();
+        let carrier = null;
+        if (this.#propagate) {
+            const injected = {};
+            this.#propagator.inject(spanContext, injected, defaultTextMapSetter);
+            carrier = Object.keys(injected).length > 0 ? injected : null;
+        }
+        try {
+            const result = await context.with(spanContext, () => fn(carrier));
+            const ids = idsOf(result);
+            const sent = typeof attempted === 'number' ? attempted : attempted(result);
+            if (sent === 1 && ids?.length === 1) {
+                span.setAttribute(ATTR.messageId, ids[0]);
+            }
+            this.#recordSend(startedAt, sent, metricAttributes(attributes));
+            return result;
+        }
+        catch (err) {
+            recordError(span, err);
+            this.#recordSend(startedAt, typeof attempted === 'number' ? attempted : 0, metricAttributes(attributes, err));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    #recordSend(startedAt, attempted, attributes) {
+        const instruments = this.#getInstruments();
+        instruments?.operationDuration.record(seconds(startedAt), attributes);
+        if (attempted > 0)
+            instruments?.sentMessages.add(attempted, attributes);
+    }
+    /**
+     * Wraps a fetch() the application made itself in a CLIENT `receive` span, linked to the send of
+     * every job it returned.
+     */
+    async receive(destination, fn, carrierOf) {
+        if (!this.enabled)
+            return fn();
+        const attributes = this.#baseAttributes('receive', 'receive', destination);
+        const span = this.#tracer.startSpan(spanName('receive', destination), { kind: SpanKind.CLIENT, attributes });
+        const startedAt = performance.now();
+        try {
+            const jobs = await context.with(trace.setSpan(context.active(), span), fn);
+            if (jobs.length === 1) {
+                span.setAttribute(ATTR.messageId, jobs[0].id);
+            }
+            else {
+                span.setAttribute(ATTR.batchMessageCount, jobs.length);
+            }
+            span.addLinks(this.#links(jobs, carrierOf));
+            const instruments = this.#getInstruments();
+            instruments?.operationDuration.record(seconds(startedAt), metricAttributes(attributes));
+            if (jobs.length > 0)
+                instruments?.consumedMessages.add(jobs.length, metricAttributes(attributes));
+            return jobs;
+        }
+        catch (err) {
+            recordError(span, err);
+            this.#getInstruments()?.operationDuration.record(seconds(startedAt), metricAttributes(attributes, err));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    // Jobs a worker claimed. The worker's own fetch has no span: it polls on a timer, and a span per
+    // empty poll would bury the traces that matter. The process span covers what it delivers.
+    consumed(destination, count) {
+        if (count === 0)
+            return;
+        this.#getInstruments()?.consumedMessages.add(count, metricAttributes(this.#baseAttributes('process', 'process', destination)));
+    }
+    /**
+     * Runs a worker's handler over a batch in a CONSUMER `process` span. A batch of one continues the
+     * trace its send() started; a larger batch starts a trace of its own and links to every send.
+     *
+     * `fn` resolves with the error the batch failed with, or undefined when it completed, because the
+     * worker settles a failed batch itself rather than letting the error escape.
+     */
+    async process(destination, jobs, carrierOf, fn) {
+        if (!this.enabled) {
+            await fn();
+            return;
+        }
+        const attributes = this.#baseAttributes('process', 'process', destination);
+        let parent = ROOT_CONTEXT;
+        let links = [];
+        if (jobs.length === 1) {
+            attributes[ATTR.messageId] = jobs[0].id;
+            if (jobs[0].retryCount !== undefined)
+                attributes[ATTR.retryCount] = jobs[0].retryCount;
+            // The whole extracted context, so baggage sent with the job reaches the handler too.
+            const carrier = carrierOf(jobs[0]);
+            if (carrier)
+                parent = this.#extract(carrier);
+        }
+        else {
+            attributes[ATTR.batchMessageCount] = jobs.length;
+            links = this.#links(jobs, carrierOf);
+        }
+        // The parent is chosen explicitly, never taken from context.active(): the worker loop inherits
+        // whatever context work() was called in, and a job has nothing to do with that caller's trace.
+        const span = this.#tracer.startSpan(spanName('process', destination), { kind: SpanKind.CONSUMER, attributes, links }, parent);
+        const startedAt = performance.now();
+        let failure;
+        try {
+            failure = await context.with(trace.setSpan(parent, span), fn);
+        }
+        catch (err) {
+            failure = err ?? new Error('undefined error');
+            throw err;
+        }
+        finally {
+            if (failure !== undefined)
+                recordError(span, failure);
+            this.#getInstruments()?.processDuration.record(seconds(startedAt), metricAttributes(attributes, failure));
+            span.end();
+        }
+    }
+    /**
+     * Wraps a call that settles or removes jobs (complete, fail, cancel, deleteJob) in a CLIENT span.
+     */
+    async settle(operation, destination, ids, fn) {
+        if (!this.enabled)
+            return fn();
+        const attributes = this.#baseAttributes(operation, 'settle', destination);
+        if (ids.length === 1) {
+            attributes[ATTR.messageId] = ids[0];
+        }
+        else {
+            attributes[ATTR.batchMessageCount] = ids.length;
+        }
+        const span = this.#tracer.startSpan(spanName(operation, destination), { kind: SpanKind.CLIENT, attributes });
+        const startedAt = performance.now();
+        try {
+            const result = await context.with(trace.setSpan(context.active(), span), fn);
+            this.#getInstruments()?.operationDuration.record(seconds(startedAt), metricAttributes(attributes));
+            return result;
+        }
+        catch (err) {
+            recordError(span, err);
+            this.#getInstruments()?.operationDuration.record(seconds(startedAt), metricAttributes(attributes, err));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    #links(jobs, carrierOf) {
+        const links = [];
+        for (const job of jobs) {
+            const spanContext = this.#extractSpanContext(carrierOf(job));
+            if (spanContext)
+                links.push({ context: spanContext });
+        }
+        return links;
+    }
+    #extract(carrier) {
+        return this.#propagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
+    }
+    #extractSpanContext(carrier) {
+        if (!carrier)
+            return null;
+        const spanContext = trace.getSpanContext(this.#extract(carrier));
+        return spanContext && trace.isSpanContextValid(spanContext) ? spanContext : null;
+    }
+}
+export default Telemetry;

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { MeterProvider, TextMapPropagator, TracerProvider } from '@opentelemetry/api';
 export type JobStates = {
     created: 'created';
     retry: 'retry';
@@ -50,6 +51,18 @@ export interface IDatabase {
      * does not implement this.
      */
     setSessionStatements?(statements: string[]): Promise<void>;
+    /**
+     * Optional capability for the instance registry: the pool's size and use, recorded on each
+     * heartbeat. The built-in pool-based Db implements it; without it the pool columns stay null.
+     */
+    poolCounts?(): PoolCounts | null;
+}
+/** A connection pool's size and use at one moment, as node-postgres counts them. */
+export interface PoolCounts {
+    max: number;
+    total: number;
+    idle: number;
+    waiting: number;
 }
 export interface ListenHandle {
     close(): Promise<void>;
@@ -255,8 +268,30 @@ export interface QueueStats {
     deltaSeconds: number | null;
     /** When the interval the deltas cover ends, 10 seconds behind `capturedOn`. Plot the deltas at this time. */
     deltaOn: Date | null;
+    /**
+     * Wait times of the jobs that finished in the deltas' window, as a histogram of 48 counts in
+     * log-spaced bins; sum histograms to read a percentile over any span. Null wherever the deltas are.
+     * @see https://pgboss.io/api/queues#getqueues-names
+     */
+    waitBins: number[] | null;
+    /** Run times of the same jobs, in the same bins as `waitBins`. */
+    runBins: number[] | null;
+    /** How long the oldest job ready to run had waited when the snapshot was captured. */
+    readyOldestSeconds: number | null;
+    /**
+     * With the `percentiles` option: one entry per percentile asked for, read from `waitBins` and `runBins`.
+     * @see https://pgboss.io/api/queues#getqueuestats-name-options
+     */
+    percentiles?: QueueStatsPercentile[];
     capturedOn: Date;
 }
+/** One percentile of a snapshot's wait and run times, in seconds. Null where the snapshot has no histograms. */
+export interface QueueStatsPercentile {
+    /** The percentile asked for, from 1 to 100. */
+    p: number;
+    waitSeconds: number | null;
+    runSeconds: number | null;
+}
 export interface QueueStatsOptions {
     /** persistQueueStats on: only return snapshots captured at or after this time. */
     from?: Date;
@@ -288,6 +323,12 @@ export interface QueueStatsOptions {
      * @default 'max'
      */
     aggregate?: 'max' | 'min' | 'avg';
+    /**
+     * Percentiles to read from each snapshot's wait and run histograms, as percents from 1 to 100, such
+     * as `[50, 95, 99.9]`. Each snapshot then carries a `percentiles` list, one entry per distinct value.
+     * @see https://pgboss.io/api/queues#getqueuestats-name-options
+     */
+    percentiles?: number[];
     /**
      * persistQueueStats off: return a fresh reading. Recomputes the counts from the job table and
      * refreshes the queue-table cache rather than serving the regular (up to ~1h) cache, but still
@@ -392,7 +433,57 @@ export interface AttachableClock extends Clock {
         idle?: () => Promise<boolean>;
     }): Promise<AsyncDisposable>;
 }
-export interface ConstructorOptions extends DatabaseOptions, SchedulingOptions, MaintenanceOptions, BackendOptions {
+export interface InstanceOptions {
+    /**
+     * Record this instance in the database's instance registry, readable with `getInstances()`.
+     * @see https://pgboss.io/api/ops#getinstances
+     * @default true
+     */
+    registerInstance?: boolean;
+    /**
+     * A name for this instance in the registry, such as `api` or `billing-worker`.
+     * @see https://pgboss.io/api/constructor#instancename
+     */
+    instanceName?: string;
+    /**
+     * How often this instance refreshes its registry row, in seconds. It reads as quiet after three
+     * missed heartbeats.
+     * @default 30
+     */
+    instanceHeartbeatSeconds?: number;
+}
+export interface OpenTelemetryOptions {
+    /**
+     * Set to false to emit no spans or metrics and store no trace context on jobs.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Store the trace context active at `send()` on the job, so the span that processes it continues
+     * the producer's trace. With the SDK's default propagators this stores W3C Baggage as well as the
+     * trace id; pass `propagator` to store less.
+     * @default false
+     * @see https://pgboss.io/opentelemetry#options
+     */
+    propagateContext?: boolean;
+    /**
+     * Propagator that writes the trace context stored on a job and reads it back when the job is
+     * processed, for example `new W3CTraceContextPropagator()` to store trace ids only.
+     * @default the propagator registered globally with the OpenTelemetry API
+     */
+    propagator?: TextMapPropagator;
+    /**
+     * Tracer provider to create pg-boss spans with.
+     * @default the global tracer provider
+     */
+    tracerProvider?: TracerProvider;
+    /**
+     * Meter provider to create pg-boss instruments with.
+     * @default the global meter provider
+     */
+    meterProvider?: MeterProvider;
+}
+export interface ConstructorOptions extends DatabaseOptions, SchedulingOptions, MaintenanceOptions, BackendOptions, InstanceOptions {
     /**
      * Source of time and timers for this instance. Defaults to the system clock (`Date.now` and the
      * global timer functions).
@@ -410,6 +501,12 @@ export interface ConstructorOptions extends DatabaseOptions, SchedulingOptions,
      * @default false
      */
     useListenNotify?: boolean;
+    /**
+     * OpenTelemetry tracing and metrics. On by default and free until an OpenTelemetry SDK is
+     * registered: without one every span and instrument is a no-op.
+     * @see https://pgboss.io/opentelemetry
+     */
+    openTelemetry?: OpenTelemetryOptions;
     /**
      * Enables job spies for deterministic testing (see `getSpy`). Adds per-transition
      * tracking overhead, **NOT for production.**
@@ -577,6 +674,10 @@ export interface RedrivePreview {
     unroutable: number;
 }
 export type InsertOptions = ConnectionOptions & {
+    /**
+     * Resolve to the ids of the inserted jobs instead of `null`. Defaults to `false`.
+     * @see https://pgboss.io/api/jobs#insert-name-job-options
+     */
     returnId?: boolean;
 };
 export type SendOptions = JobOptions & QueueOptions & ConnectionOptions;
@@ -685,11 +786,14 @@ export interface Queue extends QueueOptions {
     notify?: boolean;
 }
 export interface QueueResult extends Queue {
+    /** Queued jobs whose `startAfter` is still ahead and that are not blocked. */
     deferredCount: number;
+    /** Queued jobs waiting on a flow parent, whatever their `startAfter`. */
+    blockedCount: number;
     queuedCount: number;
     /**
-     * Jobs ready to be processed now: `queuedCount - deferredCount` (clamped at 0). This is the
-     * true backlog, `queuedCount` includes deferred (future-dated) jobs that are not yet runnable.
+     * Jobs ready to be processed now: queued, not deferred and not blocked, so `queuedCount` is
+     * `deferredCount + blockedCount + readyCount`.
      */
     readyCount: number;
     activeCount: number;
@@ -713,6 +817,12 @@ export interface QueueResult extends Queue {
     deltaSeconds: number | null;
     /** When that interval ends, 10 seconds behind the pass. See `QueueStats.deltaOn`. Null until a pass counts. */
     deltaOn: Date | null;
+    /** Wait times of the jobs counted in the deltas, as 48 counts. See `QueueStats.waitBins`. Null until a pass counts. */
+    waitBins: number[] | null;
+    /** Run times of the same jobs, in the same bins. Null until a pass counts. */
+    runBins: number[] | null;
+    /** How long the oldest ready job had waited at the pass. See `QueueStats.readyOldestSeconds`. Null until a pass counts. */
+    readyOldestSeconds: number | null;
     table: string;
     createdOn: Date;
     updatedOn: Date;
@@ -1092,6 +1202,94 @@ export interface WipData {
     lastError: object | null;
     lastErrorOn: number | null;
 }
+/** One `work()` call of a registered instance, as its last heartbeat recorded it. */
+export interface InstanceWorker {
+    /** The id `work()` returned. */
+    id: string;
+    queue: string;
+    localConcurrency: number;
+    batchSize: number;
+    pollingIntervalSeconds: number | null;
+    /** Jobs in hand at the heartbeat. */
+    active: number;
+    lastFetchedOn: string | null;
+    lastJobEndedOn: string | null;
+    lastErrorOn: string | null;
+    /**
+     * The other `work()` options this call set; one left at its default is absent.
+     * @see https://pgboss.io/api/ops#getinstances
+     */
+    options?: Partial<WorkOptions>;
+}
+/**
+ * A registered instance's process at its last heartbeat. Limits are its container's where one is set
+ * (cgroup v1 or v2), else the host's; rates cover the time since the previous heartbeat.
+ * @see https://pgboss.io/api/ops#getinstances
+ */
+export interface InstanceMetrics {
+    /** 1 or 2 when the limits were read from a cgroup, null when they are the host's. */
+    cgroup: 1 | 2 | null;
+    /** CPU cores this process used; null on the first sample. */
+    cpu: number | null;
+    /** Cores it may use: its container's CPU quota, or the CPUs it may run on. */
+    cpuLimit: number;
+    /** Share of CPU periods its container was throttled for, 0 to 1; null without a CPU quota. */
+    cpuThrottled: number | null;
+    /** Resident set size in bytes. */
+    rss: number | null;
+    heapUsed: number | null;
+    heapLimit: number | null;
+    /** Its container's working set in bytes; null without a memory limit. */
+    memoryUsed: number | null;
+    /** Its container's memory limit in bytes, or the host's total memory. */
+    memoryLimit: number;
+    /** Event loop delay, p99 and worst, in milliseconds. */
+    loopDelay: number | null;
+    loopDelayMax: number | null;
+    /** Share of the time the event loop was busy, 0 to 1. */
+    loopUtilization: number | null;
+}
+/**
+ * A PgBoss object that registered itself in this database.
+ * @see https://pgboss.io/api/ops#getinstances
+ */
+export interface Instance {
+    id: string;
+    name: string | null;
+    host: string;
+    pid: number;
+    /** pg-boss version. */
+    version: string;
+    nodeVersion: string;
+    /** The `application_name` its connections carry, for joining `pg_stat_activity`. */
+    applicationName: string | null;
+    heartbeatSeconds: number;
+    supervise: boolean;
+    schedule: boolean;
+    migrate: boolean;
+    persistQueueStats: boolean;
+    persistWarnings: boolean;
+    /** Pool counts at the last heartbeat; null for a pool pg-boss did not create. */
+    poolMax: number | null;
+    poolTotal: number | null;
+    poolIdle: number | null;
+    poolWaiting: number | null;
+    workers: InstanceWorker[];
+    /** Its process at the last heartbeat; null before the first sample. */
+    metrics: InstanceMetrics | null;
+    /** The options it runs with: timings, roles, retention and backend, never connection details. */
+    config: Record<string, unknown>;
+    /** Lives in a row on this name and host that ended without `stop()` before this one started. */
+    crashRestarts: number;
+    /** When the first of those crashed; null when there were none. */
+    crashRestartsSince: Date | null;
+    startedOn: Date;
+    heartbeatOn: Date;
+    /** Set by a graceful `stop()`; a crashed instance goes quiet instead. */
+    stoppedOn: Date | null;
+    /** Not stopped, and heard from within three heartbeats. */
+    live: boolean;
+}
 export interface StopOptions {
     close?: boolean;
     graceful?: boolean;