sharedriver

package
v0.0.0-...-c4f087e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 22 Imported by: 1

Documentation

Index

Constants

View Source
const (
	PriorityUrgent int = 1
	PriorityHigh   int = 2
	PriorityNormal int = 3
	PriorityLow    int = 4
)

Variables

View Source
var ActiveJobStates = []string{"available", "pending", "retryable", "running", "scheduled"}

ActiveJobStates are the states of a job River has not finished with.

Functions

func NewLogger

func NewLogger(l logger.Logger) *slog.Logger

NewLogger returns the logger to set as river.Config.Logger, so River's own lines reach the service logger instead of River's default text handler on stdout. It keeps that default's Warn threshold: below it River reports every failed attempt, which OutboxJobTelemetry already logs with the attempt count, and routine maintenance.

func NewOTelMiddleware

func NewOTelMiddleware(tel *telemetry.Client) *otelriver.Middleware

NewOTelMiddleware returns the River plugin every River client installs: insert and work spans suffixed with the job kind, and trace context carried from the insert into the job's metadata so the work span links back to the transaction that enqueued it.

The OpenTelemetry messaging semantic-convention metrics stay off: they duplicate every river.* measurement under messaging.* with only the operation name as a label, so nothing can read them per kind or queue.

func SkipWhen

func SkipWhen(reason string, targets ...error) func(error) string

SkipWhen reports a step as skipped for reason when its error is any of the targets.

Types

type Backlog

type Backlog struct {
	// contains filtered or unexported fields
}

Backlog reports a River outbox's unfinished and discarded jobs from a snapshot it reads every Interval, so an export never waits on the database. Every replica reads the same rows: aggregate its gauges with max, not sum. outbox.snapshot_age says how old the snapshot an export reported is.

func NewBacklog

func NewBacklog(pool *pgxpool.Pool, tel *telemetry.Client, l logger.Logger, config BacklogConfig) (*Backlog, error)

func (*Backlog) Start

func (b *Backlog) Start(ctx context.Context)

Start reads the backlog now and then every Interval until Stop.

func (*Backlog) Stop

func (b *Backlog) Stop()

type BacklogConfig

type BacklogConfig struct {
	// Schema is the schema River's tables live in.
	Schema string
	// Kinds are the job kinds the service works. Each is reported at zero
	// when it has no jobs, so an empty backlog still returns series and no
	// series means the read stopped. A kind outside the list is reported only
	// while it has jobs.
	Kinds []string
	// QueueClass groups queues into a bounded label, or "default" when nil.
	QueueClass func(queue string) string
	// QueueClasses are the classes QueueClass returns, each reported at zero.
	QueueClasses []string
	// Interval is how often the backlog is read.
	Interval time.Duration
}

type JobSteps

type JobSteps struct {
	// contains filtered or unexported fields
}

JobSteps reports the steps of one job kind. Its zero value runs every operation and reports nothing.

func (JobSteps) Skipped

func (j JobSteps) Skipped(ctx context.Context, name, reason string, subject ...zap.Field)

Skipped reports a step the job decided not to run. An empty reason is reported without one.

func (JobSteps) Step

func (j JobSteps) Step(ctx context.Context, name string, operation func(context.Context) error) error

func (JobSteps) StepWith

func (j JobSteps) StepWith(ctx context.Context, name string, options StepOptions, operation func(context.Context) error) error

func (JobSteps) StepWithSkip

func (j JobSteps) StepWithSkip(ctx context.Context, name string, operation func(context.Context) (bool, error)) (bool, error)

StepWithSkip runs a step whose operation reports for itself that it had nothing to do.

type OutboxJobTelemetry

type OutboxJobTelemetry struct {
	river.MiddlewareDefaults
	// contains filtered or unexported fields
}

OutboxJobTelemetry counts every job a River outbox finishes, by kind and by the outcome River gave it, and logs once each attempt that did not complete. River's own river.work_count carries the attempt but not the maximum, so nothing in it separates a job that will be retried from one that has failed for the last time — which is the outcome worth alerting on.

func NewOutboxJobTelemetry

func NewOutboxJobTelemetry(tel *telemetry.Client, l logger.Logger) *OutboxJobTelemetry

NewOutboxJobTelemetry returns the worker middleware to install in river.Config.Middleware. The counter is named for the outbox rather than for a service, so one query covers every service that installs it; the resource attributes each exports say whose outbox reported the point.

func (*OutboxJobTelemetry) Work

func (t *OutboxJobTelemetry) Work(ctx context.Context, job *rivertype.JobRow, doInner func(context.Context) error) error

Work records the outcome from a defer, the way otelriver does: a panicking worker is counted and the panic still reaches River, which is what turns the job into an error River can retry or discard. Every line logged during the attempt names the job and the attempt, so one job's retries can be read together.

type StepOptions

type StepOptions struct {
	// SkipReason turns an error into a skip with that reason when it returns
	// one. The step still returns the error: what a skip means for the job is
	// the worker's call.
	SkipReason func(error) string
	// Subject names what the step acted on, on every line it logs.
	Subject []zap.Field
}

type Steps

type Steps struct {
	// contains filtered or unexported fields
}

Steps reports each effect an outbox job performs — a publish, a remote call, the write that records it — as a child span of the job's work span, a count and a duration, and a log line. Errors stay off the span: their text can carry customer data, so only the log line holds it. Inside a job run by OutboxJobTelemetry, a failed or skipped step leaves its line to the middleware, which logs it once with the attempt's outcome.

func NewSteps

func NewSteps(tel *telemetry.Client, l logger.Logger, config StepsConfig) *Steps

func (*Steps) Job

func (s *Steps) Job(kind string) JobSteps

Job returns the steps of one job kind. On a nil Steps they report nothing.

type StepsConfig

type StepsConfig struct {
	// MetricPrefix names the service's step metrics,
	// <prefix>.outbox.steps.finished and <prefix>.outbox.step.duration.
	MetricPrefix string
	// ErrorClass names the class of a failure the service recognises, or
	// returns "" to leave it unknown. A deadline is always a timeout.
	ErrorClass func(error) string
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL