Documentation
¶
Index ¶
- Constants
- Variables
- func NewLogger(l logger.Logger) *slog.Logger
- func NewOTelMiddleware(tel *telemetry.Client) *otelriver.Middleware
- func SkipWhen(reason string, targets ...error) func(error) string
- type Backlog
- type BacklogConfig
- type JobSteps
- func (j JobSteps) Skipped(ctx context.Context, name, reason string, subject ...zap.Field)
- func (j JobSteps) Step(ctx context.Context, name string, operation func(context.Context) error) error
- func (j JobSteps) StepWith(ctx context.Context, name string, options StepOptions, ...) error
- func (j JobSteps) StepWithSkip(ctx context.Context, name string, ...) (bool, error)
- type OutboxJobTelemetry
- type StepOptions
- type Steps
- type StepsConfig
Constants ¶
const ( PriorityUrgent int = 1 PriorityHigh int = 2 PriorityNormal int = 3 PriorityLow int = 4 )
Variables ¶
var ActiveJobStates = []string{"available", "pending", "retryable", "running", "scheduled"}
ActiveJobStates are the states of a job River has not finished with.
Functions ¶
func NewLogger ¶
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.
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 ¶
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 ¶
Skipped reports a step the job decided not to run. An empty reason is reported without one.
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.
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
}